Printronix SMARTLINE SL4M User manual

PXML Application Developer Reference Manual

PXML Application Developer Reference Manual

Trademark Acknowledgments
Printronix and PSA are registered trademarks of Printronix, Inc.
PXML, SL4M, and T4M are trademarks of Printronix, Inc.
COPYRIGHT 2006, 2007 PRINTRONIX, INC.
All rights reserved.

1 Overview ............................................................... 7
Introduction ............................................................................................ 7
Constraints............................................................................................. 8
2 PXML .................................................................... 9
PXML Selection ..................................................................................... 9
PTX_SETUP Commands To Activate PNE (Version 1.0) ............... 9
PTX_SETUP Commands To Activate UCP (Version 2.0)............. 10
PTX_SETUP Commands To Activate PXML ................................ 10
Transport ............................................................................................. 11
Messaging ........................................................................................... 11
Message Root ............................................................................... 11
Password Security ........................................................................ 12
Message Unique ID....................................................................... 12
Status ............................................................................................ 13
Job Markers ............................................................................ 13
Get Status Request ................................................................ 14
Automatic Status Select.......................................................... 14
Job Status Reply Message ..................................................... 15
Label Response Message ...................................................... 16
RFID Tag Response Message ............................................... 17
Display Response Message ................................................... 21
Fault Response Message ....................................................... 21
Engine Status Response Message......................................... 22
Statistics........................................................................................ 22
RFID Statistic Get Request..................................................... 22
RFID Statistic Clear Request.................................................. 23
RFID Statistic Response......................................................... 23
Reboot Request ............................................................................ 24
Information Request ...................................................................... 25
Information Get Request......................................................... 25
Printer Information Response ................................................. 25
Server Information Response ................................................. 27
rfidTagOption Information Response...................................... 27
Printer ACK or Error Response ..................................................... 28
PXML Inactive Error Response .............................................. 29
Table of Contents

Table of Contents
Printer Setting ............................................................................... 29
Printer Setting Get Request.................................................... 29
Printer Setting Select Request For rfidSetting ........................ 29
Time Setting Response .......................................................... 30
Time Set Request ................................................................... 30
PGL Error Handling Response ............................................... 30
PGL Error Handling Set Request............................................ 31
Network Setting Response ..................................................... 31
Network Set Request.............................................................. 33
RFID Setting Response .......................................................... 34
RFID Set Request................................................................... 34
Printer Configuration ..................................................................... 36
Load Configuration Request ................................................... 36
Save Configuration Request................................................... 36
Save Configuration Response ................................................ 37
Printer Storage .............................................................................. 37
Flash or EMC Storage Request.............................................. 37
Flash or EMC File System Directory Response ..................... 37
Flash or EMC Delete File Request ......................................... 38
Flash or EMC Read File Request ........................................... 39
Flash or EMC Read File Response ........................................ 39
Alerts.................................................................................................... 40
Validate Requests And Responses Using XML Schema .................... 45
A New Features In PXML ....................................... 47
Version 2.0........................................................................................... 47
Version 2.1........................................................................................... 47
B Formal PXML Schema ........................................ 49
C Contact Information............................................. 71
Printronix Customer Support Center.................................................... 71
Printronix Supplies Department ........................................................... 71
Corporate Offices................................................................................. 72

7
1Overview
Introduction
This manual describes a communication model for remotely managing
Printronix SL5000r/T5000r, SL4M/T4M, and P7000 printers. It is for
application developers to implement custom printer management schemes.
Two facets to the management model include:
•management messages and the operations and events that they describe
•the transport mechanism that moves the messages back and forth
between the printer and the client software.
The main component of the model is the Printronix XML Device Management
Language, which describes the management and response messages.
PXMLTM is an XML based language that allows a client application to issue
commands to a printer and receive responses from the printer. Responses
can be either a response to a command (solicited responses), or responses
generated by events that occur during printer operation (unsolicited
responses).
Please visit the Printronix website (www.printronix.com) to view the printer
models and firmware versions available with PXML.
PXML provides the following features:
•printer power-up modes – reset and download.
•different types of printer status reporting.
•job status reporting, including RFID tag and online data validation
information.
•configuration change.
•menu changes.

