PDF417 .NET Control Properties

Barcodes.PDF417 Namespace

PDF417Control Class
Barcodes.PDF417.dll assembly

Returns or sets the data that is to be encoded in the barcode.

Syntax

object.DataToEncode [ = sDataToEncode ]

Possible Values

DataToEncode String that specifies or receives the barcode data.

The property is read/write.

Control characters and use of the tilde

To insert special characters, the "~" character is used. Below you can see available values of special characters.

~1: Not allowed.

~2: Not allowed.

~3: This character are only allowed in the first position of the symbol. It indicates that the data contains commands for the barcode reader.

~4: Not allowed.

~5: Not allowed.

~6: Not allowed.

~7NNNNNN: Specifies the Extended Channel to be used, where NNNNNN is a value between and 000000 - 811799. For example: ~7000010 means Extended Channel 10. An Extended Channel Interpretation (ECI) is used to change from the default interpretation used to encode data. This mechanism enables characters from other character sets (e.g. Arabic, Cyrillic, Greek, Hebrew) and other data interpretations or industry-specific requirements to be represented. The ECI can only be used with readers enabled to transmit the symbology identifiers.

~xNN: Represents the hexadecimal value of NN, for example, if there is a combination of "~xA7", it will be replaced with the hexadecimal value of A7.

~~: Represents the "~" character. This combination can be used to assign its usual value to the "~" character, thus, "~~R" does not mean carriage return character (CR), but two characters "~" and "R".

~R: Represents the carriage return character.

~N: Represents the new line character.

~T: Represents the tab character.

CompactionMode Property

Returns or sets the encoding mode of the PDF417 barcode.

Syntax

object.CompactionMode [ = eCompactionMode ]

Possible Values

eCompactionMode CompactionMode Value that specifies or receives the encoding mode of the PDF417 barcode

Value Constant Description

0 cmAuto The most optimal encoding mode or their combination is selected. Thanks to changing encoding modes, the most optimal PDF417 barcode size is achieved.

1 cmText The Text Compaction mode includes all the printable ASCII characters (i.e. values from 32 to 126) and three ASCII control characters: HT or tab (ASCII value 9), LF or line feed (ASCII value 10), and CR or carriage return (ASCII value 13). The Text Compaction mode encodes up to 2 characters per codeword.

2 cmNumeric The Byte Compaction mode should be used to encode long strings of consecutive numeric digits.

3 cmByte The Byte Compaction mode enables a sequence of 8-bit bytes to be encoded into a PDF417 barcode.

The property is read/write.

ErrorCorrectionLevel Property

Returns or sets the error correction level of the PDF417 barcode.

Syntax

object.ErrorCorrectionLevel [ = eErrorCorrectionLevel ]

Possible Values

eErrorCorrectionLevel ErrorCorrectionLevel Value that specifies or receives the error correction level of the PDF417 barcode

Value Constant Total number of error correction codewords

0 ecl_0 2

1 ecl_1 4

2 ecl_2 8

3 ecl_3 16

4 ecl_4 32

5 ecl_5 64

6 ecl_6 128

7 ecl_7 256

8 ecl_8 512

9 eclAuto Recommended minimum error correction level.

The property is read/write.

Remarks

Error correction can be used to compensate for defects in the label and misreads during the decode procedure. For any given error correction level, a particular number of error correction codewords is incorporated into the PDF417 symbol.

DataColumns Property

Returns or sets the number of data columns in the PDF417 matrix. This number can be from 1 to 30. The more the number of columns is, the greater width PDF417 needs.
If the DataRows property is equal to zero, the number of rows is calculated automatically depending on the amount of encoded data and the number of columns.
In the same way, if the number of data columns is equal to zero, the necessary number of columns will be calculated automatically.
The DataColumns and DataRows properties cannot be both equal to zero.
If DataColumns and DataRows are not equal to zero, the PDF417 control will try to encode the data using these parameters.

Syntax

object.DataColumns [ = iDataColumns ]

Possible Values

iDataColumns Integer that specifies or receives the DataColumns property

The property is read/write.

DataRows Property

Returns or sets the number of data rows in the PDF417 matrix. This number can be from 3 to 90.

