1. NiceLabel Help Center
  2. Automation
  3. Reference and Troubleshooting

Custom Commands

Using Custom Commands

NiceLabel commands are used in command files to control label printing. NiceLabel Automation executes the commands within command files in top-to-bottom order. For more details, see section Command Files Specifications.

You can use specific custom commands if they are available in your NiceLabel Automation product in form of an action.

Example 93. Example

It is possible to the use the SETPRINTPARAM command if you can select the Set Print Parameter action.

Pro_Enterprise.png

NiceLabel Commands Specification

COMMENT

;

When developing a command file, it is good practice to document your commands. This helps you decode what the script really does when you look at the code after some time. Use semicolon (;) at the beginning of the line. Everything following the semicolon is treated as comment and does not get processed.

CLEARVARIABLEVALUES

CLEARVARIABLEVALUES

This command resets variable values to their default values.

CREATEFILE

CREATEFILE <file name> [, <contents>]

This command creates a text file. Use the text file to give signal to a third party application that the print process has begun or ended, depending on the location where you put the command. Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources.

DELETEFILE

DELETEFILE <file name>

Deletes the specified file. Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources.

EXPORTLABEL

EXPORTLABEL ExportFileName [, ExportVariant]

This command automates the "Export to printer" command that is available in label designer. The label is exported directly to the printer and stored in printer memory for off-line printing. The user recalls the label using printer keyboard or by sending a command file to the printer. The same functionality is available also with Store label to printer action.

Note

To specify the label for exporting, use the LABEL command first.

  • ExportFileName: This mandatory parameter defines the file name of generated printer commands.

  • ExportVariant: Some printers support multiple export variants. When exporting manually, the user can select the export variant in the dialog. With the EXPORTLABEL command, you have to specify which export variant you want to use. The variants are visible in the label designer after you enable the Store/Recall printing mode.

    The first variant in the list has value 0. The second variant has value 1, etc.

    If you do not specify any variant type, value 0 is used as default.

For more information about off-line printing, see section Using Store/Recall Printing Mode.

IGNOREERROR

IGNOREERROR <on> [,<off>]

This command specifies that the error occurring in the JOB file does not terminate the printing process if the following errors occur:

  • Incorrect variable name is used.

  • Incorrect value is sent to the variable.

  • Label does not exist / is not accessible.

  • Printer does not exist / is not accessible.

LABEL

LABEL <label name> [,<printer_name>]

This command opens the label to be printed. If the label is already loaded, it does not get re-opened. You can include the path name. Enclose the label name in double quotes if the name or path contains spaces. Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources.

The optional printer_name specifies the printer, for which the label is opened. Use this setting if you want to override the printer name that is saved in the label template. If the driver for the provided printer name is not installed or not available, the command raises an error.

MESSAGEBOX

MESSAGEBOX <message> [,<caption>]

