Skip to main content

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, keyColumn and key select a single row.
  • Sequential: tableName without keyColumn prints the rows from firstRow, one label per row, for rowCount rows. The label is given by labelName, or by labelColumn to print a different label for each row v5.3.4. When both are set, labelName is used for rows where the labelColumn cell is empty.
  • Round robin: tableName, keyColumn and key select a single row, and labelColumns prints the label of each of the given columns of the row in turn, see Round robin v6.1.
ParameterTypeDescription
alignmentstringAlignment of the label within targetLength: START, CENTER, or END. Defaults to the printer's alignment setting v6.0, see Target length.
autoPrintGapdistanceAuto-print gap. A plain number is interpreted as nanometers.
autoPrintIntervaldistanceAuto-print interval. A plain number is interpreted as nanometers.
checkpointbooleanSee the seekPrintQueueCheckpoint API method.
checkpointTimeoutnumberSeek 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
copyLabelbooleanIf 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
copiesnumberLimit the number of copies to print. Default is unlimited.
copiesColumnstringTable column where the number of copies to print is available.
descriptionstringDescription 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.
firstRownumberFirst table row index to use in a sequential table job. Defaults to 0.
freezebooleanIf 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.
hAlignstringAlong-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
hOffsetdistanceShifts 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
keystringValue to search for in the keyColumn of the table.
keyColumnstringColumn in which to search to select the row to use.
labelNamestringThe name of a label.
labelDataLabelA complete label object.
labelColumnstringTable column where the label name is available. In a sequential table job, it may also be a zero-based column index v5.3.4.
labelColumnsarrayThe 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
maxTriggerDistancedistanceOnly 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
maxTriggerPosnumberOnly accept triggers up to this absolute position in meters, see Trigger window. v5.4
minTriggerDistancedistanceOnly 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
minTriggerPosnumberOnly accept triggers from this absolute position in meters, see Trigger window. v5.4
printDelaydistancePer-job print delay override. A plain number is interpreted as millimeters. v4.5
printedColumnstringTable column where to number of printed labels is stored. The value in this column will be incremented when printing.
queuebooleanIf 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.
rowCountnumberNumber of table rows to use in a sequential table job. Defaults to all remaining rows from firstRow.
repeatPrintGapdistanceRepeat print gap. A plain number is interpreted as nanometers.
repeatPrintIntervaldistanceRepeat print interval. A plain number is interpreted as nanometers.
roundRobinbooleanIf set, then the print job will be moved to the back of the queue when completed.
roundRobinIdleTimeoutnumberRestart 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
stepCountersbooleanIf true, step counters when the job is frozen. Default is true.
tableNamestringThe name of a table.
targetHeightdistanceTarget print height across the web. A plain number is interpreted as millimeters. Used together with vAlign. v5.0
targetLengthdistanceTarget 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
vAlignstringCross-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.

tip

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.
  • copies counts whole sequences. Without copies, 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 in labelColumns of 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
}