Chapter 13: Barcodes

13.1.1 Introduction

Regular (one-dimensional) barcodes are provided by the DrawBarcode method of the PdfCanvas object. This method expects two parameters: a string indicating the data to encode as a barcode, and a PdfParam object or parameter string providing parameters.

The following code sample prints a UPC-A (Universal Product Code) barcode on a page.

Click the links below to run this code sample:

http://localhost/asppdf/manual_13/13_barcode.asp http://localhost/asppdf/manual_13/13_barcode.aspx

This will produce the following:

Note that AspPDF automatically calculated and added the UPC-A check digit (the 6.)

The DrawBarcode method will validate the data passed to it and throw an error exception if it is invalid for the specified type of barcode.

AspPDF also includes a sample of an HTML form page into which a user can enter data for a barcode. This code is not repeated here due to length. Click the links below to run this sample:

http://localhost/asppdf/manual_13/13_barcode_form.asp http://localhost/asppdf/manual_13/13_barcode_form.aspx

13.1.2 Required Barcode Parameters

Type - What type of barcode to draw. See below for a list of supported types.

X, Y - X and Y coordinates of the lower-left corner of the barcode.

Width, Height - Width and height of the barcode.

The X, Y, Width, and Height parameters only specify the size of the actual rectangular bars. Text associated with barcodes may extend slightly outside the specified area.

13.1.3 Optional Barcode Parameters

Color - Specifies the color of the bars and text. This can be a named color constant like "red" or a hex RGB value. Defaults to black.

tc, tm, ty, tk - Specify the CMYK color components of the bars and text. The values must be between 0 and 1. If these parameters are specified, Color is ignored. These parameters were introduced by version 2.2.0.2.

BgColor - Specifies the color of the spaces between the bars. If not specified, the spaces will be transparent. This can be useful to make the spaces in the barcode white if the page background is non-white. Note that very few scanners can scan barcodes in colors other than standard black and white.

FontSize - Specifies the size of the font used. This is not used for certain barcode types like UPC which prescribe all font sizes. This is a maximum limit on font size. AspPDF will shrink the font as necessary to make the text fit within the width of a particular barcode type.

BarWeight - Certain barcode types do not prescribe a constant width ratio between "thin" and "wide" bars, but allow this ratio to be specified. Using this parameter may improve the scannability of these barcode types with various scanners. Defaults to 2, meaning "wide" bars are twice as wide as "thin" bars.

DrawText - Some barcode types (such as UPC) usually include printed human-readable text. Others (such as Industrial 2/5) do not. This parameter allows you to override the default behavior. Can be set to True or False.

AddCheck - A few barcode types allow optional calculation and use of a check digit. Boolean parameter.

Compress - Only used by Code 128, see below. Boolean parameter.

Angle - Specifies an angle of counter-clockwise rotation (in degrees) of the barcode around its lower-left corner.

13.1.4 Supported Linear Barcode Types

(Some images shortened vertically for space)

1. UPC-A - The most common type of barcode. Used in retail applications. Requires 11 or 12 numeric digits; if 11 are given, AspPDF calculates and adds the 12th digit which is a check digit.

2. UPC-E - A shortened form of UPC-A. Requires 8 numeric digits.

3. EAN-13 - A superset of UPC-A, with one additional digit. Requires 12 or 13 numeric digits; the 13th is a check digit in the same manner as UPC-A.

4. EAN-8 - A shortened form of EAN-13. Requires 7 or 8 numeric digits; the 8th is a check digit.

5. UPC-A with supplemental - A UPC-A code, plus either a 2-digit or 5-digit supplemental code. Requires 14 numeric digits for the 2-digit version and 17 digits for the 5-digit version. If the 12th character is a space, AspPDF will calculate a check digit for that space and encode it.

6. UPC-E with supplemental - Similar to UPC-A with supplemental. Requires 10 or 13 numeric digits.

7. EAN-13 with supplemental - Similar to UPC-A with supplemental. Requires 15 or 17 numeric digits. Calculates a check digit if the 13th character is a space.

