BOX (Box) keyword in printer files

You use this record-level keyword to print a rectangle.

The format of the keyword is: 
BOX(first-corner-down | &first-corner-down-field
first-corner-across | &first-corner-across-field
diagonal-corner-down | &diagonal-corner-down-field
diagonal-corner-across | &diagonal-corner-across-field
line-width | &line-width-field
[color value])

The first-corner-down, first-corner-across, diagonal-corner-down, and diagonal-corner-across parameters define the diagonal corners of the box. All are required parameters.

You can specify the corner position parameters as constants, program-to-system fields, or a combination of both, as shown in the following lines:
  • BOX(1.2 0.5 5.1 6.3 0.2)
  • BOX(1.2 &field2 5.1 &field4 0.2)
  • BOX(&field1 &field2 &field3 &field4 0.2)

The first-corner-down parameter defines the vertical starting point of the BOX relative to the margins specified on the FRONTMGN or BACKMGN parameter of the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in.).

When you specify the first-corner-down parameter as a program-to-system field, the field must exist in the same record format as the BOX keyword. It must be defined as length of 5 with 3 decimal positions, data type S (character), and usage P (program-to-system).

The first-corner-across parameter defines the horizontal starting point of the BOX relative to the margins specified on the FRONTMGN or BACKMGN parameter of the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in.).

When you specify the first-corner-across parameter as a program-to-system field, the field must exist in the same record format as the BOX keyword. It must be defined as length of 5 with 3 decimal positions, data type S (character), and usage P (program-to-system).

The diagonal-corner-down parameter defines the vertical end point of the BOX relative to the margins specified on the FRONTMGN or BACKMGN parameter of the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in.).

When you specify the diagonal-corner-down parameter as a program-to-system field, the field must exist in the same record format as the BOX keyword. It must be defined as length of 5 with 3 decimal positions, data type S (character), and usage P (program-to-system).

The diagonal-corner-across parameter defines the horizontal end point of the BOX relative to the margins specified on the FRONTMGN or BACKMGN parameter of the CRTPRTF command. Valid values are 0 to 57.790 cm (0 to 22.750 in.).

When you specify the diagonal-corner-across parameter as a program-to-system field, the field must exist in the same record format as the BOX keyword. It must be defined as length of 5 with 3 decimal positions, data type S (character), and usage P (program-to-system).

The line-width parameter is required and defines the width of the lines. Valid values are 0.001 to 57.790 cm (0.001 to 22.750 in.). The following special values can also be specified:

Value Line width
*NARROW 12/1440 in. (0.008 in., 0.022 cm)
*MEDIUM 24/1440 in. (0.017 in., 0.042 cm)
*WIDE 36/1440 in. (0.025 in., 0.064 cm)

When you specify the line-width parameter as a program-to-system field, the field must exist in the same record format as the BOX keyword. It must be defined as length of 5 with 3 decimal spaces, data type S (character), and usage P (program-to-system). The special values of *NARROW, *MEDIUM, or *WIDE cannot be specified using a program-to-system field.

Notes:
  1. The UOM parameter on the CRTPRTF command determines the units of measure for the first-corner-down, first-corner-across, diagonal-corner-down, diagonal-corner-across, and line-width parameter values. If the value specified for a parameter is outside the valid range, it is flagged when the spooled file is created.
  2. Depending on printer hardware, lines smaller than approximately 0.010 cm (0.004 in.) might not print because of printer resolution. No message is issued when this occurs.

The line width is drawn on the inside of the box.

Color

The optional color parameter lets you specify the color of the lines. Specify the color as an expression in one of the following forms:

  • Color name method: (*COLOR color-name)
  • RGB (red/green/blue) color model: (*COLOR *RGB rvalue gvalue bvalue)
  • CMYK (cyan/magenta/yellow/black) color model: (*COLOR *CMYK cvalue mvalue yvalue kvalue)
  • CIELAB color model: (*COLOR *CIELAB lvalue c1value c2value)
  • Highlight color model: (*COLOR *HIGHLIGHT hvalue coverage)

Using the BOX keyword

When the BOX keyword is specified on a record format, all fields within the record format must be positioned using the POSITION keyword.

An error message is issued if a constant field is specified in a record format where the BOX keyword is also specified.

An error message is issued at application run time if the box extends beyond the page boundaries.

Specify DEVTYPE(*AFPDS) on the CRTPRTF command when BOX is specified in the file. If DEVTYPE is changed to anything other than *AFPDS, the keyword is ignored and a warning message is issued at print time.

You can specify this keyword multiple times on a record.

You cannot specify BOX with the SPACEA, SPACEB, SKIPA, or SKIPB keywords.

Option indicators are valid for this keyword.

Example 1

The following example shows how to specify the BOX keyword.

|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
     A*
     A          R BOX1                      BOX(1.2 0.5 5.1 6.3 0.2)
     A*
     A          R BOX2                      BOX(2 5 5.0 3.33 *WIDE)
     A                                      BOX(0.5 0.1 2.1 2.0 0.09)
     A*
     A          R BOX3
     A  01                                  BOX(0 0 8.5 11.0 0.5)
     A*
     A          R BOX4                      BOX(2.5 0.5 5.1 6.3 0.2 +
     A                                      (*COLOR *HIGHLIGHT 3 75)
     A
Note: The UOM parameter on the CRTPRTF command determines the units of measure for the parameter values.

BOX1 prints a box with one corner located 1.2 units down and 0.5 units across from the location specified on the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. The diagonal corner of this box is located 5.1 units down and 6.3 units across from the margins specified on the CRTPRTF command. The edges of the box are 0.2 units wide.

BOX2 prints two boxes. The first box starts 2 units down and 5 units across from the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. The diagonal corner of this box is located 5.0 units down and 3.33 units across from the margins specified on the CRTPRTF command. The edges of the box are determined by the special value *WIDE.

The second box starts 0.5 units down and 0.1 units across from the margins specified on the FRONTMGN or BACKMGN parameter on the CRTPRTF command. The diagonal corner of this box is located 2.1 units down and 2.0 units across from the margins specified on the CRTPRTF command. The edges of the box are 0.09 units wide.

BOX3 prints only if indicator 01 is on.

BOX4 specifies to use highlight color 3 (which is determined by printer) with 75% coverage.

Example 2

The following example shows how to specify the BOX keyword. 
|...+....1....+....2....+....3....+....4....+....5....+....6....+....7....+....8
      *
                R BOX1                      BOX(2 3 4 7 0.2)
      *
                R BOX2                      BOX(3 5 6 9 0.2)
      *
      *

The following example illustrates the location of the boxes using the DDS code in example 2. BOX1 spans columns 3 through 7 and rows 2 through 4. BOX2 spans columns 5 through 9 and rows 3 through 6.

An illustration of the results produced by Example 2.