UPSship Control User's Guide   BurdickSoft (www.burdicksoft.com)

 

The BurdickSoft UPSship Control is a Visual Basic developed, server-side, ActiveX component that dramatically improves the ease of implementing and integrating real-time UPS shipping cost data into Internet E-Commerce sites.  It eliminates guesswork and shipping calculation errors by acquiring real-time, streaming shipping cost quote data and rate messages directly from the on-line UPS Rating and Service Selection server. As an Active-X control, it can be used either as server-side IIS/ASP component or integrated into any Microsoft application language for use in web-based client or server applications. The simplicity of the UPSship Active-X interface allows web-site developers to add real-time UPS shipping information to their commerce sites in minutes (by following 3 easy steps and only 15 lines of code) while providing maximum flexibility to control and display rate information that integrates seamlessly into the look and feel of the site.  

A Word About UPS Shipping

Excerpted from www.ups.com

UPS is the world's largest express carrier, the world's largest package delivery company and a leading global provider of specialized transportation and logistics services. UPS was founded in 1907 to provide private messenger and delivery services in the Seattle, Washington area. Over the past 93 years, it has expanded its small regional parcel delivery service into a global company. UPS delivers packages each business day for 1.8 million shipping customers to six million consignees. In 1999, it delivered an average of almost 13 million pieces per day worldwide, generating revenue of over $27 billion.

E-Commerce Capabilities. UPS is a leading participant in and facilitator of e-commerce.  It has teamed with over 100 e-commerce leaders to offer fully integrated Web-enabled solutions for our customers. Over two-thirds of ActivMedia, Inc.'s top 50 websites that use transportation services are UPS customers.

For more information about UPS and its shipping and E-Commerce offerings, please visit http://www.ups.com

Disclaimer:
BurdickSoft is not affiliated in any way with UPS.  The UPSship control written by BurdickSoft is an E-Commerce tool that works in conjunction with public UPS on-line E-Commerce capabilities such as the UPS Rates and Service Selection Datastream Server.  UPS assumes no liability either expressed or implied by a person(s) use of the BurdickSoft UPSship Control.  

Licensing

The UPSship control license grants the user 2 simultaneous server installations (one for development, the other for production).  A developer may choose to use one license on his or her development machine that uses Microsoft Personal or Peer Web Services and another license for the production server which in most cases will be running under IIS  in a remote location at the ISP site.  

Installing the UPSship Control

The UPSship control is packaged as an Active-X DLL.  There are two different build packages to choose from:

1.  The UPSShip DLL (UPSship.exe) - 100KB

2.  The UPSShip DLL with the Visual Basic Version 6.0 Run-Time libraries (UPSshipVB.exe) - 2.5 MB

The functionality of the two packages is identical, however, the second build package includes the Visual Basic 6.0 run-time libraries, which for most users are unnecessary, since these are already installed on most IIS/ASP servers.  

Important Note: Please check with your ISP hosting administrator to ensure that they will in fact allow you to install the UPSship DLL on their server.  While most ISP's are quite cooperative about this, a few forbid the installation of extended applications and DLL's.  

To install the control, simply double click the on the self-extracting executable file (e.g. UPSship.exe or UPSshipVB.exe) from anywhere on your desktop and follow the simple, self-guided installation sequence.  The DLL, user guide, and sample program will automatically install and self-register the necessary components. The sample programs and documentation are defaulted to install in the folder c:\Program Files\BurdickSoft.  The DLL is installed in the sytems directory C:\Windows\System.

After installing the UPSship Control, confirmation testing can be performed by running the "UPStest.asp" file.  This asp page tests to ensure that there is a working "handshake" between your server and the UPS web server.

Using UPSship Control 

The "UPSsample.asp" page contains a simple example of how to implement the UPSship control.  A real, live E-Commerce production example can also be seen at http://www.winekings.com . 

There are basically three steps required to implement the UPSship on a web-site:

Step 1 - Declare and instantiate the control  

ASP Example:

Dim UPS 
Set UPS= Server.CreateObject("UPSship.ship")                 ' create the UPSship object

Visual Basic Example:

In the Visual Basic IDE, select "Project/References" from the main menu and find the UPSship reference and click on it and hit the "apply" button.

Dim UPS as new UPSship.ship                                        ' create and instantiate the UPSship object

Step 2 - Set the input variables

ASP Example: (where the input is generated from an HTML form - see UPSsample.asp)

UPS.ResidentCode = Cint(request("chkResBus") ) 
UPS.ShipperZip = request("shipzip") 
UPS.DestinationZip = request("destzip") 
UPS.DestinationCountry = request("country") 
UPS.PackagingType = request("package") 
UPS.RateChart = request("ratechart") 
UPS.ServiceType = request("servicetype") 
UPS.Weight = request("weight") 
UPS.message = ""

Visual Basic Example: (where input is generated from a VB form)

