^PQ - Print Quantity
Prints the label more than once, which is the one command here that changes how many pages come back.
^PQ asks for more than one copy of the label format it appears in. It is the
one command in this category that changes the response rather than the printer:
a quantity of three returns three pages and X-Total-Count: 3. The quantity
belongs to one ^XA…^XZ block and does not carry into the next. A document of
several formats needs a ^PQ in every format that must repeat.
Syntax
^PQq,p,r,o,eSupport
The command renders, with the caveat below.
The renderer applies the label count: ^PQ3 returns three identical pages and counts as three in X-Total-Count. It also applies the replicates argument r, but only where it is observable, which is a label carrying ^SN: r sets how many pages one serialized value occupies. The remaining three arguments are printer mechanics that the parser reads and the renderer ignores. — not pinned by a test
Labelary renders this command.
Parameters
qLabel countoptional · integerHow many copies of this label format to render. Every copy is identical unless the label carries ^SN.
- Default
- 1
- Accepted range
- 1 to 99999999
- Invalid value
- clamped to the nearest allowed value. A quantity of 0 renders one page, matching Labelary. The renderer clamps the upper end to 10,000 and reports the clamp (see below).
- Test coverage
- Bounds pinned: minimum (1), maximum (10000), below the minimum (0). The invalid-value rule is pinned by 1 test, including the diagnostic it emits.
pLabels between pausesoptional · integernot honoured by zpl.toolsHow many labels to print before a pause for the operator.
- Default
- 0
- Accepted range
- 0 to 99999999
- Invalid value
- clamped to the nearest allowed value. The renderer clamps the value to 99,999,999, as Labelary does (measured 2026-07-12); nothing reads it.
- Test coverage
- Bounds pinned: minimum (0), above the maximum (100000000). No test at the maximum. The invalid-value rule is not pinned by a test.
rReplicates per serial numberoptional · integerHow many output pages each serialized value occupies. It divides q rather than adding to it, so the page count stays at q.
- Default
- 0
- Accepted range
- 0 to 99999999
- Invalid value
- clamped to the nearest allowed value. The renderer clamps the value to 99,999,999. A value of 0 gives one page per serialized value, as an absent argument does.
- Test coverage
- Bounds pinned: above the maximum (100000000). No test at the minimum or maximum. The invalid-value rule is not pinned by a test.
oOverride pauseoptional · Y or Nnot honoured by zpl.toolsPrevents the pause that p causes.
- Default
- N
- Invalid value
- discarded, and the default applies. The parser reads and discards the argument; no pause exists.
- Test coverage
- No documented value is exercised by a test (Y, N). The invalid-value rule is not pinned by a test.
Y- Prevent pauses
N- Accept pauses (default)
eCut on erroroptional · Y or Nnot honoured by zpl.toolsWhether the printer cuts the media after an error label.
- Default
- Y
- Invalid value
- discarded, and the default applies. The parser reads and discards the argument. No cutter exists.
- Test coverage
- No documented value is exercised by a test (Y, N). The invalid-value rule is not pinned by a test.
Y- Cut after an error label (default)
N- Do not cut
Behavior
The position of the command inside the format makes no difference. The parser
collects the quantity as it reads the format, and the renderer applies it when
the format closes at ^XZ. ^PQ before the first field and ^PQ after the
last therefore behave alike. Two of them in one format leave the last one in
force.
Every copy is identical unless the label carries ^SN, which advances a number
on each copy. The third argument r sets how many output pages each value
occupies. ^PQ4,0,2 prints two pages of the first number, then two of the
second.
Page indices in the API address output pages, not label formats. With ^PQ3,
indices 0, 1 and 2 each return a copy of the same label, and a format that
follows starts at index 3.
A quantity of 0 returns one page rather than none, which matches Labelary. The renderer clamps a quantity above 10,000 to 10,000 and reports a warning. A dozen bytes of ZPL must not ask for a hundred-million-page document.
Tested behavior
Differences from the specification
Labelary against the ZPL II guide
Where Labelary — our compatibility target — behaves differently from the printed specification.
- The fifth argument,
e, is Labelary's. The guide's format line is^PQq,p,r,o, and its parameter table stops ato.ebelongs to firmware newer than the 2006 edition. — not pinned by a test - Labelary accepts
pfrom 0, and documents that value as the default. The guide's accepted range for the same argument starts at 1, but the guide still gives 0 as its default. The guide contradicts itself here, and Labelary gives the usable reading. — pinned bytest_pq_pause_cut_zero_is_silent
zpl.tools against Labelary
Where our output differs from Labelary for the same input. These are the differences that break a migration.
- The renderer clamps the quantity to 10,000 pages and reports the clamp as a warning. Labelary rejects an unreasonable quantity with HTTP 413, so no measurement covers its upper bound. A bounded document is more useful than an error. — pinned by
test_pq_count_past_the_page_cap_is_cut_and_reported
Example
Related commands
^XAStart FormatBegins a label format.^XZEnd FormatEnds a label format and prints it.^SNSerialization DataMakes the current field a counter that steps by a fixed amount for each copy `^PQ` prints.^PMPrint Mirror ImageMirrors the finished label left-to-right about its vertical centerline.