Error handling in the Commerce Server version 3.0 site environment revolves around the OPP's interaction with the OrderForm, the MtsPipeline or MtsTxPipeline object, and the MessageManager object.
The OrderForm provides a detailed, in-memory summary of one or more shopping sessions, including merchant, customer, and item information. You pass an initialized OrderForm to the OPP by calling the OrderPipeline's OrderExecute method.
As the OrderForm is passed through various stages of the OPP, the components associated with each stage read and write various values to and from the OrderForm.
For purposes of error processing, the most crucial members of the OrderForm are its _Basket_Errors and _Purchase_Errors collections. These collections are intended to store strings that describe error conditions that the OPP detects while processing other elements of the OrderForm.
The OPP gets these strings from the MessageManager. The MessageManager is a site's central repository of locale-based error messages. Each message stored in the MessageManager consists of a string that describes a given error condition, and a string identifier that uniquely identifies the message to the OPP. The MessageManager creates the association between string identifier and string message through the AddMessage method that adds a message to the MessageManager.
Although the string used to describe a given error condition can vary from one site environment to the next, the string ID that identifies a message is hard coded. For example, if the OPP is unable to validate a credit card in the OrderForm, the pipeline attempts to retrieve the string associated with the message ID pur_bad_cc in the site's MessageManager. If the site builder has not associated a string with this message ID, the error condition is ignored. Otherwise, the OPP retrieves this message and writes it to the OrderForm's _Purchase_Errors collection. When the OrderExecute method that initiated the pipeline returns, this collection can be examined, and the strings in this collection can be used to provide site users with a detailed description of any errors that occurred during order processing.
The following example, from the Volcano Coffee sample site, illustrates the object interaction described in the preceding paragraphs.
The Volcano Coffee site creates a MessageManager component in its Global.asa file. Next, the MessageManager's AddMessage method is called multiple times to add a group of messages to the MessageManager:
REM -- Create a message manager for use by the pipeline
Set MSCSMessageManager = Server.CreateObject("Commerce.MessageManager")
Call MSCSMessageManager.AddLanguage("usa", &H0409)
MSCSMessageManager.defaultLanguage = "usa"
Call MSCSMessageManager.AddMessage("pur_out_of_stock", "At least one item is out of stock.")
Call MSCSMessageManager.AddMessage("pur_badsku", "Products in your basket were deleted because they don't exist in this store.")
Call MSCSMessageManager.AddMessage("pur_badplacedprice", "Prices of products in your basket have been updated.")
Call MSCSMessageManager.AddMessage("pur_noitems", "An order must have at least one item.")
Call MSCSMessageManager.AddMessage("pur_badshipping", "Unable to complete order. Cannot compute shipping cost.")
Call MSCSMessageManager.AddMessage("pur_badtax", "Unable to complete order. Cannot compute tax.")
Call MSCSMessageManager.AddMessage("pur_badhandling", "Unable to complete order. Cannot compute handling cost.")
Call MSCSMessageManager.AddMessage("pur_badverify", "Changes to the data require your review. Please review and resubmit.")
Call MSCSMessageManager.AddMessage("pur_badpayment", "There was a problem authorizing your credit. Please verify your payment information or use a different card.")
Call MSCSMessageManager.AddMessage("pur_badcc", "Bad Credit Card Number.")
After messages are added to the MessageManager, the MessageManager is initialized as an Application variable named MSCSMessageManager. Because the OPP must use the Active Server Pages (ASP) context to retrieve a site's instance of a given object, and must request this object by name, the MSCSMessageManager Application variable name is not optional:
REM Set up the Application instrinsic object
Set Application("MSCSMessageManager") = MSCSMessageManager