^IL - Image Load

^IL draws a whole stored label image as the background of the label under construction. The fixed part of a design — rules, boxes, headings — is then one bitmap, and only the variable data changes per label. ^IL is the recall half of

^IS, and the pair serves throughput: one raster costs far less than a hundred drawing commands.

Syntax

^ILd:o.x

Support

Supportedparsed: full · state: full · rendered: full

Every documented parameter renders the same output Labelary produces.

The background is drawn under everything else the format draws, wherever the ^IL stands in it, and takes its position from ^LH alone. An ^IL naming a label saved by ^IS still finds nothing, because ^IS stores no raster. — pinned by test_il_draws_under_a_field_written_before_it

Labelary renders this command.

Parameters

dStorage deviceoptional · single character

Which memory device to load from.

Default: R:
Invalid value: enough to stop the field being printed. A letter no printer answers to rejects the whole recall: the renderer reports the device and draws no background. The default is R: alone, and a path with no device is not looked for on the other devices.
Test coverage: The invalid-value rule is pinned by 2 tests, including the diagnostic it emits.

oObject nameoptional · text

Name of the image to load.

Default: UNKNOWN
Invalid value: enough to stop the field being printed. The renderer reports RESOURCE_MISSING for a name never downloaded, and draws no background.
Test coverage: The invalid-value rule is pinned by 1 test.

xExtensionoptional · text

Extension of the image to load.

Default: .GRF
Invalid value: enough to stop the field being printed. The extension is part of the lookup and is kept as written, so ^ILR:LOGO.PNG does not find the graphic downloaded as LOGO.GRF.
Test coverage: The invalid-value rule is pinned by 1 test.

Behavior

^IL has no position arguments and takes none from the field it sits in. The image lands at 0,0. Measured against Labelary on 2026-08-22: ^FO300,300, ^FT300,900, ^FWR and ^LS60 all leave it there, and so does a ^PW narrower than the label, which shifts every ordinary field. Only ^LH moves it, and ^LT, which moves the whole finished label. That is the difference from ^IM, which draws the same picture wherever the field origin says.

The image is a background in the full sense: it goes under everything the format draws, wherever the ^IL stands in that format. A reverse-printed frame cuts the same hole in the loaded raster whether its field comes before the ^IL or after it. Putting ^IL at the top of the format, as the guide recommends, therefore documents the intent rather than producing the effect.

Two ^IL commands in one format both draw. A recalled raster draws its black dots and leaves its white ones alone, so the two rasters add up.

The path rule is ^IL's own. An omitted device is R, an omitted name is UNKNOWN, and an omitted extension is .GRF — so a bare ^IL looks for R:UNKNOWN.GRF. A written extension is kept as written, where ^XG would fold an unrecognized one onto .GRF. A path with no device is not searched for on the other devices either.

An ^IL that names a label saved by ^IS finds nothing here. ^IS stores no raster in this renderer, because a page is built as a drawing-command stream rather than as a whole-label bitmap. Store the background with ~DG or ~DY instead, and ^IL draws it.

Differences from the specification

Example

A background loaded from a stored graphic, with variable data over it:

~DGR:BG.GRF,00080,010,
FFFFFFFFFFFFFFFFFFFF
8000FFFF0000FFFF0001
8000FFFF0000FFFF0001
8000FFFF0000FFFF0001
FFFF0000FFFF0000FFFF
FFFF0000FFFF0000FFFF
FFFF0000FFFF0000FFFF
FFFFFFFFFFFFFFFFFFFF
^XA
^ILR:BG.GRF^FS
^FO50,120^A0N,30,30^FDvariable data^FS
^XZ

Open in viewer

^IM Image MoveDraws a stored image at the current field origin.
^IS Image SaveSaves the current label image into printer memory.
^XG Recall GraphicDraws a previously downloaded graphic, optionally magnified.