8. EAN-8 with supplemental - Similar to UPC-A with supplemental. Requires 10 or 13 numeric digits. Calculates a check digit if the 8th character is a space.

9. 2-digit supplemental - The 2-digit supplemental barcode can be drawn by itself without an accompanying main barcode.

10. 5-digit supplemental - See previous.

None of the UPC or EAN barcode types use the FontSize or BarWeight parameter. All other barcodes do use FontSize, and use BarWeight unless otherwise specified.

11. Industrial 2 of 5 - Can encode any quantity of numeric characters. AspPDF adds the start and stop bars.

12. Interleave 2 of 5 - Similar to Industrial 2 of 5 with a more compact encoding scheme.

13. Interleave 2 of 5 Special - Same as Interleave 2 of 5 but with different spacing. Does not use BarWeight.

14. DataLogic 2 of 5 - Similar to Industrial 2 of 5 but with a different compact encoding scheme.

15. Plessey - Can encode any quantity of numeric characters. AspPDF adds the start and stop bars. This image illustrates the use of the BarWeight parameter set to 3. Note that the wide bars are much thicker than the thin bars.

16. Codabar - Can encode any quantity of these characters:

0123456789-$:/.+

Requires a matched pair of start and stop characters which must be the letters A, B, C, or D. Does not use BarWeight.

17. Code 39 - A common encoding scheme for alphabetic text. Can encode numbers, uppercase letters, and these characters:

-. $/+%

AspPDF encodes lowercase characters as uppercase, and adds start and stop bars.

18. Code 11 - Can encode any quantity of numeric characters.

20. Code 39 Extended - Can encode the entire ASCII set (characters 0 to 127). Can optionally add a check digit with the AddCheck parameter.

21. Code 93 - Can encode the entire ASCII set (characters 0 to 127). Does not use BarWeight.

22. Code 128 - Can encode the entire ASCII set (characters 0 to 127). Does not use BarWeight. Must use a check digit via the AddCheck=true parameter. Automatically selects between Code-128 encoding schemes as necessary. Implements the Code-C encoding scheme to compactly encode pairs of digits; this is done if the optional parameter Compress is set to True. NOTE: as of Version 3.1.0.2, this barcode is replaced by a more readable Type=24 barcode described below.

23. Code 128 Raw - Provides access to advanced features of Code-128 encoding; AspPDF does not do any processing of the data passed to it, except for adding the stop bars and optionally adding the check digit. You must provide the start code character; in VB or ASP, this would be ChrW(135) for Code A, ChrW(136) for Code B, and so on. Consult a Code 128 reference for full information on specifications such as function and shift characters.

24. Code 128 Auto - An improved version of Code 128 (Type=22) described above. Can encode the entire ASCII set (characters 0 to 127). Does not use BarWeight. Ignores AddCheck and Compress parameters. Introduced in version 3.1.0.2 to replace barcode Type=22. Uses an alternative encoding algorithm which provides better scannability than the old Type=22 barcode.

30. US Postal Code - Printed on mail by the US Postal Service. AspPDF calculates and adds a check digit. Does not use BarWeight.

31. UK/Canada Postal Code - Printed on mail by the UK and Canada mail services. Does not use BarWeight.

32. Intelligent Mail Code - Used by US Postal Service. Also known as the USPS OneCode Solution or USPS 4-State Customer Barcode. Requires 20 digits of tracking information followed by 0, 5, 9, or 11 digits of routing (zip code) information. The 2nd digit of the tracking code must be in the range 0 to 4. Introduced by AspPDF 2.4. Does not use BarWeight.

The barcode functionality is demonstrated by Live Demo #8a.

13.2.1 Introduction

AspPDF supports four popular 2-dimensional barcodes: PDF417, Data Matrix, QR Code and Aztec. (PDF417 and DataMatrix were added in version 1.8, QR Code was added in service release 2.0.0.7, and Aztec was added in service release 3.4.0.7.) 2D barcode symbols are drawn via the method DrawBarcode2D of the PdfCanvas object. This method has two required arguments: the text to be encoded, and an instance of the PdfParam object or parameter string. If binary data is to be encoded, the binary array with the data is to be passed via the 3rd optional argument. If the 3rd argument is specified, the text argument is ignored.

