Print job
The simplest form deselects any existing jobs, or selects a single label, but it can also set up a database driven job. The job can either replace the existing job, or add it to a queue.
All parameters are optional, but there needs to be one to specify the label, i.e. labelName, labelColumn, labelColumns or labelData.
A table can be used in three ways:
- Key lookup:
tableName,keyColumnandkeyselect a single row. - Sequential:
tableNamewithoutkeyColumnprints the rows fromfirstRow, one label per row, forrowCountrows. The label is given bylabelName, or bylabelColumnto print a different label for each row v5.3.4. When both are set,labelNameis used for rows where thelabelColumncell is empty. - Round robin:
tableName,keyColumnandkeyselect a single row, andlabelColumnsprints the label of each of the given columns of the row in turn, see Round robin v6.1.
| Parameter | Type | Description |
|---|---|---|
| alignment | string | Alignment of the label within targetLength: START, CENTER, or END. Defaults to the printer's alignment setting v6.0, see Target length. |
| autoPrintGap | distance | Auto-print gap. A plain number is interpreted as nanometers. |
| autoPrintInterval | distance | Auto-print interval. A plain number is interpreted as nanometers. |
| checkpoint | boolean | See the seekPrintQueueCheckpoint API method. |
| checkpointTimeout | number | Seek the print queue to the checkpoint, as seekPrintQueueCheckpoint does, when the job has been first in the queue for this many seconds without printing. Cannot be set on a checkpoint job. v6.1 |
| copyLabel | boolean | If true, the job takes a copy of the label given by labelName when it is selected, so that later changes to the label don't affect it. Unlike freeze, counters, date and time and variables are still updated on each print. Has no effect on a table job. Default is false. v6.0 |
| copies | number | Limit the number of copies to print. Default is unlimited. |
| copiesColumn | string | Table column where the number of copies to print is available. |
| description | string | Description which will be displayed on the Overview tab in the user inteface. Left out when the job is read back if it was not set v6.0. |
| firstRow | number | First table row index to use in a sequential table job. Defaults to 0. |
| freeze | boolean | If true, then the label will be frozen, i.e. the current label content, as well as all dynamic text, will be copies and unaffected by any changes. It will also cause all used counters to increment immediately. The default value is the value of the queue parameter, except for a job with labelColumns, which cannot be frozen. |
| hAlign | string | Along-web alignment of the label within targetLength, taking precedence over alignment when set: LEFT, CENTER, or RIGHT. LEFT/RIGHT map to START/END according to the print direction. v5.0 |
| hOffset | distance | Shifts the print along the web. A plain number is interpreted as millimeters. A positive value always moves the print to the right regardless of the print direction. Applied only when targetLength is set, and clamped so the net change to position is never negative. v5.0 |
| key | string | Value to search for in the keyColumn of the table. |
| keyColumn | string | Column in which to search to select the row to use. |
| labelName | string | The name of a label. |
| labelData | Label | A complete label object. |
| labelColumn | string | Table column where the label name is available. In a sequential table job, it may also be a zero-based column index v5.3.4. |
| labelColumns | array | The table columns, by name or zero-based index, whose labels a round-robin job prints in turn. Cannot be combined with labelColumn, labelName, copiesColumn or printedColumn. v6.1 |
| maxTriggerDistance | distance | Only accept triggers up to this distance from the current position, see Trigger window. A plain number is interpreted as millimeters. Ignored if maxTriggerPos is set. v5.4 |
| maxTriggerPos | number | Only accept triggers up to this absolute position in meters, see Trigger window. v5.4 |
| minTriggerDistance | distance | Only accept triggers from this distance from the current position, see Trigger window. A plain number is interpreted as millimeters. Ignored if minTriggerPos is set. v5.4 |
| minTriggerPos | number | Only accept triggers from this absolute position in meters, see Trigger window. v5.4 |
| printDelay | distance | Per-job print delay override. A plain number is interpreted as millimeters. v4.5 |
| printedColumn | string | Table column where to number of printed labels is stored. The value in this column will be incremented when printing. |
| queue | boolean | If true, then the label will be added to the end of the queue of jobs, else it will replace any existing queue with this job. |
| rowCount | number | Number of table rows to use in a sequential table job. Defaults to all remaining rows from firstRow. |
| repeatPrintGap | distance | Repeat print gap. A plain number is interpreted as nanometers. |
| repeatPrintInterval | distance | Repeat print interval. A plain number is interpreted as nanometers. |
| roundRobin | boolean | If set, then the print job will be moved to the back of the queue when completed. |
| roundRobinIdleTimeout | number | Restart the sequence of a round-robin job from its first label when it has waited this many seconds for a trigger after printing a label of the sequence. Only with labelColumns. v6.1 |
| stepCounters | boolean | If true, step counters when the job is frozen. Default is true. |
| tableName | string | The name of a table. |
| targetHeight | distance | Target print height across the web. A plain number is interpreted as millimeters. Used together with vAlign. v5.0 |
| targetLength | distance | Target print length. A plain number is interpreted as millimeters. Used together with alignment. Since v6.0, it defaults to the printer's targetLength setting, and zero means no target length, see Target length. v4.5 |
| vAlign | string | Cross-web alignment of the label within targetHeight: TOP, CENTER, or BOTTOM. Defaults to BOTTOM. The target height itself is aligned on the printheads by the printer's vertical alignment setting v6.1, which is BOTTOM by default, see Vertical alignment. v5.0 |
Auto-print
Auto-print is a feature that automatically triggers a job after the previous job is completed, and the configured gap/interval has elapsed.
In v4.2.0 through v4.3.x, if there were no other print jobs waiting in
the queue, the job was automatically printed once the configured gap/interval
had elapsed. Since v4.4.0 this is no longer the case: if the queue is empty,
the auto-print parameters are ignored.
Trigger window
The trigger window limits the positions at which a job accepts triggers. The position is the one reported by getSpeedInfo. A trigger before the start of the window is ignored, and a trigger after the end of the window removes the job from the queue, and the trigger is passed on to the next job in the queue.
The window can be given as absolute positions with minTriggerPos and
maxTriggerPos, or relative to the position when the job is selected with
minTriggerDistance and maxTriggerDistance. When the job is read back, for
example with getCurrentPrintJob,
the window is always reported as minTriggerPos and maxTriggerPos.
Target length
The target length is the length of the product, starting at the trigger. The
label is aligned within it by alignment or hAlign, and shifted by
hOffset.
Triggers within the target length of the previous product, for example from
gaps or holes in the product seen by the photocell, are ignored and counted in
the triggers.ignored.withinTarget
statistic. A reverse limit while idle
ends this lockout, since the product may be presented again. v6.0
With a target length, a repeat print goes on the next product rather than on
the same one, aligned within its own target length. repeatPrintInterval is
then the distance between the starts of products, and repeatPrintGap the
distance between them. A repeated label that would overlap the previous one is
an error. v6.0
A job without targetLength and alignment uses the printer settings
targetLength and alignment (Product length and Label alignment on the
product in the printer's label settings), which are zero and START by
default. A zero target length turns it off, also in a job that overrides a
printer setting. v6.0
Vertical alignment
The printer setting Vertical alignment in the printer's label settings
aligns the label to the top, center or bottom of the printheads, and the
vertical offset setting then moves it, with a positive value always moving it
up. The default is bottom, which is how labels were always aligned before.
A job with targetHeight has its target height aligned by the setting, and
the label aligned within it by vAlign. v6.1
Round robin
A round-robin job prints the labels of one table row in turn, one label per
print, starting over after the last v6.1. It is selected with
tableName, keyColumn and key, which select the row, and labelColumns,
the columns that name the labels. This is useful for example when marking
pallets, where each block of the pallet gets its own mark.
- A column whose cell in the row is empty is left out when the job is selected. Selecting fails if all of them are empty.
- The labels of a sequence are taken from the row as it was when the first of them was printed, and a counter that several of the labels use is stepped once per sequence.
copiescounts whole sequences. Withoutcopies, the job prints until it is deselected.- With
roundRobinIdleTimeout, the sequence starts over from the first label when the printer has waited that long for a trigger after printing a label of the sequence. The gap between two products then puts the printer back in step, also after a missed or extra trigger. - getCurrentPrintJob
returns the number of labels of the current sequence that have been printed
as
roundRobinStep, which is also the index inlabelColumnsof the next label to print.
Before v6.1, round robin was done with a queue of jobs, one per label, with
roundRobin set, and the first one a checkpoint job. That still works, and
checkpointTimeout on the jobs after the first restarts such a sequence
after idle time, the way roundRobinIdleTimeout does.
Examples
Deselect all print jobs (clearing the queue):
{}
Select a single label "MyLabel":
{"labelName": "MyLabel"}
Select a single label "MyLabel", limit to a single print, and add to the end of the queue:
{
"labelName": "MyLabel",
"copies": 1,
"queue": true
}
Search the table "MyTable" in the column "Product" for "MyProduct", and select the label from the column "Label":
{
"tableName": "MyTable",
"keyColumn": "Product",
"key": "MyProduct",
"labelColumn": "Label"
}
Print every row of the table "MyTable", using the label named in the column "Label", or "DefaultLabel" for rows where that column is empty:
{
"tableName": "MyTable",
"labelColumn": "Label",
"labelName": "DefaultLabel"
}
Look up "Pallet1" in the column "Product" of the table "Pallets", and print the labels of the columns "Block1", "Block2" and "Block3" in turn, starting over from "Block1" after two seconds without a trigger:
{
"tableName": "Pallets",
"keyColumn": "Product",
"key": "Pallet1",
"labelColumns": ["Block1", "Block2", "Block3"],
"roundRobinIdleTimeout": 2
}
Queue the label "MyLabel" for a single print, accepting triggers only between 100 and 250 millimeters from the current position:
{
"labelName": "MyLabel",
"copies": 1,
"queue": true,
"minTriggerDistance": 100,
"maxTriggerDistance": 250
}