Syntax

object.DataRows [ = iDataRows ]

Possible Values

iDataRows Integer that specifies or receives the DataRows property

The property is read/write.

CompactPDF Property

If this property is True, the PDF417 barcode will be drawn in the compact mode. You should keep in mind that not all scanners support compact PDF417.

Syntax

object.CompactPDF [ = bCompactPDF ]

Possible Values

bCompactPDF Boolean that specifies or receives the CompactPDF property

The property is read/write.

Remarks

In earlier specifications of PDF417, this was called Truncated PDF417. Compact PDF417 is a preferred term to avoid confusion with the more general use of the term 'truncated'.

Y2XRatio Property

This property determines the ratio of y-dimension to x-dimension. The minimum recommended value is 3. Usually, this property is set to 4.

Syntax

object.Y2XRatio [ = rY2XRatio ]

Possible Values

rY2XRatio Double that specifies or receives the y to x ratio.

The property is read/write.

Orientation Property

Returns or sets the orientation of the barcode.

Syntax

object.Orientation [ = eOrientation ]

Possible Values

Orientation Orientation Value that specifies or receives the orientation of the barcode.
Valid values are 0, 90, 180 and 270

The property is read/write.

Transparent Property

Returns or sets a value indicating whether the background of a PDF417 control is transparent or opaque.

Syntax

object.Transparent [ = bTransparent ]

Possible Values

bTransparent Boolean that specifies or receives the Transparent property
If the value is False then the the control's BackColor property setting fills the control and obscures any color or graphics behind it.

The property is read/write.

BackColor Property

Returns or sets the background color of a bar code.

Syntax

object.BackColor [ = sColor ]

Possible Values

sColor Color Value that specifies or receives the background color

The property is read/write.

ForeColor Property

Returns or sets the foreground color of all bars in a bar code object.

Syntax

object.ForeColor [ = sColor ]

Possible Values

sColor Color Value that specifies or receives the foreground color

The property is read/write.

QuietZone Property

Returns or sets a value that determines whether to include quiet zones. The PDF417 barcode shall include a quiet zone on all four sides.

Syntax

object.QuietZone [ = bQuietZone ]

Possible Values

bShowQuietZone Boolean that specifies or receives the ShowQuietZone property

The property is read/write.

Remarks

Quiet Zones are small areas of blank space (x-dimension). Most bar code symbology specifications require quiet zones therefore it is highly recommended that you enable this option.

AlignH Property

Returns or sets a horizontal barcode alignment.

Syntax

object.AlignH [ = eAlignH ]

Possible Values

eAlignH HorizontalAlignment Value that specifies or receives the horizontal barcode alignment

The property is read/write.

AlignV Property

Returns or sets a vertical barcode alignment.

Syntax

object.AlignV [ = eAlignV ]

Possible Values

eAlignV VerticalAlignment Value that specifies or receives the vertical barcode alignment

The property is read/write.

MacroPDF Property

If this property is true True, Macro PDF417 Control Block will be included in barcode PDF417.
Macro PDF417 provides a mechanism for the data in a file to be split into blocks and be represented in more than one PDF417 symbol(barcode). This mechanism is similar to the Structured Append in other symbologies.
Using Macro PDF417, large files are split into several file segments and encoded into individual symbols(barcodes).
Up to 99999 individual PDF417 symbols(barcodes) may be used to encode data in Macro PDF417.
The Macro PDF417 shall contain at least the three mandatory properties: MacroPDFSegmentCount, MacroPDFSegmentIdx, MacroPDFFileID. It also may contain a number of optional properties: MacroPDFFileName, MacroPDFTimeStamp, MacroPDFSender, MacroPDFAddressee, MacroPDFFileSize, MacroPDFChecksum.
To be able to use Macro PDF417, your reader or software must support the Macro PDF417 technology.

Syntax

object.MacroPDF [ = bMacroPDF ]

Possible Values

bMacroPDF Boolean that specifies or receives the MacroPDF property

The property is read/write.

Examples

PDF417Ctrl1.MacroPDF = True
PDF417Ctrl1.MacroPDFFileID = "#001"
PDF417Ctrl1.MacroPDFSegmentCount = 3