The barcode's appearance is controlled via parameters passed as the 2nd argument. The only two required parameters are X and Y which specify the position of the lower-left corner of the symbol on the page. The Type parameter specifies which of the four barcode types to draw. The valid Type values are 1 (PDF417, default), 2 (Data Matrix), 3 (QR Code) and 4 (Aztec). The four 2D barcode types and their parameters are described below.

The 2D barcode functionality is demonstrated by Live Demo #8b.

13.2.2 PDF417

In the context of the PDF417 barcode, "PDF" stands for Portable Data File and has nothing to do with the Adobe PDF file format. A PDF417 barcode symbol is essentially a stack of 1D barcodes. A single symbol can contain far more information than a 1D barcode (up to 1.1 KB) in a space no larger than a traditional barcode. This format allows you to store not only text and numbers but binary data as well. In addition, PDF417 has a built-in error correction system so that a symbol can be read even if it is partially damaged or destroyed. The following code snippet draws the barcode symbol shown above:

A PDF417 symbol has a columnar pattern. The leftmost and rightmost columns of every symbol always look the same and they are called start and stop patterns. These are abutted by row indicator columns, and the actual data columns are squeezed in the middle. The symbol above has 3 data columns. Each data column is a stack of "codewords" which are sequences of 4 bars and 4 spaces arranged on 17 available slots. That is where the number 417 comes from. A symbol can contain 1 to 30 data columns and 3 to 90 rows.

The appearance and properties of a PDF417 symbol are controlled by the following parameters (all optional):

• BarWidth - the width of the narrowest vertical bar (in user units.) 1 by default.
• AspectRatio - the ratio of the row height to the narrowest bar width. 2 by default.
• ErrorLevel - controls the amount of error correction information in the symbol. The higher this number is, the more resistant to damage (and larger in size) the symbol gets. Valid values are 0 to 8. The value of 0 means no error correction. If this parameter is not specified at all, the error level is computed automatically based on the data size according to the standard PDF417 specifications.
• Columns - the symbol will contain at least this number of data columns, provided there is enough data for it. If not specified, the number of columns is determined automatically.
• Rows - the symbol will contain at least this number of rows, provided there is enough data for it. If not specified, the number of rows is determined automatically.
• Angle - an angle of counter-clockwise rotation (in degrees) of the barcode around its lower-left corner. 0 by default.
• Color - barcode color, the current fill color by default.
• BgColor - background color (the color of the "white" rectangular area underneath the barcode.) Transparent by default. Useful to make the barcode background white if the page background is non-white.
• BgMargin - the size (in user units) of the margins around the barcode. 2 x BarWidth by default. Ignored unless BgColor is specified.
• CodePage - the code page number, such as 1252, to be used to convert the Unicode string to a byte array. 65001 (UTF-8) by default. This parameter was introduced in Version 3.4.0.7.

As of Version 3.2.0.1, the following parameters have been added to enable the creation of US Government-compliant barcodes on official USCIS forms:

• Width, Height - specify the overall width and height of the barcode symbol in user units, including the quiet zone (described below.) Both parameters must be specified to have an effect, i.e. if one is omitted, the other is ignored. If both of these parameters are specified, BarWidth and AspectRatio are ignored.
• QZH, QZV - specify the "quiet zone" space margins in user units on the left/right and top/bottom sides of the barcode, respectively. 0 by default. These parameters are only used if the Width/Height parameters are specified.

• Binary - if set to true, forces the byte (or binary) compression mode in which each codeword represents 1.2 bytes of information The default text compression mode encodes (roughly) 2 characters per codeword. False by default.

Filling out PDF417 barcode-equipped government forms is covered in detail in Section 12.8 - Barcode-equipped Government Forms.

The following code snippet encodes binary data from a BLOB recordset field. It specifies the error correction level of 5 and bar width of 2:

Unlike the DrawBarcode method described in the previous subsection, the DrawBarcode2D method returns a value -- an instance of the PdfParam object populated with the barcode's width, height, number of rows, number of columns and error level. For example, the following code snippet draws a barcode and then prints out its width and height:

