| Customize Help

Customizing write operation settings


This section provides information to consider and describes settings that you might have to change for write operations.

It is strongly recommended that you define your codes as completely as possible using the available control settings, since it will facilitate reading them later on. When writing a code, ensure that you are familiar with the requirements and restrictions of your chosen code type; otherwise, the code will not be generated and a MIL error will result.

Destination buffer size

The destination image buffer of the write operation should be large enough to hold the encoded string. For a given code type, cell size, and string, you can inquire about the minimum buffer size required by first calling McodeWrite() with its image buffer parameter set to M_NULL and then using McodeGetResult() with M_WRITE_SIZE_X and M_WRITE_SIZE_Y.

Special characters

If you need to encode unprintable characters, such as a carriage return or tab, use a code type that supports them. If you use McodeWrite() with M_ESCAPE_SEQUENCE, you can use ASCII codes to encode all unprintable characters. In the string to encode, the unprintable character's ASCII code must be in hexadecimal format and be preceded by \x (for example, \x0D for ASCII 13, which is the carriage return).

If you want to encode the "\" character in escape sequence mode, type "\\".

The encoded string for a Codabar code type must be numeric, but can contain the following characters: minus (-), dollar sign ($), colon (:), slash (/), period (.), and plus (+). In addition, the string must start and end with any of the following characters: a, b, c, or d. The encoded string for a Maxicode code type with the M_ENC_MODE2 or M_ENC_MODE3 encoding scheme, must respect the structured carrier message format (the portion of the string that contains postal code, country code, and class of service information).

Foreground color

Setting the foreground color is essential for write operations. To set the foreground color, use McodeControl() with M_FOREGROUND_VALUE. The default foreground color is black.

Cell size and number

In most cases, you should not have to specify the cell size when writing codes; the default setting (McodeControl() with M_CELL_SIZE_MIN set to M_DEFAULT) is sufficient. In this case, the code is resized so as to just fit into the destination image of the operation, when possible. During a write operation, you can use McodeControl() with M_CELL_SIZE_MIN to force the cell size; the cell size is used to determine the size of the generated code. If you specify the required cell size with McodeControl(), you should ensure that the destination image has an appropriate size. See the Destination buffer size subsection of this section.

The M_CELL_SIZE_MAX control type is not used in write operations.

During a write operation, the number of cells will be automatically chosen to minimize the code written. To specify the number of cells in a 2D code, use McodeControl() with M_CELL_NUMBER_X and M_CELL_NUMBER_Y. If you specify more cells than are necessary to generate the code, fill characters will automatically be added. If you specify fewer cells than are necessary to generate the code, you will get a MIL error. Specifying the number of cells is mostly useful when writing PDF417, Truncated PDF417, Data Matrix, and QRCodes code types; the Maxicode code type has a fixed number of cells. For the PDF417 code type, M_CELL_NUMBER_X must equal 17c + 35, where c is the number of columns, and 35 represents the number of cells required for the start and stop patterns. For the Truncated PDF417 code type, M_CELL_NUMBER_X must equal 17c + 18, where c is the number of columns, and 18 represents the number of cells required for the start patterns.

Bearer bars

Note that MIL does not generate bar codes with bearer bars. To generate a code with bearer bars, generate the required code and then draw a rectangle at the top and bottom of the code using MgraRectFill(); the minimum width of the bearer bar (height of the rectangle) must respect the specifications of your code type.

Writing EAN 14 code types

Strings encoded with the EAN 14 code type should all start with "(01)", which helps to identify the encoding type of the string. If, for some reason, the string to encode does not start with "(01)", McodeWrite() will add it automatically. The string to encode as an EAN 14 code can be either 13 or 14 digits in length. The optional fourteenth digit is a check digit calculated based on the first 13 digits according to Modulo 10. If the fourteenth digit is provided, MIL will validate it. If it is not provided, however, MIL will calculate it and add it.

Writing GS1-128 code types

Strings encoded with the GS1-128 code type typically start with a two-digit number inside parentheses (for example, (13)). The parentheses surrounding the number will not be written as part of the encoded string, as long as the number matches one of the valid application identifiers for GS1-128 (EAN/UCC_128). If this number is invalid, the parentheses are written as normal characters in the code.