Command files are plain text files that contain instructions for the printing process – these instructions are expressed using NiceLabel commands. Commands are executed one at a time from the beginning until the end of the file.
supports the following command file types:
Note
The files support Unicode formatting. This allows you to include multi-lingual content.
JOB command file is text file that contains native NiceLabel printing commands. The commands execute in order from top to bottom. The sequence of commands usually starts with LABEL (open label). LABEL command is followed by SET (to set variable value), and finally by PRINT (print label).
JOB command file can be executed using the following actions:
NiceLabel commands are used in command files to control label printing. Desktop Designer executes the commands within command files from top to bottom.
COMMENT
;
If developing a command file, it is a good practice to document your commands. This helps you decode what the script really performs, when you check the code after some time. Use a semicolon (;) at the beginning of the line. Everything that follows the semicolon is treated as a comment and is not processed.
CLEARVARIABLEVALUES
CLEARVARIABLEVALUES
This command resets variable values to their default values.
CREATEFILE
CREATEFILE <file name> [, <contents>]
This command creates a text file. You can use it to signal a third party application that the printing process has begun or ended, depending on the location where command is put. Use the UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation user guide.
DELETEFILE
DELETEFILE <file name>
Deletes the specified file. Use UNC syntax for network resources. For more information, see section Access to Network Shared Resources in NiceLabel Automation user guide.
EXPORTLABEL
EXPORTLABEL ExportFileName [, ExportVariant]
This command is implemented to automate the "Export to printer" command that is available in the label designer. The label is exported directly to the printer and stored in the memory for off-line printing. The user can recall the label using the keyboard on the printer 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 LABELcommand first.
-
ExportFileName. This parameter is mandatory and defines the file name of generated printer commands.
-
ExportVariant. Some printers support multiple export variants. If exporting them manually, the user can select the export variant in the dialog. With the EXPORTLABEL command, you must 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 holds the value 0. The second variant has the 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 topic Using Store/Recall Printing Mode.
IGNOREERROR
IGNOREERROR <on> [,<off>]
Specifies that the below listed JOB file errors do not terminate the printing process:
-
Incorrect variable name is used.
-
Incorrect value is sent to a variable.
-
Label does not exist / is not accessible.
-
Printer does not exist / is not accessible.
LABEL
LABEL <label name> [,<printer_name>]
The command opens a label to be printed. If the label is already loaded, it will not be 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 topic Access to Network Shared Resources in NiceLabel Automation User Guide.
The optional parameter printer_name specifies the printer, for which the label will be 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>]
Logs the custom message into the trigger log. If the message contains space characters or commas, you have to 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 topic Access to Network Shared Resources in NiceLabel Automation User Guide.
The parameter APPEND is optional. By default, the file is overwritten. Use this parameter to append data into the existing file.
Once you use a PORT command in the 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 an empty value, such as PORT = "".
PRINT <quantity> [,<skip> [,<identical label copies> [,number of label sets]]]
This command starts the print process.
-
Quantity. Specifies the number of labels to print.
-
<number>. Specified number of labels will print.
-
VARIABLE. Specifies that some label variable is defined as variable quantity and will contain the number labels to print. The label will determine how many labels to print.
-
UNLIMITED. If you use a database to acquire values for objects, unlimited printing will print as many labels as there are record in the database. If you do not use a database, the maximum number of labels that thermal printer internally supports will 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. When the part of the page has already been used, you can reuse the same sheet by Shifting the start location of the first label.
-
Identical label copies. Specifies how many copies of the same label must print.
-
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 the numeric value, not string value. Do not enclose the value in the double quotes.
PRINTER
PRINTER <printer name>
This command overrides the printer 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 in the label design application. Printer names are usually the same as the printer names in Printers and Faxes from Control Panel, but not always. If using network printers, you might see the name displayed using syntax \\server\share.
PRINTJOBNAME
PRINTJOBNAME
This command specifies the print job name to be seen in Windows Spooler. If the name contains space characters or commas, you have to enclose the value in double quotes (").
SESSIONEND
SESSIONEND
This command closes the print stream. Also see SESSIONSTART.
Note
SESSIONEND must be sent as the only item in Send Custom Command action. If you would like 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 the SESSIONEND command. The meaning of quantity and skip parameters is the same as with NiceLabel command PRINT. Also see SESSIONSTART.
-
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 a 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, every label data will be sent to the printer in a separate print job. If you want to join label data for multiple labels into print stream, you should use the session print commands. You must start with the command SESSIONSTART, followed with any number of SESSIONPRINT commands and in the end the command SESSIONEND.
Use these commands to optimize label printing process. Printing labels coming from one print job is much faster than printing labels from a bunch of print jobs.
There some rules you have to follow so the session print will 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 will have empty values
SET
SET <name>=<value> [,<step> [,<number or repetitions>]]
This command assigns a value to the name variable. 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 and the number labels before the counter changes value.
If value contains spaces or comma characters, you must enclose the text in double quotes ("). Also see TEXTQUALIFIER.
If you want to assign multi-line value, use \r\n to encode 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 some other characters.
Example 143. Example
If you assign a value "c:\My Pictures\raw.jpg" to the variable, the "\r" will be replaced with CR character.
SETPRINTPARAM
SETPRINTPARAM <paramname> = <value>
This command allows you to set fine-tune 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 just one paper / label tray, you can control which 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 the other. See printer's 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 topic Understanding printer settings and DEVMODE in NiceLabel Automation User Guide.
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 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, sometimes it is 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.
This JOB file opens the label2.nlbl label, sets variable values and prints a single label. Because no PRINTER command is used to redirect printing, the label will be printed using the printer name as defined in the label.
LABEL "label2.nlbl" SET code="12345" SET article="FUSILLI" SET ean="383860026501" SET weight="1,0 kg" PRINT 1
The commands available in the XML Command Files form a subset of NiceLabel commands. You can use the following commands:
-
LOGIN
-
LABEL
-
SET
-
PORT
-
PRINTER
-
SESSIONSTART
-
SESSIONEND
-
SESSIONPRINT
The syntax requires minor adaptation if used in an XML file.
XML command file can be executed using the following actions:
The root element in the XML Command file is <Nice_Commands>. The next element that must follow is <Label>– it specifies the label to be used.
Two methods are available to start the label printing:
-
Print the labels normally using the
<Print_Job>element. -
Print the labels in a session using the
<Session_Print_Job>element.
You can also change the printer using which the labels are going to be printed, and set the variable value.
This section defines the XML Command file structure. There are several elements that contain attributes. Some attributes are required, while the others are optional. Some attributes can occupy pre-defined values only. For others, you can specify custom values.
-
<Nice_Commands>. This is a root element.
-
<Label>. Specifies the label file to be opened. If the label is already open, it won't be re-opened. The label file must be accessible from this computer. For more information, see the topic Access to Network Shared Resources in NiceLabel Automation user guide. This element can occur several times within the command file.
-
Name. This attribute contains label name. You can include the path to the label name. Mandatory element.
-
-
<Print_Job>. The element that contains data for one label job. This element can occur several times within the command file.
-
Printer. Use this attribute to override the printer defined in the label. The printer must be accessible from this computer. For more information, see the topic Access to Network Shared Resources. Optional element.
-
Quantity. Use this attribute to specify the number of labels to print. Possible values: numeric value, VARIABLE or UNLIMITED. For more information on parameters, see the topic Print Label. Mandatory element.
-
Skip. Use this attribute to specify the number of skipped labels at the beginning. This feature is useful if you print sheet of labels to laser printer, but the sheet is partial already printed. For more information, see the topic Print Label. Optional element.
-
Job_name. Use this attribute to specify the name of your job file. The specified name is visible in the print spooler. For more information, see the topic Set Print Job Name. Optional element.
-
Print_to_file. Use this attribute to specify the file name where you want to save the printer commands. For more information, see the topic Redirect Printing to File. Optional element.
-
Identical_copies. use this attribute to specify the number of copies you need for each label. For more information, see the topic Print label. Optional element.
-
-
<Session_Print_Job>. The element that contains commands and data for one or more sessions. The element can contain one or more
<Session>elements. It considers session print rules. You can use this element several times within the command file. For available attributes look up the attributes for the element<Print_Job>. All of them are valid, you just cannot use the quantity attribute. See the description of the element<Session>to find out how to specify label quantity in session printing. -
Store_job. Use this attribute to store your label to the printer. For more information, see the topic Store Label to Printer.
-
Store_name. With this value, you store your label to the printer. Optional element.
-
Store_variant. Storage unit where you store your label (USB memory, SD card, DRAM). See your printer driver settings for the exact names. Optional element.
-
Job_name. Use this attribute to specify the name of your job file. The specified name is visible in the print spooler. For more information, see the topic Set Print Job Name. Optional element.
Note
To Recall labels from your printer use the same elements as for printing.
When job_name element is empty the label name element value is used to recall the correct label from the printer's memory.
-
-
<Session>. The element that contains data for a single session. When printing in session, all labels are encoded into a single print job and are sent to the printer as one job.
-
Quantity. Use this attribute to specify the number of labels to print. Possible values: numeric value, string VARIABLE, or string UNLIMITED. For more information on parameters, see the topic Print Label. Required.
-
Skip. Specifies the number of labels that are skipped on the first page of labels. The sheet of labels might have been printed once already, but not entirely. You can re-use the same sheet by offsetting the starting position. This option is applicable, if you print labels to sheets of labels, not rolls of labels, so it's effective for office printers and not for label printers. Possible values: numeric value or string VARIABLE. For more information on parameters, see the topic Print Label. Optional.
-
Identical_copies. Specifies the number of label copies to be printed for each unique label. For fixed labels, this option produces the same result as the main Number of Labels option. For variable labels, such as labels using counters, you can get the real label copies. Possible values: numeric value or string VARIABLE. For more information on parameters, see the topic Print Label. Optional.
-
Number_of_sets. Specifies how many times the entire label printing process should repeat. Possible values: numeric value or string VARIABLE. For more information on parameters, see the topic Print Label. Optional.
-
-
<Variable>. The element that sets the value of variables on the label. This element can occur several times within the command file.
-
Name. The attribute contains the variable name. Required.
-
XML Schema Definition (XSD) for XML Command File
<?xml version="1.0" encoding="utf-8"?>
<xs:schema targetNamespace="http://tempuri.org/XMLSchema.xsd" elementFormDefault="qualified" xmlns="http://tempuri.org/XMLSchema.xsd" xmlns:mstns="http://tempuri.org/XMLSchema.xsd" xmlns:xs="http://www.w3.org/2001/X
MLSchema">
<xs:element name="nice_commands">
<xs:complexType>
<xs:sequence>
<xs:element name="label" maxOccurs="unbounded" minOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="print_job" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="database" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="table" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="variable" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="quantity" type="xs:string" use="required" />
<xs:attribute name="printer" type="xs:string" use="optional" />
<xs:attribute name="skip" type="xs:integer" use="optional" />
<xs:attribute name="identical_copies" type="xs:integer" use="optional" />
<xs:attribute name="number_of_sets" type="xs:integer" use="optional" />
<xs:attribute name="job_name" type="xs:string" use="optional" />
<xs:attribute name="print_to_file" type="xs:string" use="optional" />
<xs:attribute name="print_to_file_append" type="xs:boolean" use="optional" />
<xs:attribute name="clear_variable_values" type="xs:boolean" use="optional" />
</xs:complexType>
</xs:element>
<xs:element name="session_print_job" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element name="database" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="table" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="session" minOccurs="1" maxOccurs="unbounded">
<xs:complexType>
<xs:sequence>
<xs:element name="variable" minOccurs="0" maxOccurs="unbounded">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute name="name" type="xs:string" use="required" />
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="quantity" type="xs:string" use="required" />
<xs:attribute name="skip" type="xs:string" use="optional" />
<xs:attribute name="identical_copies" type="xs:string" use="optional" />
<xs:attribute name="number_of_sets" type="xs:string" use="optional" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="printer" type="xs:string" use="optional" />
<xs:attribute name="skip" type="xs:integer" use="optional" />
<xs:attribute name="job_name" type="xs:string" use="optional" />
<xs:attribute name="print_to_file" type="xs:string" use="optional" />
<xs:attribute name="print_to_file_append" type="xs:boolean" use="optional" />
<xs:attribute name="clear_variable_values" type="xs:boolean" use="optional" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="name" type="xs:string" use="required" />
<xs:attribute name="close" type="xs:boolean" use="optional" />
<xs:attribute name="clear_variable_values" type="xs:boolean" use="optional" />
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute name="quit" type="xs:boolean" use="required" />
</xs:complexType>
</xs:element>
</xs:schema>
The sample below presents the structural view on the elements and their attributes as you can use them in an XML command file.
<nice_commands>
<label name="label1.nlbl">
<session_print_job printer="CAB A3 203DPI" skip=0 job_name="job name 1" print_to_file="filename 1">
<session quantity="10" skip="2" identical_copies="1" number_of_sets="4">
<variable name="variable name 1" >variable value 1</variable>
</session>
</session_print_job>
<print_job printer="Zebra R-402" quantity="10" skip=0 identical_copies=1 number_of_sets=1 job_name="job name 2" print_to_file="filename 2">
<variable name="variable1" >1</variable>
<variable name="variable2" >2</variable>
<variable name="variable3" >3</variable>
</print_job>
</label>
</nice_commands>
This sample presents storing a label to the printer.
<nice_commands> <label name="label1.nlbl" close="false"> <store_job store_name="label011" store_variant= "DRAM" printer="Zebra R-402" job_name="recall011"> <variable name="country" >Slovenia</variable> <variable name="packaging_type" >big box</variable> <variable name="Warehouse_no" >3</variable> </store_job> </label> </nice_commands>
The commands available in CSV command files form a subset of NiceLabel commands. You can use the following commands: LABEL, SET, PORT, PRINTER and PRINT.
CSV command file can be executed using the following actions:
CSV command file is a text file in which the values are delimited by comma (,) character. The text file can contain Unicode value (important for multi-language data). Each line in the CSV command file contains commands for a single label print action.
The first row of CSV command file must contain commands and variable names. The order of commands and names is not important, but all records in the same data stream must follow the same structure. Variable name-value pairs are extracted automatically and sent to the label that is referred to them.
Note
No error is raised if the variable with its name included in the CSV does not exist on the label.
The commands in the first line of data must be expressed with at (@) character. The fields without @ at the beginning are names of variables, and they will be extracted with their values as name-value pairs.
-
@Label. Specifies the label name to be used. It's a good practice to include label path and filename. Make sure the service user can access file. For more information, see the topic Access to Network Shared Resources in NiceLabel Automation user guide. Mandatory field.
-
@Printer. Specifies the printer to use. It overrides the printer defined in the label. Make sure the service user can access the printer. For more information, see the topic Access to Network Shared Resources in NiceLabel Automation user guide. Optional field.
-
@Quantity. Specifies the number of labels to print. Possible values: numeric value, VARIABLE or UNLIMITED. For more information, see the topic in NiceLabel Automation user guide. Mandatory field.
-
@Skip. Specifies the number of labels to skip at the beginning of the first printed page. This feature is useful if you want to re-use the partially printed sheet of labels. Optional field.
-
@IdenticalCopies. Specifies the number of label copies that should be printed for each unique label. This feature is useful when printing labels with data from database or when you use counters, and you need label copies. Optional field.
-
@NumberOfSets. specifies the number of times the printing process should repeat. Each label set defines the occurrence of the printing process. Optional field.
-
@Port. Specified the port name for the printer. You can override the default port as specified in the printer driver. You can also use it to redirect printing to file. Optional field.
-
Other field names. All other fields define names of variables from the label. The field contents will be saved to the variable of the same name as its value.
The sample below presents a structural overview of fields that you can use in a CSV command file.
@Label,@Printer,@Quantity,@Skip,@IdenticalCopies,NumberOfSets,@Port,Product_ID, Product_Name label1.nlbl, CAB A3 203 DPI, 100, , , , , 100A, Product 1 label2.nlbl, Zebra R-402, 20, , , , , 200A, Product 2
PAS command file is a text file that contains Loftware LPS printing commands. The commands execute in order from top to bottom. Each PAS file must start with the *FORMAT (open label) command, and end with the *PRINTLABEL command.
PAS command file can be executed using the action Run Command File.
Note
If you migrated from Loftware to NiceLabel, you can use your existing PAS command files with NiceLabel label templates (.nlbl) *FORMAT command checks if .nlbl file exists with the same name as .lwl.
*FORMAT,\\127.0.0.1\labelcomputer$\labels\ML2193.lwl *JOBNAME,PastaPallet002 *QUANTITY,1 *PRINTERNUMBER,1 Text0000,New Data Text0001,New Data *PRINTLABEL
Note
If you want to use *PRINTERNUMBER command, you must copy the printr32.ini file from LPS to c:\Program Files\NiceLabel\NiceLabel 10\\bin.net\Configuration.
You can find more details about PAS commands in Loftware LPS User Guide.