The number of rows, number of columns and error level are retrieved via Param("Rows"), Param("Columns") and Param("ErrorLevel"), respectively.

13.2.3 Data Matrix

Data Matrix is another very popular 2D barcode. Its symbols are usually square and sometimes rectangular. A single symbol can encode up to 2335 characters. The required parameters are X, Y, and Type (the latter must be set to 2.) This barcode uses the same error correction system as PDF417, but the error level is determined automatically, therefore the ErrorLevel parameter is not used. The symbol shown above was drawn using the following code:

The BarWidth parameter specifies both the width and height of an individual cell of the symbol (in user units.) AspectRatio is not used since the cells are always square.

By default, the number of cell columns and rows in a symbol is determined automatically. You can specify the desired size via the Columns and Rows parameters. You must either specify both parameters, or neither. The following [Rows x Columns] combinations are valid: 10x10, 12x12, 14x14, 16x16, 18x18, 20x20, 22x22, 24x24, 26x26, 32x32, 36x36, 40x40, 44x44, 48x48, 52x52, 64x64, 72x72, 80x80, 88x88, 96x96, 104x104, 120x120, 132x132, 144x144, 8x18, 8x32, 12x26, 12x36, 16x36, and 16x48.

All the other parameters have the same meaning as with PDF417. The return values are also the same except that there is no ErrorLevel value.

13.2.4 QR Code

The QR Code barcode is used in commercial tracking applications as well as advertisements and signs aimed at mobile-phone users. It was invented in Japan in 1994. "QR" stands for "quick response." The three prominent corner boxes give the QR Code symbols a very distinctive look. The symbols are always square.

A single symbol can encode up to 7,089 numeric symbols, up to 4,296 alpha-numeric symbols, up to 2,953 binary bytes, or up to 1,817 Kanji/Kana characters. The required parameters are X, Y, and Type (the latter must be set to 3.) There are 4 error correction levels, from 0 to 3, 0 being the lowest, specified via the optional ErrorLevel parameter (0 by default.) The symbol shown above was drawn using the following code:

By default, the size of the symbol is determined automatically. To make the symbol larger than necessary, use the Version parameter. The valid values are 0 (auto) and 1 to 40 to specify a larger size.

The BarWidth parameter specifies both the width and height of an individual cell of the symbol (in user units.) AspectRatio is not used since the cells are always square. Columns and Rows are not used since the size is determined automatically or specified via the Version parameter.

All the other parameters have the same meaning as with PDF417 and DataMatrix. CodePage is not used as QR Code always uses UTF-8 encoding. The return values are also the same except that there is no ErrorLevel value.

QR Code's built-in error correction system allows a symbol to function correctly even if it is partially destroyed or obstructed. Thanks to that feature, a QR code symbol can be decorated with a logo for marketing purposes while remaining perfectly scannable:

The symbol above was created with the following code. Note that the error correction level is set to 3:

13.2.5 Aztec

Aztec code was invented by Andrew Longacre, Jr. and Robert Hussey in 1995. It can encode 3832 digits, 3067 letters, or 1914 bytes of data. Aztec symbols have a recognizable "bull's eye" pattern in the center.

The required parameters are X, Y, and Type (the latter must be set to 4.) The symbol shown above was drawn using the following code:

There are 4 error correction levels, from 1 to 4, specified via the optional ErrorLevel parameter (2 by default.)

Aztec symbols are always square. By default, the size of the symbol is determined automatically. To make the symbol larger than necessary, use the Version parameter. The valid values are 0 (auto) and 1 to 36 to specify a larger size. The following table maps the Version values to the corresponding symbol size. The symbols marked with an asterisk (*) in the table below are "compact" symbols, meaning they have a smaller bulls-eye pattern at the center of the symbol.

The BarWidth parameter specifies both the width and height of an individual cell of the symbol (in user units.) AspectRatio is not used since the cells are always square. Columns and Rows are not used since the size is determined automatically or specified via the Version parameter. The return values are Width, Height, Rows and Columns.