^HY - Upload Graphics

^HY reads a stored graphic out of printer memory and returns it to the host. It extends ^HG, which recalls a graphic into the label. ^HY moves the object the opposite way, off the printer, and can convert it on the way out. That direction is why it cannot affect a rendered label.

Syntax

^HYd:o.x

Support

Recognised, deliberately skippedparsed: none · state: none · rendered: none

Accepted and skipped, because it configures the printer rather than the label. It cannot change the rendered output, and Labelary skips it too.

Reads an object out of printer memory and returns it over the printer's link. The transfer direction is what makes it inert here: like ^HG, it moves an object outward and draws nothing. The object store only holds what ~DG downloaded in the same request. The renderer does not parse this command. It reports IGNORED_COMMAND at info severity, which does not reach X-Warnings. Labelary is also silent, so the rendered label is identical in both engines. — not pinned by a test

Labelary renders this command.

Parameters

dStorage deviceoptional · single character

Which memory device to read from: R:, E:, B: or A:.

Default: the printer's own search priority across the devices
Invalid value: not documented, and we have not measured it. The renderer does not parse or measure this command.
Test coverage

oObject namerequired · text

Name of the object to upload, one to eight alphanumeric characters, as ~DG or ~DY stored it. The guide requires a name.

Invalid value: not documented, and we have not measured it. The renderer does not parse or measure this command.
Test coverage

xUpload formatoptional · one of a set

Which image format to send the object back in.

Default: the format the object is stored in
Invalid value: not documented, and we have not measured it. The renderer does not parse or measure this command.
Test coverage: No documented value is exercised by a test (G, P).

G: .GRF, raw bitmap
P: .PNG, compressed bitmap

Behavior

The reply is not a raw image. The guide states the printer answers with a complete ~DY command, the download command for the same object, and its data field is always ZB64-encoded. A round trip from one printer to another therefore resends what came back.

A render request has nowhere to upload to. Its object store holds only what its own ~DG or ~DY commands put there, and it ends with the request. The renderer ignores the command, and the page is unchanged. It reports IGNORED_COMMAND at info severity, which does not reach X-Warnings. Labelary is also silent. Render the label to take a graphic out of a format.

Differences from the specification

Labelary against the ZPL II guide

Where Labelary — our compatibility target — behaves differently from the printed specification.

Labelary documents one path argument, with the default R:UNKNOWN.GRF. The guide documents three: a device that defaults to the printer's search priority, and a required name. The third is an extension that selects the upload format and defaults to the stored object's own format. — not pinned by a test

Example

Asking for a stored graphic while printing a line of text. Only the text reaches the page.

^XA
^HYR:SAMPLE.GRF
^FO50,50^A0N,40,40^FDUpload^FS
^XZ

Open in viewer

^HG Host GraphicUploads a stored graphic back to the host.
~DG Download GraphicDownloads an ASCII-hex bitmap into printer memory as a `.GRF` object.
^XG Recall GraphicDraws a previously downloaded graphic, optionally magnified.
^HW Host Directory ListSends a listing of the objects held in printer memory back to the host.