'optional properties
'PDF417Ctrl1.MacroPDFAddressee = "addresse"
'PDF417Ctrl1.MacroPDFSender = "My Name"
'PDF417Ctrl1.MacroPDFFileName = "MyFileName"
'PDF417Ctrl1.MacroPDFFileSize = 843921
'PDF417Ctrl1.MacroPDFChecksum = 37894
'PDF417Ctrl1.MacroPDFTimeStamp = "7329847911"

PDF417Ctrl1.MacroPDFSegmentIdx = 1
PDF417Ctrl1.DataToEncode = "123"
Call PDF417Ctrl1.SaveToImageFile(300, 100, "c:\part1.bmp")

PDF417Ctrl1.MacroPDFSegmentIdx = 2
PDF417Ctrl1.DataToEncode = "456"
Call PDF417Ctrl1.SaveToImageFile(300, 100, "c:\part2.bmp")

PDF417Ctrl1.MacroPDFSegmentIdx = 3
PDF417Ctrl1.DataToEncode = "789"
Call PDF417Ctrl1.SaveToImageFile(300, 100, "c:\part3.bmp")

Another example, optional properties are used here.

PDF417Ctrl1.MacroPDF = True
PDF417Ctrl1.MacroPDFFileID = "#001"
PDF417Ctrl1.MacroPDFSegmentCount = 3

'optional properties
PDF417Ctrl1.MacroPDFAddressee = "addresse"
PDF417Ctrl1.MacroPDFSender = "My Name"
PDF417Ctrl1.MacroPDFFileName = "MyFileName"
PDF417Ctrl1.MacroPDFFileSize = 843921
PDF417Ctrl1.MacroPDFChecksum = 37894
PDF417Ctrl1.MacroPDFTimeStamp = "7329847911"

PDF417Ctrl1.MacroPDFSegmentIdx = 1
PDF417Ctrl1.DataToEncode = "123"
Call PDF417Ctrl1.SaveToImageFile(300, 100, "c:\part1.bmp")

'Optional properties can be present only in one of Macro PDF417 symbols, that is why they are not necessary in further symbols.
PDF417Ctrl1.MacroPDFAddressee = ""
PDF417Ctrl1.MacroPDFSender = ""
PDF417Ctrl1.MacroPDFFileName = ""
PDF417Ctrl1.MacroPDFFileSize = -1
PDF417Ctrl1.MacroPDFChecksum = -1
PDF417Ctrl1.MacroPDFTimeStamp = ""

PDF417Ctrl1.MacroPDFSegmentIdx = 2
PDF417Ctrl1.DataToEncode = "456"
Call PDF417Ctrl1.SaveToImageFile(300, 100, "c:\part2.bmp")

PDF417Ctrl1.MacroPDFSegmentIdx = 3
PDF417Ctrl1.DataToEncode = "789"
Call PDF417Ctrl1.SaveToImageFile(300, 100, "c:\part3.bmp")

As a result, three PDF417 symbols encoding one string "123456789" will be created. Of course, "123456789" is taken only as an example, Macro PDF417 is actually used to encode large amounts of information about several kilobytes.

Macro PDF417

MacroPDFSegmentCount Property

Returns or sets the value that defines the total number of Macro PDF417 symbols.

Syntax

object.MacroPDFSegmentCount [ = iMacroPDFSegmentCount ]

Possible Values

iMacroPDFSegmentCount Value that specifies or receives the MacroPDFSegmentCount property.

Valid values are 1...99999

The property is read/write.

MacroPDFSegmentIdx Property

Returns or sets the segment index of Macro PDF417 symbols.

Syntax

object.MacroPDFSegmentIdx [ = iMacroPDFSegmentIdx ]

Possible Values

iMacroPDFSegmentIdx Value that specifies or receives the MacroPDFSegmentIdx property.

Valid values are 1...99999

The property is read/write.

MacroPDFFileID Property

Returns or sets Macro PDF417 file ID.
For each related Macro PDF417 symbol, the file ID contains the same value. This ensures that all reassembled symbol data belongs to the same distributed file representation.