UPS.ResidentCode = Cint(text1.text ) 
UPS.ShipperZip = text2.text
UPS.DestinationZip = text3.text
UPS.DestinationCountry = text4.text 
UPS.PackagingType = Cint(text5.text)
UPS.RateChart = Cint(text6.text )
UPS.ServiceType = Cint(text7.text)
UPS.Weight = Cint(text8.text)
UPS.message = ""

Step 3 - Get the rate info from the UPS site and display the results

ASP and Visual Basic Example

UPS.calculate                                                 ' get the data from the UPS server

message = UPS.message                                 ' capture the returned UPS message
status = UPS.StatusCode                               '  get the return code, 0 = success 
If status = 0 then price = UPS.ShipPrice          ' capture the price data if successful
Set UPS = nothing                                          ' destroy and release the UPS object from memory

That's It! Just 3 easy steps and 15 lines of code total.

Detailed Documentation

Properties - The BurdickSoft UPSship control contains 15 properties, 11 are input properties, 4 are output properties.

• About - Gets the current version number of the UPSship Control.

Syntax

string = object.About

Part	Description
string	String variable
object	The name of the UPSship object


Data Type: String

• DestinationCountry - Sets the two digit UPS country designation identifying where the product will be shipped.  UPS ships to over 100 different countries worldwide.  A complete list of the country designators are listed in the HTML select list in the UPSsample.asp page. Some of the more common designators are:
  
"US" - United States
"GB" - United Kingdom
"FR" - France
"DE" - Germany
"JP" - Japan
"MX" - Mexico
"CA" - Canada

Syntax

object.DestinationCountry = string

Part	Description
object	The name of the UPSship object
string	A 2-character string expression
Required Input	Yes
Default Value	"US"


Data Type: String

Remarks:  There is no Originating Country property since this is hardcoded to "US"


• DestinationZip - Sets the one to six digit alphanumeric-character postal code of the destination country/region.  
  
  Syntax
  
  object.DestinationZip = string
  

  Part	Description
  object	The name of the UPSship object
  string	One to six digit alphanumeric-character postal  code
  Required Input	Yes
  Default Value	None

  Data Type: String
  

• Insurance - Indicates whether or not shipping insurance is desired.
  
  Syntax
  
  object.Insurance = integer
  

  Part	Description
  object	The name of the UPSship object
  integer	one digit integer  = 0 No insurance  = 1 Insurance
  Required Input	No
  Default Value	0, No Insurance

  Data Type: Integer

  Remarks: Every package sent by UPS is automatically insured against loss or damage up to $100.  For packages having a greater value, additional coverage is available for 35 cents for each additional $100 of declared value or fraction thereof.  If insurance is desired, then the object.Insurance property must be set to 1, and the object.InsuredValue field must be filled in with the declared value of the package.  
  

• InsuredValue - Sets the declared value of the package if UPS shipping insurance is desired.
  
  Syntax
  
  object.InsuredValue = single
  

  Part	Description
  object	The name of the UPSship object
  single	An integer or single precision decimal number indicating the declared value of the package (e.g. 300 or 1587.65)
  Required Input	Only if shipping insurance is desired
  Default Value	0

  Data Type: Single

  Remarks: Every package sent by UPS is automatically insured against loss or damage up to $100.  For packages having a greater value, additional coverage is available for 35 cents for each additional $100 of declared value or fraction thereof.  If insurance is desired, then the object.Insurance property must be set to 1, and the object.InsuredValue field must be filled in with the declared value of the package.
  

• message - Returns the current message(s) being held in the control.  
  
  Syntax
  
  message = object.message
  

  Part	Description
  message	A string variable to hold the message
  object	The name of the UPSship object
  Required Input	No
  Default Value	None

  Data Type: String

  Remarks:  Any time a message is generated from the control, either error messages or rate status messages, they are placed in the object.message property variable.  It's a good idea to set this property to null ("") before executing the calculate method to ensure clean messages are returned.  The message property records both user generated errors (e.g. not filling in a required field) and UPS transaction messages.

   

• PackagingType - Sets the UPS packaging type.  
  
  Syntax
  
  object.PackagingType = integer
  

  Part	Description
  object	The name of the UPSship object
  integer	Packaging Type Code
  Valid Values (Note: For VB programmers, these are enumerated)	ShipperSupplied = 1   UPSLetterEnvelope = 2   UPSTube = 3   UPSExpressBox = 4   UPSIntl25KGBox = 5   UPSIntl10KGBox = 6
  Required Input	Yes
  Default Value	1 (ShipperSupplied)

  Data Type: Integer

  Remarks:  Indicates the type of packaging used for the package.
  
  

