PDF417 Plug-In for 4th Dimension 1999-2002 DataCraft, Inc. All rights reserved. Portions 1999 Symbol Technologies, Inc. Introduction The PDF417 Plug-in for 4th Dimension injects the power and versatility of the PDF417 bar code symbology into your applications. The plug-in lets you produce PDF417 bar codes from within your 4th Dimension application. This manual assumes knowledge of the PDF417 symbology and an understanding of 4th Dimension and the use of 4D plug-ins. If you are unfamiliar with PDF417 symbology, we recommend contacting AIM USA <http://www.aimusa.org/> to purchase the Uniform Symbology Specification PDF417 documentation. About the PDF417 Symbology PDF417 is a multi-row, variable-length symbology offering a high data capacity and error-correction capability. A single symbol is capable of encoding up to 1,850 text characters, 2,710 digits, or 1,108 bytes. By adding error correction codewords to the data message, PDF417 supports correction of lost or missing data. A PDF417 symbol is essentially a graphic image. The PDF417 plug-in converts text into a picture that can be placed on a 4D form for printing. PDF417 bar codes can be scanned only by scanners designed to read and decode this type of 2D bar code.
Installation To install the PDF417 plug-in into your 4D database, simply drop the PDF417.4DX file (and the PDF417.RSR file on Windows) into your Mac4DX or Win4DX folder. See the 4th Dimension Design Reference for additional details about these special folders. About the Demo Database A demonstration database has been included with this plug-in. It requires 4th Dimension v6.7.x. The demo database is not compiled or password protected, so you can examine or copy the source code. The database has two primary features. The main demo window allows you to create and print your own PDF417 bar codes. The database also allows you to connect a bar code scanner to your computer s serial port. Scanned data is then displayed on-screen.
Plug-In Commands PDF Make Symbol Example result:=pdf Make Symbol (symbol; text; rows; columns; limits; ecc) Parameters symbol picture Pass a picture variable or field. The plugin will insert the symbol image into this variable or field. text text The text to be encoded. rows integer Assign a row count limit from 3 to 90, or supply a fixed row count in the range of 3 through 90 or 0. columns integer Assign a column limit from 1 to 30, or supply a fixed column count in the range of 1 through 30, or 0. limits integer Pass 0 to interpret rows and columns as fixed values. Pass 1 to interpret rows and columns as upper limits. ecc integer Percent of symbol used for error correction (0-400) Return Value result integer Returns 1 if the symbol was successfully created, or an error code.
Possible values returned by this function: 1 success -11 The plug-in was unable to create a valid symbol from given the parameters passed to it. -998 the plug-in is not activated and evaluation time has expired. -999 means the row, col, limits, ecc combination is not valid Setting the row and column values Set the row and column counts used for sizing a PDF symbol. The values supplied can refer either to limits placed on row and column dimensions or to fixed values. How these values are interpreted relies on the value of the limit parameter. When defining both row and column values for the fixed dimension mode (limit parameter is set to 1), the matrix defined must describe a valid PDF symbol total codeword count must not exceed 928 codewords. For example, a request to define a 50 row by 19 column matrix fails since it describes a 950 codeword symbol (50 x 19 = 950). When the interpretation mode is set for fixed dimensions, the row and/or column count can optionally be set to zero. When either the row or column parameter is assigned a zero, this informs the encoder that the parameter is variable. For example, assume an rows parameter of 0 and an columns parameter of 5. A bar code that contains 30 codewords would result in a 6 row by 5 column bar code. Note that only one parameter can be assigned a zero value for the fixed dimension s mode. Setting the error correction percentage This function sets the ECC level as a percentage of data codewords. This percentage is used by the plug-in to dynamically select an ECC level (levels 0 through 8) based upon the number of data codewords in the bar code. The valid range is from 0% to 400%. A typical value for this feature might be 10%.
PDF Get Info This function returns to the application a detailed account of information for the most recently encoded bar code. Example result:=pdf Get Info (bytes; height; width; PadCW; DataCW; EccCW; rows; columns; EccLevel) Parameters size integer The size of the image in bytes. height integer The height of the image in pixels. width integer The width of the image in pixels. PadCW integer Padding codewords applied to the symbol. DataCW integer Data codewords applied to the symbol. EccCW integer Error correction codewords applied to the symbol. rows integer The number of rows in the PDF bar code. columns integer The number of data columns in the PDF bar code. EccLevel integer Error correction level of the symbol (0-8). Return Value result integer Returns 1 if the function is successfully able to return values. Note that the rows and columns parameters do not include the left and right row indicator columns, nor the start/stop patterns. PadCW represents the number of codewords applied to the bar code to fill the matrix. These codewords do not contribute to the decoded data. The DataCW value is the number of codewords which relate to the encoded source. This value does not include the data length codeword. EccCW is the number of codewords allocated for error correction. The rows and columns values represent number of columns actually used to create the PDF symbol. This information is provided since the plug-in may determine this number automatically if 0 is passed as the number of rows, or if the rows and columns specified in the call to PDF Make Symbol are specified to be upper limits (the limit parameter is set to 1).
PDF Activate Example result:=pdf Activate (macintosh code; windows code) Parameters mac code integer The Macintosh activation code. win code integer The Windows activation code. Return Value result integer Returns 1 if the plug-in is activated successfully. Until this command is called, the PDF417 plug-in operates in demo mode. Use this command to set the plug-in to normal operation. When the plug-in is not activated, it will replace the first 25 characters with the text <PDF417 Not Registered>. It will also put up an alert once after 30 minutes of use, then stop working. After this time out period, the PDF Make Symbol function will return error -998. After successfully calling the PDF Activate command, the first 25 characters will not be modified, and the plug-in will not time out. Printing PDF417 Bar Codes To print a PDF417 bar code created by this plug-in, simply create a variable on a form and print the form. The variable area will display the picture created by the call to PDF Make Symbol. See the demo application for an example. The variable should be set to display the image as centered and truncated. Make sure the area is large enough to display the entire symbol without truncating any part of it. PDF417 bar codes must not be scaled. Macintosh LaserWriter Problem The Macintosh LaserWriter drivers have an option in the Page Setup dialog, Smooth Graphic, that is on by default. This option thoroughly messes up the printing of PDF symbols, causing all the corners to be softened. Because this is considered a driverspecific user option, its setting in the print record is undocumented, and there is no officially condoned method for setting it programmatically. So to print the bar code properly from a 4D form, you must disable this option while designing the form. Do this by selecting Page Setup and selecting PostScript Options from the pop-up menu while the
form window is front most in 4D s design environment. Disable the Smooth Graphics option, then click OK to save your changes. Finally, save the 4D form. This setting will be retained when the form is later printed to a LaserWriter printer. Miscellaneous Information Bar Code Row & Column Sizes Rows are 3 pixels tall in the resulting symbol. A column is one of the vertical stripes in the symbol, 17 pixels wide. With fixed start and stop codes on either side of the symbol, one column yields a symbol 86 pixels wide, and every additional column adds 17 pixels. Note on ECC Padding A pad codeword is defined as the additional codeword(s) added to a PDF symbol to fill vacancies in the symbol s data region. These vacancies arise when the number of ECC codewords and data codewords is less than the PDF symbol s data region capacity. For example, a 20 row by 10 column symbol has a data region of 200 codewords. The pad codeword is meant to merely occupy space and provides no information, and the value chosen for this codeword is the TC latch codeword, 900. To make better use of this vacant space, the plug-in attempts to pad the symbol with ECC information, in lieu of the standard padding codeword. In other words, the encoder attempts to raise the ECC level to best fill the data region void. Any remaining vacant data region codewords are filled in with the standard padding codeword: 900. For example, assume the symbol size from the prior paragraph, 20 rows by 10 columns, that contained 200 data region codewords. If we encode a message at ECC level 2 that results in 180 data codewords, we are left with 11 vacant codewords: 200 codewords, less one data length codeword, 180 data codewords and 8 ECC codewords. To fill these 11 vacancies, the encoder automatically advances the ECC level to 3, 16 codewords, which leaves 3 codewords to be assigned the 900 padding codeword. Note that the encoder never lowers the ECC level to accommodate more data codewords in a symbol. Therefore, ECC levels you request are merely minimums and may not actually be the level applied to the symbol. If you must determine that actual ECC level assigned by the encoder, you can obtain this information through the PDF Get Info function. Support For assistance, contact DataCraft at: DataCraft 12081 West Alameda Pkwy, #506 Lakewood, CO 80228 Phone: 720-962-4886 Fax: 720-294-0182 Email: support@datacraft-inc.com Web: http://www.datacraft-inc.com/