Syntax

object.MacroPDFFileID [ = sMacroPDFFileID ]

Possible Values

sMacroPDFFileID String that specifies or receives the MacroPDFFileID property.

If the first character of the MacroPDFFileID property is "#", the ID file must be of the following format: NNNXXX...
where NNN, XXX, ... are numbers 000...899
Otherwise the ID file can contain any set of numbers.

Examples
PDF417.MacroPDFFileID = "#001899017"
or
PDF417.MacroPDFFileID = "782357826587"

The property is read/write.

MacroPDFFileName Property

Returns or sets a string of Macro PDF417 file name.
This property is optional.

Syntax

object.MacroPDFFileName [ = sMacroPDFFileName ]

Possible Values

sMacroPDFFileName String that specifies or receives the MacroPDFFileName property.

The property is read/write.

MacroPDFTimeStamp Property

Returns or sets a string that determines Macro PDF417 time stamp expressed as the elapsed time in seconds since 1970:01:01:00:00:00 GMT (i.e. 00:00:00 GMT on 1 January 1970).
This property is optional.

Syntax

object.MacroPDFTimeStamp [ = sMacroPDFTimeStamp ]

Possible Values

sMacroPDFTimeStamp String that specifies or receives the MacroPDFTimeStamp property.

The property is read/write.

MacroPDFSender Property

Returns or sets a string that determines Macro PDF417 file sender.
This property is optional.

Syntax

object.MacroPDFSender [ = sMacroPDFSender ]

Possible Values

sMacroPDFSender String that specifies or receives the MacroPDFSender property.

The property is read/write.

MacroPDFAddressee Property

Returns or sets a string that determines the sender addressee.
This property is optional.

Syntax

object.MacroPDFAddressee [ = sMacroPDFAddressee ]

Possible Values

sMacroPDFAddressee String that specifies or receives the MacroPDFAddressee property.

The property is read/write.

MacroPDFFileSize Property

Returns or sets a value that determines Macro PDF417 file size in bytes.
This property is optional.

Syntax

object.MacroPDFFileSize [ = iMacroPDFFileSize ]

Possible Values

iMacroPDFFileSize Integer that specifies or receives the MacroPDFFileSize property.

The property is read/write.

MacroPDFChecksum Property

Returns or sets a value that contains the value of the 16-bit (2-bytes) CRC checksum using CCITT-16 polynomial x¹⁶+x¹²+x⁵+1 computed over the entire source file.
This property is optional.

Syntax

object.MacroPDFChecksum [ = iMacroPDFChecksum ]

Possible Values

iMacroPDFChecksum Integer that specifies or receives the MacroPDFChecksum property.
Valid values are 0...65535

The property is read/write.

FreezeEncode Property

This property pauses or resumes encoding the PDF417 symbol. It makes sense to use this method in heavily loaded application, for example, web services, etc.

Syntax

object.FreezeEncode [ = bFreezeEncode ]

Possible Values

bFreezeEncode Boolean that specifies or receives the FreezeEncode property

The property is read/write.

Example

You need to set several properties of the DataMatrix control. Each time some properties are set (CompactionMode, DataToEncode, ErrorCorrectionLevel and others) the matrix is re-encoded, i.e. the Reed-Solomon codes are calculated, the matrix is build, etc. It takes a lot of CPU time. To improve the performance of the application, you can pause encoding and resume it only after all properties are set.
PDF417Ctrl.FreezeEncode = True
PDF417Ctrl.DataToEncode = "1234567"
PDF417Ctrl.CompactionMode = CompactionModes.cmByte
PDF417Ctrl.ErrorCorrectionLevel = ErrorCorrectionLevels.ecl_8
PDF417Ctrl.FreezeEncode = False

JPEGQuality Property

Returns or sets the value indicating the image quality in the JPEG format.
This property makes sense only if the SaveToImageFile method is used and the barcode is saved to a JPEG file.

Syntax

object.JPEGQuality [ = iJPEGQuality ]

Possible Values

iJPEGQuality Integer that specifies or receives the JPEGQuality property
The value of this property must be within the range of 0..100, where 100 is the highest quality.

The property is read/write.