• RateChart - Determines how shipping prices are calculated based on how the package will be received by UPS.  
  
  Syntax
  
  object.RateChart = integer
  

  Part	Description
  object	The name of the UPSship object
  integer	Rate Chart Code
  Valid Values (Note: For VB programmers, these are enumerated)	CustomerCounter = 1   LetterCenter = 2   OnCallAir = 3   OneTimePickup = 4   RegularDailyPickup = 5
  Required Input	Yes
  Default Value	5 (RegularDailyPickup)

  Data Type: Integer

  Remarks:  Indicates how UPS receives the package.  Most higher volume business customers are placed on the Regular Daily Pickup routes.
  
  

• ResidentCode - Indicates whether the package is being sent to a home residence or business establishment.    
  
  Syntax
  
  object.ResidentCode = integer
  

  Part	Description
  object	The name of the UPSship object
  integer	Resident Code
  Valid Values	Business = 0   Home Residence = 1
  Required Input	Yes
  Default Value	1 (Ship to Home Residence)

  Data Type: Integer

  
  

• StatusCode - Gets the success or failure status of the rate query.  
  
  Syntax
  
  longinteger = object.PackagingType
  

  Part	Description
  longinteger	The returned status code:  = -2: Internet connection or UPS site down  = -1: User input validation error  =  0:  successful completion  <>0: unsuccessful completion
  object	The name of the UPSship object
  Required Input	No
  Default Value	None

  Data Type: Long Integer

  Remarks:  This property can be used to test whether or not UPS was able to successfully calculate a price based on the parameters presented.  A non-zero value indicates a problem that can be more fully examined by displaying the object.message property.

 

• ServiceType - Sets the type of UPS shipping desired.  
  
  Syntax
  
  object.ServiceType = integer
  

  Part	Description
  object	The name of the UPSship object
  integer	Service Type Code
  Valid Values (Note: For VB programmers, these are enumerated)	NextDayAirEarly = 1   NextDayAir = 2   NextDayAirIntra = 3   NextDayAirSaver = 4   SecondDayAirAM = 5   SecondDayAir = 6   ThreeDaySelect = 7   Ground = 8   CanadaStandard = 9   WorldwideExpress = 10  WorldwideExpedited = 11
  Required Input	Yes
  Default Value	8 (Ground)

  Data Type: Integer

  Remarks:  UPS offers a wide range of shipping services.  Some of these would be obviously invalid (e.g. Ground for shipping from the US to the UK).  In cases where certain service offerings are not available, an error message and non-zero StatusCode is generated.
  
  

• ShipperZip - Sets the shipper's postal code where the package originates.  
  
  Syntax
  
  object.ShipperZip = string
  

  Part	Description
  object	The name of the UPSship object
  string	The five digit US zip code for the package  origin
  Valid Values	Five digit numeric zip code
  Required Input	Yes
  Default Value	None

  Data Type: string
  
  

• ShipPrice - Gets the total shipping charge including any accessories and surcharges.  
  
  Syntax
  
  string = object.ShipPrice
  

  Part	Description
  string	Contains a currency value indicating the total  shipping price
  object	The name of the UPSship object
  Required Input	No
  Default Value	None

  Data Type: String

  Remarks:  The price returned is in $US.
  
  

• TimeOut - Sets the request timeout in seconds.
  
  Syntax
  
  object.TimeOut = integer
  

  Part	Description
  object	The name of the UPSship object
  integer	The length of time in seconds before the request times out.
  Required Input	No
  Default Value	5

  Data Type: Integer

  Remarks:  If a request (e.g. calculate method) doesn't respond within the specified time, and an error is generated.  Setting this property to 0 means infinity..
  
  

• Weight - Sets the weight in lbs of the package.  
  
  Syntax
  
  object.Weight = integer
  

  Part	Description
  object	The name of the UPSship object
  integer	The weight of the package in lbs.
  Valid Values	The weight should be rounded to the nearest  whole  integer (e.g. 20.3 lbs = 20,   20.7 lbs = 21)
  Required Input	Yes
  Default Value	None

  Data Type: Integer

  Remarks:  If the package is a UPS letter, no weight is needed.  If the package exceeds 150 lbs, an error message will be generated since 150 lbs is the maximum weight limit per package.
  

Methods - The BurdickSoft UPSship control contains just one method - object.calculate..

• calculate - gathers all of the required inputs, validates user inputs, gets real-time pricing data from the UPS server and sets all output properties.

Syntax

object.calculate

Part	Description
object	The name of the UPSship object
Returned Values	All of the returned UPS data is used to set the three output properties (e.g. message, StatusCode,  and ShipPrice)


Data Type: None

Remarks:  The object.calculate method takes the user generated inputs and constructs a web datastream with the UPS server.  It receives the data back and parses it into the three output variables -- message, StatusCode,  and ShipPrice.  If the Internet connection is down or the UPS Server is down, the system will timeout after a few seconds and return an error message.


Further inquires and questions should be directed to BurdickSoft:

• web: www.burdicksoft.com
• email: dburdick@burdicksoft.com