8
Chapter 1 Constraints
Constraints
•UCP (for GPIO) and PXML cannot be used at the same time in the
system. Only one can be active at any time.
•Only one client may connect to the management port at a time.
•The client is responsible for maintaining the TCP management
connection to the printer; reconnect as necessary. The management
connection may be lost at any time due to printer power-down or network
failure. Responses will be lost when the management connection is down
since there is no caching or retransmission mechanism.
•It is possible for a client to connect to the management port in the middle
of a response message, which at the same time is being sent to a
previous client. This is possible if the connection to the previous client is
dropped before the message is complete. It is the responsibility of the
new client to read and discard the remainder of the message.
•All responses are not synchronized, so a message immediately returned
after a command may not be the one that applies to the command. The
messages are in XML format and are guaranteed to be complete
messages, except when the management connection is lost and
reestablished while a message was being sent from the printer.
•XML messages must start with the <?xml> header so that invalid
messages can be ignored by the printer.
•The TCP transport mechanism does not provide a separate framing
protocol, so the input stream must be processed by an XML parser to
determine the end of a message. Alternatively, message framing can be
determined by searching for the <?xml> header, then capturing all data
until the </pxml> trailer is found.
•One response may span more than one message to relieve the printer
from having to buffer output messages. Messages that form a single
response are guaranteed to be sent in the correct sequence, and a flag is
provided to denote the final message of the sequence.
•For firmware download, the client is responsible for waiting for the printer
to enter download mode before sending data. The client is responsible for
waiting until the printer fully boots with the new firmware before sending
configuration data.
•Notification of start and end of print job must be initiated by some other
means, typically be placing PTX_SETUP commands in the print data
stream.

9
2PXML
PXML Selection
PrintNet Enterprise (PNE) is the Printronix proprietary management protocol
used by the Printronix PrintNet Enterprise software. PXML is the XML based
management protocol that serves as a direct interface between third party
software. In version 1.0, the printer factory default is PNE, but the user can
select which management protocol to use via PTX_SETUP commands or
from the front panel. PNE and PXML can't be use concurrently in the system,
only one can be active at any time. In version 2.0 and above, both PNE and
PXML are active at the same time. However, PXML and GPIO (UCP) share
the same channel and only one can be active at any time in version 2.0 and
above.
For the user connecting to the printer using third party application, there is an
initial setup. The initial setup is done with a PTX_SETUP file sent through the
printing port. This is only necessary for version 1.0 of PXML. The
PTX_SETUP file involves the following steps:
•Select PXML as management protocol
•Select Ethernet to be the interface for PXML
•Set 3007 as the PXML Port number
You can also use the front panel menu options to perform these steps.
To switch from PXML to PPM:
•Select PNE as management protocol
•Set 3001 as the PNE Port number
These steps can be done with a PTX_SETUP file or from changing the front
panel menu. A printer power cycle will be performed after the PNE or PXML
port number change and goes back online. The change stays persistent in the
printer.
PTX_SETUP Commands To Activate PNE (Version 1.0)
NOTE: Only necessary for version 1.0 of PXML support.
This sets up PNE using the Ethernet port on port number 3001 for version 1.0:
!PTX_SETUP
CONFIG-MPI_SELECT;PNE
CONFIG-PNE_PORT;ETHERNET
CONFIG-PNE_PORT_NUM;3001
PTX_END

10
Chapter 2 PXML Selection
PTX_SETUP Commands To Activate UCP (Version 2.0)
This sets up UCP using the Ethernet port on port number 3007 for version 2.0
and above:
!PTX_SETUP
CONFIG-MPI_SELECT;UCP
CONFIG-PNE_PORT;ETHERNET
CONFIG-PNE_PORT_NUM;3007
PTX_END
PTX_SETUP Commands To Activate PXML
This section defines PTX_SETUP commands that are used to activate PXML.
The default setting on printers with PXML version 2.0 and above is “PXML
enabled” on port 3007.
These commands are:
CONFIG-MPI_SELECT;value
where values are:
PNE (For version 1.0)
UCP (For version 2.0 and above)
PXML
CONFIG-PNE_PORT;value
where values are:
DISABLE
ETHERNET (if Ethernet is not available, try Adapter if it is
enabled)
CONFIG-PXML_PORT;value
Where values are:
DISABLE
ETHERNET (if Ethernet is not available, try Adapter if it is
enabled)
CONFIG-PNE_PORT_NUM;value
where value selects the active PNE Port Number.
NOTE: The printer automatically reboots after this command.
CONFIG-PXML_PORT_NUM;value
where value selects the active PXML Port Number.
NOTE: The printer automatically reboots after this command.

