BOX (Box) keyword in printer files

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]
[shading])

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:

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.
Depending on printer hardware, lines smaller than approximately 0.004 in. (0.010 cm) 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)

Shading

The optional shading parameter lets you specify shading for the box. Specify the shading as expression in the following form:

(*SHADE coverage color)

The shading coverage specifies how dark the shading should be. Specify the coverage as an integer from 0 to 100 that matches the percentage of shading that you want. You also can specify one of the following special values:

*XLIGHT
*LIGHT
*MEDIUM
*DARK
*XDARK

The default is *MEDIUM if you do not specify a coverage value.

The color specifies which color you want the shading to be. If you do not specify a color, then the color prints with the default color of the medium. Specify the color in the same manner as you specify the previous line colors on the color parameter. For example, to specify coverage and color for shading using the RGB color model, specify as follows:

(*SHADE *MEDIUM (*COLOR *RGB rvalue gvalue bvalue))

Notes:

When you specify box shading with no color or with the basic color model, IM1 image is used as the fill pattern. This works best on 240/300/600 pel printers. It might produce unsatisfactory results on the 4224, 4234, and 64XX printers.
When you specify box shading with an extended color model (RGB, CMYK, or CIELAB), IOCA image is used for the fill pattern. IM1 image does not support these color models. The IPDS™ printer must support IOCA image for this to print properly.
When you specify box shading with an extended color model, the following monochrome IPDS printers support gray scaling when you specify highlight color:
- Infoprint^® 60
- Infoprint 62
- Infoprint 2000
- Infoprint 3000
- Infoprint 4000
These printers must be at ucode level 8.3 or later.

Use 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(1.2 0.5 5.1 6.3 0.2 +
     A                                      (*SHADE 50))
     A          R BOX5                      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 shading with 50% coverage and default color for shading.

BOX5 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.

An illustration of the results produced by Example 2. BOX1 spans columns
3 through 7 and rows 2 through 4. BOX2 spans columns 5 through 9 and rows
3 through 6.