This command logs the custom message into the trigger log. If the message contains space characters or commas, enclose the text in double quotes (").

PORT

PORT <file name> [, APPEND]

This command overrides port as defined in the printer driver and redirects printing to a file. If file path or file name contain spaces, enclose the value in double quotes ("). Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources.

The APPEND parameter is optional. By default, the file gets overwritten. Use this parameter to append data into the existing file.

Once you use the PORT command in JOB file, it remains valid until the next PORT command, or until the end of file (whichever comes first). If you use PRINTER command after the PORT command has been executed, the PORT setting overwrites the port defined for the selected printer. If you want to use the actual port that is defined for the selected printer, you have to use another PORT command with empty value, such as PORT = "".

PRINT

PRINT <quantity> [,<skip> [,<identical label copies> [,number of label sets]]]

This command starts the printing process.

  • Quantity: Specifies the number of printed labels.

    • <number>: The specified number of labels gets printed.

    • VARIABLE: Specifies that a label variable is defined as variable quantity and that it contains the number of labels to be printed. The label determines how many labels get printed.

    • UNLIMITED: If you use a database to acquire values for objects, unlimited printing prints as many labels as there are records in the database. If you do not use a database, the maximum number of labels that thermal printer internally supports gets printed.

  • Skip: Specifies the number of labels you want to skip on the first page. The parameter is used for printing labels on sheets of paper. If the part of the page has already been used, reuse the same sheet by shifting the starting location of the first label.

  • I dentical label copies: Specifies how many copies of the same label must be printed.

  • Number of label sets. Specifies the number of times the whole printing process should repeat itself.

Note

Make sure the quantity values are provided as numeric value, not as a string value. Do not enclose the value in double quotes.

PRINTER

PRINTER <printer name>

This command overrides the printer as defined in the label file. If the printer name contains space characters, enclose it in double quotes (").

Use the printer name as displayed in the status line of label design application. Printer names usually match the listed names under Printers and Faxes in Control Panel, but not always. If using network printers, you might see the name displayed in syntax \\server\share.

PRINTJOBNAME

PRINTJOBNAME

This command specifies the print job name as displayed in Windows Spooler. If the name contains space characters or commas, enclose the value in double quotes (").

SESSIONEND

SESSIONEND

This command closes print stream. Also see SESSIONSTART.

Note

SESSIONEND must be sent as the only item in Send Custom Command action. If you want to send additional commands, use separate Send Custom Command actions.

SESSIONPRINT

SESSIONPRINT <quantity> [,<skip>]

This command prints the currently referenced label and adds it into the currently open session-print stream. You can use multiple SESSIONPRINT commands one after another and join the referenced labels in a single print stream. The stream does not close until you close it using SESSIONEND command. The meaning of quantity and skip parameters is the same as with NiceCommand PRINT. Also see SESSIONSTART command.

  • Quantity: Specifies the number of labels to be printed.

  • Skip: Specifies the number of labels you want to skip on the first page. The parameter is used for printing labels on sheets of paper. If the part of the page has already been used, you can reuse the same sheet by shifting the start location of the first label.

SESSIONSTART

SESSIONSTART

This command initiates the session-print type of printing.

The three session-print-related commands ( SESSIONSTART, SESSIONPRINT, SESSIONEND) are used together. When you use command PRINT, data for each label is sent to the printer in a separate print job. If you want to join label data for multiple labels into a print stream, use the session print commands. To do so, start with the SESSIONSTART command, followed by any number of SESSIONPRINT commands. The sequence ends with SESSIONEND command.

Use these commands to optimize label printing process. Printing of labels that belong to a single print job is much faster than printing labels using multiple print jobs.

Use the rules below to make sure the session print does not break:

  • You cannot change the label within a session.

  • You cannot change the printer within a session.

  • You must set values for all variables from the label within a session, even if some of the variables have empty values.

SET

SET <name>=<value> [,<step> [,<number or repetitions>]]

This command assigns the variable name with value. The variable must be defined on the label, or an error is raised. If the variable isn't on the label, an error occurs. Step and number of repetitions are parameters for counter variables. These parameters specify the counter increment value and the number printed labels before the counter changes value.

If a value contains spaces or comma characters, enclose the text in double quotes ("). Also see TEXTQUALIFIER.

If you want to assign a multi-line value, use \r\n to encode a newline character. \r is replaced with CR (Carriage Return) and \n is replaced with LF (Line Feed).

Be careful when setting values to variables that provide data for pictures on the label, as backslash characters might be replaced with other characters.

Example 94. Example

If you assign a value "c:\My Pictures\raw.jpg" to the variable, the "\r" is replaced with CR character.


SETPRINTPARAM

SETPRINTPARAM <paramname> = <value>

This command allows you to fine-tune the printer settings just before printing. The supported parameter for printer settings ( paramname) are:

  • PAPERBIN: Specifies the tray that contains label media. If the printer is equipped with more than one paper / label tray, you can control which one is used for printing. The name of the tray should be acquired from the printer driver.

  • PRINTSPEED: Specifies the printing speed. The acceptable values vary from one printer to the other. See printer's manuals for exact range of values.

  • PRINTDARKNESS: Specifies the printing darkness / contrast. The acceptable values vary from one printer to another. See printer manuals for exact range of values.

  • PRINTOFFSETX: Specifies the left offset for all printing objects. The value for parameter must be numeric, positive or negative, in dots.

  • PRINTOFFSETY: Specifies the top offset for all printing objects. The value for parameter must be numeric, positive or negative, in dots.

  • PRINTERSETTINGS: Specifies the custom printer settings to be applied to the print job. The parameter requires the entire DEVMODE for the target printer, provided in a Base64-encoded string. The DEVMODE contains all parameters from the printer driver at once (speed, darkness, offsets and other). For more information, see section Understanding printer settings and DEVMODE.

    Note

    The Base64-encoded string must be provided inside double quotes (").

TEXTQUALIFIER

TEXTQUALIFIER <character>

Text-qualifier is the character that embeds data value that is assigned to a variable. Whenever a data value includes space characters, it must be included with text-qualifiers. The default text qualifier is a double quote character ("). Because double quote character is used as shortcut for inch unit of measure, it is sometimes difficult to pass the data with inch marks in the JOB files. You can use two double quotes to encode one double quote, or use TEXTQUALIFIER.

Example

TEXTQUALIFIER %

SET Variable = %EPAK 12"X10 7/32"%