Message Root
11
This following sets up PXML using the Ethernet port on port number 3007:
!PTX_SETUP
CONFIG-MPI_SELECT;PXML
CONFIG-PXML_PORT;ETHERNET
CONFIG-PXML_PORT_NUM;3007
PTX_END
Transport
The printer provides a TCP server socket that can be opened by a client as a
telnet session. Only one socket is allowed to be open at a time. The factory
default is port 3001 for PNE protocol and 3007 for PXML protocol.
The client is responsible for opening and maintaining the session. The
connection could be broken at any time, either by a network error or by the
printer being powered down. The client must detect that the connection is
broken and reconnect to the port. Most TCP stacks do not immediately report
that the connection is down, so the client must ‘ping’ the printer on a regular
basis.
No separate framing protocol is provided, so the client must continuously
parse the incoming data stream for XML messages. The client may send XML
messages at any time.
Messaging
All messages are in XML format and are described by a formal XML schema.
Command messages are messages that are sent by the client to perform
some action or request information.
Response messages are messages that are sent by the printer, either as a
response to a command message or as an unsolicited message that is
triggered by a change of printer state or an event that occurs during a print
job.
All responses are not synchronized. When a command asks for a response, it
adds a request to an event queue. A reply to a command may be interspersed
with unsolicited messages, although all messages are guaranteed to be well
formed XML.
To protect the printer against unauthorized use, commands that affect printer
operation require a password to be embedded in the message. This password
is the same as the printer’s ‘telnet’ root password.
Message Root
All PXML messages are wrapped with a common root element, named pxml.
The standard XML header <?xml version=”1.0”?> must be sent at the
beginning of each message so that the XML parser can discard faulty
messages.

12
Chapter 2 Messaging
Password Security
For inbound messages (messages to the printer), an optional password can
be specified. For those commands that require a password, the string is
checked against the printer’s telnet password; the message is rejected if the
password does not match. For commands that do not require a password, the
string is ignored. Only commands that change printer setup requires a
password. For information inquiry commands a password is not required. By
default the NIC password is zero, or an empty string. To change the NIC
password, please refer to the Printronix
Network Interface Card User’s
Manual
.
<?xml version=”1.0” encoding="UTF-8"?>
<pxml password=”mypassword”>
.
.
.
</pxml>
Example of setting a password through telnet:
>set user passwd root mypassword
Message Unique ID
This feature is supported by PXML version 2.0 or higher. For inbound
messages (messages to the printer), an optional requestID number can be
specified. The generated response message will have the same requestID
attached to it.
None of the unsolicited messages will have any requestID attribute. If the
request does not include any ID, the response will have the requestID of 0.
Label, job, and RFID messages are unsolicited and do not include requested
ID. The label and job responses use the job ID, not the requestID.
The requestID value in any command sent to the printer needs to be between
1 and 4294967294. An example of a request sent to the printer with a
requestID include:
<?xml version="1.0"?>
<pxml requestID="203">
<info>
<get type="printer"/>
</info>
</pxml>
Response coming from the printer:
<?xml version="1.0" encoding="UTF-8"?>
<pxml requestID="203">
<info>
<server pxmlVersion="2.0" />
</info>
</pxml>

Status
13
Status
When certain events occur, the printer can send status messages to the client
as responses to the client’s request or as unsolicited notification. For
example, if a fault occurs, messages are sent to inform the client about the
fault condition. By default, the printer does not send unsolicited messages.
The management client can however, select the unsolicited messages to be
sent by the printer. This helps reduce the amount of traffic on the
management interface.
Job Markers
Printing can cause automatic replies due to the data that is being printed,
such as RFID tag data. Markers can be placed in the print stream to indicate
the start and end of a job. Print data can be queued so that the markers are
processed simultaneously with the print data. When a marker is processed, it
sends an automatic reply. This guarantees that a management client listening
to the management data stream reads the replies in the order they were
processed on the print data stream.
The maximum job number is 65535 (Decimal), for printers released before
Oct 2006, and 4294967295 for printers released later.
The host can print the following command to indicate the start of a print job.
Any number can be used as the job number to identify the job. This example
uses 1234.
!PTX_SETUP
PRINTJOB-START;1234
PTX_END
When the command is eventually processed, a Job Status Message is sent
with a jobStart type attribute.
The end of a job can also be indicated with a Job End marker:
!PTX_SETUP
PRINTJOB-END;1234
PTX_END
When this command is eventually processed, a Job Status Message is sent
with a jobEnd type attribute.

14
Chapter 2 Messaging
Get Status Request
The client sends the following command to request the printer to send status.
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<get type="fault"/>
</status>
</pxml>
The type attribute is used to specify the type of status to send, which can
include the any of the following:
Automatic Status Select
Changes in the printer state and some print operations can cause unsolicited
status messages to be sent to the management client. It is possible for the
management client to select the unsolicited messages to be sent. This can
reduce the amount of traffic on the management interface. The printer will
send an Ack message to confirm the status select command.
The printer default for all unsolicited status messages is disabled. To receive
any type of status messages, the select message is necessary to enable that
type of unsolicited status messages.
To enable or disable unsolicited messages, the management client sends the
following command:
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<select type="job" enable="true" version="2"/>
</status >
</pxml>
Table 1. Printer Attribute and Status - Get Status Request
Attribute Status
engine Send current engine status.
NOTE: Not supported on P7000 printers.
fault Send current fault status.
display Automatic panel display status.

Status
15
The type attribute is used to specify the type of status reports that are enabled
or disabled. Possible options for type include:
The enable attribute turns on or off automatic status for the specific type. The
valid parameters are Boolean type: false, 0, true, and 1.
NOTE: Job status messages are provided in an unsolicited fashion and
cannot be requested individually. The engine and fault status
messages can be received by request or as changes happen in the
system, if the select command is enabled.
Version attribute is only acceptable for the type=job.
Job Status Reply Message
NOTE: Not supported on P7000 printers.
Job Start and Job End markers in the print data stream generate the Job
Status Reply message. To receive these automatic start and end of the job,
the select command should be sent once to enable the automatic messages
as described in “Automatic Status Select” on page 14.
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="jobStart">
<jobDetail id="1234"/>
</job>
</status>
</pxml>
type = The type of the job information, specified by the marker. Possible
values include: jobStart, jobEnd, rfid, and label.
NOTE: Some types are only supported in PXML version 2.1 and higher.
The types are: errorLabel, partialLabel and errorReport.
These messages are generated for PGL jobs only.
id = The identifier specified by the marker. The id attribute only appears for
types jobStart and jobEnd.
Table 2. Printer Attribute and Status - Automatic Status Select
Attribute Status
display Automatic panel display status.
engine Automatic engine status.
fault Automatic fault status.
job Automatic job status.
NOTE: Only this option can have version 1 or 2 attributes.
Version=1 generates version 1 of rfidTagDetail element.
Version=2 generates version 2 of rfidTagDetail element.
Refer to “RFID Tag Response Message” on page 17.

16
Chapter 2 Messaging
The end of the job that is not completed successfully is announced by sending
the following message:
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="jobEnd">
<jobDetail id="1234" failure="1"/>
</job>
</status>
</pxml>
NOTE: The failure attribute is only sent by PXML version 2.1 or higher.
Label Response Message
NOTE: Not supported on P7000 printers.
The Label Response message is sent out at the end of each page or label. To
receive the label status message the select job message should be sent prior
to the start of the job or at system start up.
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="label">
<labelDetail failure="0"/>
</job>
</status>
</pxml>
The attributes for the labelDetail include:
failure = This is the result of printing a label.
Possible Boolean values are true, false, 0 (pass) or 1 (fail).
If the emulation encounters errors, error messages will be sent out as they are
recognized from the emulation. The error report option for PGL on the front
panel should be set to “on” or “host” to receive this message.
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="errorReport">
<jobDetail id="1234" error="135"/>
</job>
</status>
</pxml>

Status
17
If the emulation generates an error page, an error label message is reported
by sending the following:
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="errorLabel">
<labelDetail failure="0"/>
</job>
</status>
</pxml>
If part of the label does not print, a partial page message is reported by
sending the following:
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="partialLabel">
<labelDetail failure="0"/>
</job>
</status>
</pxml>
If the error is caused by RFID reader error such as RFID read, write error, or
ODV verification error, the message will read as follows:
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="label">
<labelDetail failure="1"/>
</job>
</status>
</pxml>
RFID Tag Response Message
NOTE: Not supported on P7000 printers.
Whenever an RFID Tag is encoded, a message generates. Depending on the
version of the job selected for automatic status select, one of the following
messages is returned.
If job version is set to one, rfidTagDetail version=1 is sent by the printer. This
message is only sent for writing to EPC field.
If job version is set to two, rfidTagDetail version=2 is sent by the printer. This
message is sent for reading or writing to EPC, TID, and USR fields.
The attributes for the rfidTagDetail include:
version= Version of the detail information
failure = A Boolean that indicates if the tag failed.

18
Chapter 2 Messaging
Version 1 Example:
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="rfid">
<rfidTagDetail version="1" failure="false">
<property name="type" value="Alien Squiggle 64"/>
<property name="length" value="64"/>
<property name="sequence" value="0000"/>
<property name="epc" value="0123456789ABCDEF"/>
<property name="prechecked" value="false"/>
<property name="retries" value="00"/>
<property name="errorCount" value="00"/>
<property name="totalTagCount" value="00"/>
<property name="totalTagFailures" value="00"/>
</rfidTagDetail>
</job>
</status>
</pxml>
The properties for rfidTagDetail version 1 include:
Table 3. Printer Attribute and Properties - RFID Tag Response Message, Version 1
Attribute Properties
type The tag type description.
length The number bits in the raw tag data.
sequence The number of RFID operations (read and write) performed including this
operation since power up.
epc The raw tag data in xsd:hexBinary format.
(The number of digits depends on the number of tag data bits.)
prechecked A Boolean that indicates that a tag has been pre-checked.
retries The number of bad tags that have already been voided while attempting to
write this tag data.
errorCount The number of errors seen when reading or writing this tag.
totalTagCount Same as the statistics for the menu “Tag Write Cnt” in Hex.
totalTagFailures Same as the statistics for the menu “Failed Tag Count” in Hex.

Status
19
Version 2 Example:
<?xml version="1.0" encoding="UTF-8"?>
<pxml>
<status>
<job type="rfid">
<rfidTagDetail version="2" failure="false">
<property name="chain" value="single"/>
<property name="length" value="64"/>
<property name="operation" value="write"/>
<property name="fieldType" value="EPC"/>
<property name="totalDatalength" value="64"/>
<property name="type" value="Alien Squiggle 64"/>
<property name="sequence" value="0000"/>
<property name="prechecked" value="false"/>
<property name="retries" value="00"/>
<property name="errorCount" value="00"/>
<property name="totalTagCount" value="00"/>
<property name="totalTagFailures"value="00"/>
<property name="data"value="0123456789ABCDEF"/>
</rfidTagDetail>
</job>
</status>
</pxml>
The properties for rfidTagDetail for version 2 include:
“chain” = first, last, middle, single. If data is sent in a sequence of chained
messages, there is more than one message to contain all data. Single means
all data is sent in a single message.
NOTE: The Host application needs to collect all data in the first, middle, and
last message to construct the data that was written to or read from the
tag.

20
Chapter 2 Messaging
Table 4. Printer Attribute and Properties - RFID Tag Response Message, Version 2
Attribute Properties
length The number of bytes in the data property.
operation Read or write. This will not be present in the middle or last chain.
fieldType USR, TID, EPC, and ACS. This will not be present in the middle or last
chain.
type The tag type description. This will not be present in the middle or last chain.
totalDatalength The total number of bits sent in all of the chained messages related to this
operation. This will not be present in the middle or last chain.
sequence The number of RFID operations (read and write) performed including this
operation since power up. This will not be present in the middle or last chain.
prechecked A Boolean indicating that a tag has been prechecked.
This will not be present in the middle or last chain.
retries The number of bad tags that have already been voided while attempting to
write this tag data. This will not be present in the the middle or last chain.
errorCount The number of errors seen when reading or writing this tag.
This will not be present in the middle or last chain.
totalTagCount Same as the statistics for the menu “Tag Write Cnt” in Hex.
This will not be present in the middle or last chain.
totalTagFailures Same as the statistics for the menu “Failed Tag Count” in Hex.
This will not be present in the middle or last chain.
data The raw tag data in xsd:hexBinary format.
The number of digits depends on the number of tag data bytes.
chain First, last, middle, and single. If data is sent in a sequence of chained
messages, there is more than one message to contain all data. Single
means all data is sent in a single message.