DirectIO

Overview

Through the DirectIO feature a POS application communicates directly with the underlying CoreScanner Service.

This method provides a means for a UnifiedPOS Service to provide functionality to the application that is not otherwise supported by UnifiedPOS control for its device category.

Information in this chapter is applicable to both scanner and scale devices.

DirectIO Java Package

The necessary classes to perform DirectIO are contained in the JposService.jar file under the two namespaces:

  • com.zebra.jpos.service
  • com.zebra.jpos.service.directio

The package com.zebra.jpos.service contains the DirectIO method, while the package com.zebra.jpos.service.directio contains the supporting classes to leverage the DirectIO method.

Zebra JPOS Direct IO implementation is similar to the Scanner SDK.

com.zebra.jpos.service.directio

The directio package contains the following supporting class:

  • DirectIOCommand

DirectIO Command


public class DirectIOCommand {

    // Common for Scanner and Scale
    public static final int DIO_GET_SCANNERS = 1;
    @Deprecated
    public static final int GET_SCANNERS = DIO_GET_SCANNERS;
    public static final int DIO_RSM_ATTR_GETALL = 0x1388;                       // 5000
    @Deprecated
    public static final int RSM_ATTR_GETALL = DIO_RSM_ATTR_GETALL;
    public static final int DIO_RSM_ATTR_GET = 0x1389;                          // 5001
    @Deprecated
    public static final int RSM_ATTR_GET = DIO_RSM_ATTR_GET;
    public static final int DIO_RSM_ATTR_GETNEXT = 0x138A;                      // 5002
    @Deprecated
    public static final int RSM_ATTR_GETNEXT = DIO_RSM_ATTR_GETNEXT;
    public static final int DIO_RSM_ATTR_SET = 0x138C;                          // 5004
    @Deprecated
    public static final int RSM_ATTR_SET = DIO_RSM_ATTR_SET;
    public static final int DIO_RSM_ATTR_STORE = 0x138D;                        // 5005
    @Deprecated
    public static final int RSM_ATTR_STORE = DIO_RSM_ATTR_STORE;
    public static final int DIO_RTA_GET_SUPPORTED = 0x157C;                     // 5500
    @Deprecated
    public static final int CMD_RTA_SUPPORTED_GET = DIO_RTA_GET_SUPPORTED;
    public static final int DIO_RTA_UNREGISTER = 0x157E;                        // 5502
    @Deprecated
    public static final int CMD_RTA_UNREGISTER = DIO_RTA_UNREGISTER;
    public static final int DIO_RTA_GET_EVENT_STATUS = 0x157F;                  // 5503
    @Deprecated
    public static final int CMD_RTA_ALERT_STATUS_GET = DIO_RTA_GET_EVENT_STATUS;
    public static final int DIO_RTA_SET_EVENT_STATUS = 0x1580;                  // 5504
    @Deprecated
    public static final int CMD_RTA_ALERT_STATUS_SET = DIO_RTA_SET_EVENT_STATUS;
    public static final int DIO_RTA_SUSPEND = 0x1581;                           // 5505
    @Deprecated
    public static final int CMD_RTA_SUSPEND = DIO_RTA_SUSPEND;
    public static final int DIO_RTA_GETSTATE = 0x1582;                          // 5506
    @Deprecated
    public static final int CMD_RTA_STATE = DIO_RTA_GETSTATE;
    public static final int DIO_SCANNER_LOAD_CONFIG = 0x139C;                   // 5020
    @Deprecated
    public static final int CMD_LOAD_CONFIGURATION = DIO_SCANNER_LOAD_CONFIG;

    // Scanner Specific
    public static final int DIO_SCANNER_UPDATE_FW_DAT = 0x1398;                 // 5016
    @Deprecated
    public static final int CMD_DEVICE_UPDATE_FIRMWARE_DAT = DIO_SCANNER_UPDATE_FW_DAT;
    public static final int DIO_SCANNER_UPDATE_FW_PLUGIN = 0x1399;              // 5017
    @Deprecated
    public static final int CMD_DEVICE_UPDATE_FIRMWARE_FROM_PLUGIN = DIO_SCANNER_UPDATE_FW_PLUGIN;

    // NCR Scanner
    public static final int NCR_DIO_SCANNER_TONE = 0x01F5;                      // 501
    @Deprecated
    public static final int DIO_NCR_SCAN_TONE = NCR_DIO_SCANNER_TONE;
    public static final int NCR_DIO_SCANNER_RESET = 0x1F6;                      // 502
    @Deprecated
    public static final int NCRDIO_SCAN_RESET = NCR_DIO_SCANNER_RESET;
    public static final int NCR_DIO_SCANNER_STATUS = 0x1F7;                     // 503
    @Deprecated
    public static final int NCRDIO_SCAN_STATUS = NCR_DIO_SCANNER_STATUS;
    public static final int NCR_DIO_SCANNER_DIRECT = 0x1FB;                     // 507
    @Deprecated
    public static final int NCRDIO_SCAN_DIRECT = NCR_DIO_SCANNER_DIRECT;
    public static final int NCR_DIO_SCANNER_NOT_ON_FILE = 0x01FC;               // 508
    @Deprecated
    public static final int DIO_NCR_SCANNER_NOF = NCR_DIO_SCANNER_NOT_ON_FILE;

    // NCR Scale
    public static final int NCR_DIO_SCALE_STATUS = 0x259;                       // 601
    @Deprecated
    public static final int NCRDIO_SCAL_STATUS = NCR_DIO_SCALE_STATUS;
    public static final int NCR_DIO_SCALE_LIVE_WEIGHT = 0x25C;                  // 604
    @Deprecated
    public static final int NCR_DIO_SCAL_LIVE_WEIGHT = NCR_DIO_SCALE_LIVE_WEIGHT;
    public static final int NCR_DIO_SCALE_DIRECT = 0x25D;                       // 605
    @Deprecated
    public static final int NCRDIO_SCAL_DIRECT = NCR_DIO_SCALE_DIRECT;
}
NOTE: Where an opcode has an older name, it is shown in parentheses after the current one - for example, DIO_RSM_ATTR_SET (RSM_ATTR_SET). The parenthetical name is the deprecated alias shown above (marked @Deprecated); it still works, but new code should use the primary name.

DIO_GET_SCANNERS (GET_SCANNERS)

This command must be used first when setting up DirectIO. It updates the OutXml parameter with information for available scanners, and returns ScannerIDs used in all other DirectIO calls.

InOutXml: This contains the raw XML string of all of the connected scanners in the format:


<scanners>
    <scanner type="mode">
        <scannerID>id1</scannerID>
        <serialnumber>serial_number</serialnumber>
        <GUID>S_N:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</GUID>
        <VID>vendor_id</VID>
        <PID>product_id</PID>
        <modelnumber>model_number</modelnumber>
        <DoM>date_of_manufacture</DoM>
        <firmware>firmare_revision</firmware>
    </scanner>
    <scanner type="mode">
        <scannerID>id2</scannerID>
        <serialnumber>serial_number</serialnumber>
        <GUID>S_N:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</GUID>
        <VID>vendor_id</VID>
        <PID>product_id</PID>
        <modelnumber>model_number</modelnumber>
        <DoM>date_of_manufacture</DoM>
        <firmware>firmare_revision</firmware>
    </scanner>
    ....
    ....
    <scanner type="mode">
        <scannerID>idN</scannerID>
        <serialnumber>serial_number</serialnumber>
        <GUID>S_N:XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</GUID>
        <VID>vendor_id</VID>
        <PID>product_id</PID>
        <modelnumber>model_number</modelnumber>
        <DoM>date_of_manufacture</DoM>
        <firmware>firmware_revision</firmware>
    </scanner>
</scanners>

DIO_RSM_ATTR_GETALL (RSM_ATTR_GETALL)

This command returns a list in XML format via the object argument, defined above, of all possible attributes that can be set. This list and what it contains is dependent on the scanning device. The scanner specific Product Reference Guide contains the definitions of all of these attributes. The XML string returned in the obj argument has the following format:

InOutXml: This contains the raw XML string of all the supported RSM attributes:


<?xml version="1.0" encoding="UTF-8"?>
<outArgs>
    <scannerID>1</scannerID>
    <arg-xml>
        <modelnumber>DS4801-XXXXXXXXXXX</modelnumber>
        <serialnumber>S/N:B1353E3FBA73C94DB3449420F6F3B3FD</serialnumber>
        <GUID>B1353E3FBA73C94DB3449420F6F3B3FD</GUID>
        <response>
            <opcode>5000</opcode>
            <attrib_list>
                <attribute name="">0</attribute>
                <attribute name="">1</attribute>
                <attribute name="">2</attribute>
                <attribute name="">3</attribute>
                <attribute name="">4</attribute>
                ....
                ....
                <attribute name="">25011</attribute>
                <attribute name="">25012</attribute>
            </attrib_list>
        </response>
    </arg-xml>
</outArgs>

The value of each attribute in the returned XML list can be accessed using the DIO_RSM_ATTR_GET (RSM_ATTR_GET) command.

NOTE: Calling this is not necessary if the attributes you wish to SET, or GET are known ahead of time.

DIO_RSM_ATTR_GET (RSM_ATTR_GET)

This command can be used to retrieve scanner attribute information including value, data type, and permission. For more information, refer to the Zebra Scanner SDK for Windows Developer's Guide.

InOutXml: For this command InOutXml argument is used to provide input and retrieve the output of the command.

InXML:


<inArgs>
    <scannerID>scannerID</scannerID>
    <!-- ScannerID of one of the scanners which could be retrieved by executing DIO_GET_SCANNERS (GET_SCANNERS) Direct IO command -->
    <cmdArgs>
        <arg-xml>
            <attrib_list> attribute1[,attribute2…attributeN]</attrib_list>
            <!-- A comma separated list of scanner attribute numbers -->
        </arg-xml>
    </cmdArgs>
</inArgs>

OutXML:


<outArgs>
    <scannerID>1</scannerID>
    <arg-xml>
        <modelnumber>DS4801-XXXXXXXXXXX</modelnumber>
        <serialnumber>S/N:B1353E3FBA73C94DB3449420F6F3B3FD</serialnumber>
        <GUID>B1353E3FBA73C94DB3449420F6F3B3FD</GUID>
        <response>
            <opcode>5001</opcode>
            <attrib_list>
                <attribute>
                    <id> attribute1</id>
                    <name></name>
                    <datatype>F</datatype>
                    <permission>RWP</permission>
                    <value>True</value>
                </attribute>
                ....
                ....
                <attribute>
                    <id> attributeN</id>
                    <name></name>
                    <datatype>F</datatype>
                    <permission>RWP</permission>
                    <value>True</value>
                </attribute>
            </attrib_list>
        </response>
    </arg-xml>
</outArgs>

DIO_RSM_ATTR_GETNEXT (RSM_ATTR_GETNEXT)

This will retrieve the value of the next available attribute of the given attribute number.

InOutXml: For this command InOutXml argument is used to provide input and retrieve the output of the command.

InXML:


<inArgs>
    <scannerID>1</scannerID>
    <cmdArgs>
        <arg-xml>
            <attrib_list>1</attrib_list>
        </arg-xml>
    </cmdArgs>
</inArgs>

OutXML:


<?xml version="1.0" encoding="UTF-8"?>
<outArgs>
    <scannerID>1</scannerID>
    <arg-xml>
        <modelnumber>MP7001-LNS0C00AU</modelnumber>
        <serialnumber>22351010553559</serialnumber>
        <GUID>22351010553559</GUID>
        <configname>Modified</configname>
        <response>
            <opcode>5002</opcode>
            <attrib_list>
                <attribute>
                    <id>2</id>
                    <name></name>
                    <datatype>F</datatype>
                    <permission>RWP</permission>
                    <value>True</value>
                </attribute>
            </attrib_list>
        </response>
    </arg-xml>
</outArgs>

DIO_RSM_ATTR_SET (RSM_ATTR_SET) / DIO_RSM_ATTR_STORE (RSM_ATTR_STORE)

Sets (volatile, cleared after device reboot) or stores (non-volatile, retained after device reboot) attributes respectively, specified in the XML string given in the obj argument. The XML string takes the following format.

InOutXml: For this command using InOutXml argument we could provide the information for the attribute to set in XML format

NOTE: The tabbed formatting is for brevity only, and the actual XML string has no end-line or carriage-return characters required.


<inArgs>
    <scannerID>1</scannerID>
    <cmdArgs>
        <arg-xml>
            <attrib_list>
                <attribute>
                    <id>rsm_attribute_number</id>
                    <!-- 7 -->
                    <datatype>valid_datatype</datatype>
                    <!-- F -->
                    <value>value_matching_datatype</value>
                    <!-- True -->
                </attribute>
            </attrib_list>
        </arg-xml>
    </cmdArgs>
</inArgs>

The following are the valid values:

  • rsm_attribute_number: One of the scanners accepted, writeable attributes numbers.
  • valid_datatype: A valid datatype character: F, B, W, D, A, S
  • value_matching_datatype: A value that is consistent with the datatype and the datatypes range. For example, 'F' is a 'Boolean' value that may be either 'false' or 'true'. A 'B' datatype is 'Byte' which ranges from 0-255.

For example, to disable UPC Code 128, the actual XML string passed into the obj argument would look this:


<inArgs>
    <scannerID>1</scannerID>
    <cmdArgs>
        <arg-xml>
            <attrib_list>
                <attribute>
                    <id>7</id>
                    <datatype>F</datatype>
                    <value>False</value>
                </attribute>
            </attrib_list>
        </arg-xml>
    </cmdArgs>
</inArgs>

DIO_SCANNER_LOAD_CONFIG (CMD_LOAD_CONFIGURATION)

This command can be used to update the scanner configuration by specifying the relevant scannerID and the absolute file path, including the filename, created using 123Scan (.scncfg).

InXML:


<inArgs> 
    <scannerID>1</scannerID> 
    <cmdArgs> 
        <arg-string>C:\DS8108 Config.scncfg</arg-string> 
    </cmdArgs> 
</inArgs>

OutXML: None. Instead of OutXml, DirectIO events with the following event types will be received.

  • CONFIG_LOAD_START = 17
  • CONFIG_LOAD_PROGRESS = 18
  • CONFIG_LOAD_END = 19

Possible error scenarios are outlined below.

Failure Error Code
File does not exist ERROR_INLVAID_CONFIG_FILE (601)
Incorrect extension ERROR_INLVAID_CONFIG_FILE (601)
Self-hash failure ERROR_INLVAID_CONFIG_FILE (601)
Incompatible device ERROR_INCOMPATIBLE_CONFIG_FILE (602)
XML syntax validation failure ERROR_CONFIG_FILE_SYNTAX_VALIDATION_FAILED (603)

DIO_SCANNER_UPDATE_FW_PLUGIN (CMD_DEVICE_UPDATE_FIRMWARE_FROM_PLUGIN) / DIO_SCANNER_UPDATE_FW_DAT (CMD_DEVICE_UPDATE_FIRMWARE_DAT)

This command can be used to update the scanner firmware by specifying the relevant scannerID and the absolute path of the firmware file (PLUGIN or DAT), including the filename.

InXML:


<inArgs> 
    <scannerID>1</scannerID> 
    <cmdArgs> 
        <arg-string>C:\DS3678-STANDARD.SCNPLG</arg-string> 
    <arg-int>2</arg-int> 
    </cmdArgs> 
</inArgs>

OutXML: None. Instead of OutXml, DirectIO events with the following event types will be received.

  • SCANNER_UF_SESS_START = 11
  • SCANNER_UF_DL_START = 12
  • SCANNER_UF_DL_PROGRESS= 13
  • SCANNER_UF_DL_END= 14
  • SCANNER_UF_SESS_END= 15
  • SCANNER_UF_STATUS= 16

Possible error scenarios are outlined below.

Failure Error Code
ERROR_FW_INVALID_DATFILE Invalid firmware file (500)
ERROR_FW_UPDATE_FAILED_IN_SCN FW Update failed in scanner (501)
ERROR_FW_READ_FAILED_DATFILE Failed to read DAT file (502)
ERROR_FW_UPDATE_INPROGRESS Firmware Update is in progress (cannot proceed another FW Update or another command) (503)
ERROR_FW_UPDATE_ALREADY_ABORTED Firmware update is already aborted (504)
ERROR_FW_UPDATE_ABORTE FW Update aborted (505)
ERROR_FW_SCN_DETTACHED Scanner is disconnected while updating firmware (506)
ERROR_FW_UPDATE_NOT_SUPPORTED Device doesn't support firmware update (507)
STATUS_FW_SWCOMP_RESIDENT The software component is already resident in the scanner (600)

NCR_DIO_SCANNER_TONE (DIO_NCR_SCAN_TONE)

This command is used to execute the NCR tone pattern configured in the JPOS.xml. Tone pattern can be set for any logical device by setting the following configuration.


<prop name="NcrScanTonePattern" type="String" value="<TonePatternID>"/>

InOutXml: No need of providing an InOutXml argument.

NCR_DIO_SCANNER_NOT_ON_FILE (DIO_NCR_SCANNER_NOF)

This command is used to execute the NCR “Not on File” tone pattern configured in the JPOS.xml. Tone pattern can be set for any logical device by setting the following configuration.


<prop name="NcrScanNOFPattern" type="String" value="<TonePatternID>"/>

InOutXml: No need of providing an InOutXml argument.

NCR_DIO_SCANNER_RESET (NCRDIO_SCAN_RESET)

This command is used to reset the device. Executing this command is not doing any change to the device now. Once executed it always returns success.

InOutXml: No need of providing an InOutXml argument.

NCR_DIO_SCANNER_STATUS (NCRDIO_SCAN_STATUS)

This command is used to get the IBM USB status bytes of the scanner. Status bytes are given as a string.

InOutXml: No need of providing an InOutXml argument.

NCR_DIO_SCANNER_DIRECT (NCRDIO_SCAN_DIRECT)

This command is used to execute direct IO commands GetAll, Get, GetNext, Set and Store attributes directly without the corresponding direct IO commands for these operations. Direct IO OpCode for these operations are passed as an attribute in the InXml.

InOutXml: This contains the raw XML string of direct access in xml with the opcode tag.


<inArgs>
    <scannerID>1</scannerID>
    <opcode>5000</opcode>
    <cmdArgs>
        <arg-xml>
            <attrib_list>
                <attribute>
                    <id>6000</id>
                    <datatype>X</datatype>
                    <value>2</value>
                </attribute>
            </attrib_list>
        </arg-xml>
    </cmdArgs>
</inArgs>

NCR_DIO_SCALE_LIVE_WEIGHT (NCR_DIO_SCAL_LIVE_WEIGHT)

This command is used to get the live weight value of the scale.

InOutXml: No need of providing an InOutXml argument.

NCR_DIO_SCALE_STATUS (NCRDIO_SCAL_STATUS)

This command is used to get the IBM USB status bytes of the scale. Status bytes are given as a string.

InOutXml: No need of providing an InOutXml argument.

NCR_DIO_SCALE_DIRECT (NCRDIO_SCAL_DIRECT)

This command is used to execute direct IO commands GetAll, Get, GetNext, Set and Store attributes directly without the corresponding direct IO commands for these operations. Direct IO OpCode for these operations are passed as an attribute in the InXml.

InOutXml: This contains the raw XML string of direct access in xml with the opcode tag.


<inArgs>
    <scannerID>1</scannerID>
    <opcode>5000</opcode>
    <cmdArgs>
        <arg-xml>
            <attrib_list>
                <attribute>
                    <id>6000</id>
                    <datatype>X</datatype>
                    <value>2</value>
                </attribute>
            </attrib_list>
        </arg-xml>
    </cmdArgs>
</inArgs>

Real Time Alerts (RTA)

Real Time Alerts (RTA) are preselected events that are monitored by a scanner device. When a selected statistic has reached a specified value or when a selected event occurs, it is then reported by the scanner device to the host as an alert.

For more information, see Real Time Alerts (RTA) User Guide

The JPOS driver uses DirectIO commands to invoke Real-Time Alerts (RTA) methods on the scanner or cradle device and utilizes DirectIO events to receive notifications when an RTA event is triggered by the scanner. Because the Zebra JPOS Service Object automatically registers for CoreScanner notification events during the initial Open call, the host application does not need to perform manual registration to receive RTA events.

DIO_RTA_GET_SUPPORTED (OPCODE - 5500)

Gets RTA events supported by the device.

InXML:


<inArgs>
    <scannerID>1</scannerID>
</inArgs>

OutXML:

Supported RTA events (ID and Stat type) along with on-limit and off-limit.

NOTE: On-limit/ Off-limit with "Not set" requires the value to be set when registering, and "Not applicable" doesn't require a value to be set.


<?xml version="1.0" encoding="UTF-8"?>
<outArgs>
    <scannerID>1</scannerID>
    <arg-xml>
        <modelnumber>CR8178-PCM00FBWW</modelnumber>
        <serialnumber>23117010558099</serialnumber>
        <GUID>B2887932D8F09D40880BFAE7AD61A8BA</GUID>
        <configname>Modified</configname>
        <response>
            <opcode>5500</opcode>
            <rtaevent_list>
                <rtaevent>
                    <id>38004</id>
                    <stat>7</stat>
                    <onlimit>Not set</onlimit>
                    <offlimit>Not applicable</offlimit>
                </rtaevent>
                <rtaevent>
                    <id>38001</id>
                    <stat>7</stat>
                    <onlimit>Not set</onlimit>
                    <offlimit>Not applicable</offlimit>
                </rtaevent>
                <rtaevent>
                    <id>38003</id>
                    <stat>13</stat>
                    <onlimit>Not applicable</onlimit>
                    <offlimit>Not applicable</offlimit>
                </rtaevent>
                <rtaevent>
                    <id>616</id>
                    <stat>2</stat>
                    <onlimit>Not applicable</onlimit>
                    <offlimit>Not applicable</offlimit>
                </rtaevent>
            </rtaevent_list>
        </response>
    </arg-xml>
</outArgs>

DIO_RTA_UNREGISTER (OPCODE - 5502)

Unregister for selected RTA events using RTA event ID and type.

InXML:


<inArgs>
    <scannerID>1</scannerID>
    <cmdArgs>
        <arg-xml>
            <rtaevent_list>
                <rtaevent>
                    <id>38004</id>
                    <stat>7</stat>
                </rtaevent>
                <rtaevent>
                    <id>38001</id>
                    <stat>7</stat>
                </rtaevent>
            </rtaevent_list>
        </arg-xml>
    </cmdArgs>
</inArgs>

OutXML:

Null

DIO_RTA_GET_EVENT_STATUS (OPCODE - 5503)

Retrieve the RTA event's alert status. The RTA alert status contains information on the following four statuses:

  • Registered: Whether the event is registered or not.
  • Reported: An alert associated with the event has been reported.
  • Measuring: Device has started measurement of the event.
  • Initialized: Device has initialized the event.

InXML:


<inArgs>
    <scannerID>1</scannerID>
</inArgs>

OutXML:


<outArgs>
    <scannerID>1</scannerID>
    <arg-xml>
        <modelnumber>CR8178-PC100F4WW  </modelnumber>
        <serialnumber>17034010506402  </serialnumber>
        <GUID>8835E76BE40A6C49B458BEEA0065F60E</GUID>
        <configname>Factory Default </configname>
        <response>
            <opcode>5503</opcode>
            <suspend>FALSE</suspend>
            <rtaevent_list>
                <rtaevent>
                    <id>38004</id>
                    <stat>7</stat>
                    <scope>0</scope>
                    <registered>TRUE</registered>
                    <reported>FALSE</reported>
                    <initialized>TRUE</initialized>
                    <measuring>FALSE</measuring>
                </rtaevent>
                <rtaevent>
                    <id>38001</id>
                    <stat>7</stat>
                    <scope>0</scope>
                    <registered>TRUE</registered>
                    <reported>TRUE</reported>
                    <initialized>TRUE</initialized>
                    <measuring>TRUE</measuring>
                </rtaevent>
            </rtaevent_list>
        </response>
    </arg-xml>
</outArgs>

DIO_RTA_SET_EVENT_STATUS (OPCODE - 5504)

Set RTA event's reported state.

NOTE: Only the <reported> alert status can be modified, and it can only be transitioned from true (1) to false (0). If set to any other value, the system will automatically overwrite it with 0.

InXML:


<inArgs>
    <scannerID>1</scannerID>
    <cmdArgs>
        <arg-xml>
            <rtaevent_list>
                <rtaevent>
                    <id>38004</id>
                    <stat>7</stat>
                    <reported>0</reported>
                </rtaevent>
                <rtaevent>
                    <id>616</id>
                    <stat>2</stat>
                    <reported>0</reported>
                </rtaevent>
            </rtaevent_list>
        </arg-xml>
    </cmdArgs>
</inArgs>

OutXML:

Null

DIO_RTA_SUSPEND (OPCODE - 5505)

Toggle RTA alert notification reporting to the host.

InXML:


<inArgs>
    <scannerID>1</scannerID>
    <cmdArgs>
        <arg-bool>false</arg-bool> <!--"true" will enable RTA to suspend, "false" will disable RTA suspend -->
    </cmdArgs>
</inArgs>

OutXML:

Null

DIO_RTA_GETSTATE (OPCODE - 5506)

Retrieve the current operational state of RTAs. State will have 4 values as follows.

State Name Value Description
Wait For Register 1 There are currently no alerts registered by the User.
Wait for Context 2 The scanner has not yet been assigned a Context Address for reporting.
Online 3 The Real Time Alerts feature is fully operational.
Suspend 0 The Real Time Alerts were suspended automatically or by the RTA_Suspend command.

InXML:


<inArgs>
    <scannerID>1</scannerID>
</inArgs>

OutXML:


<outArgs>
    <scannerID>1</scannerID>
    <arg-xml>
        <modelnumber>CR8178-PC100F4WW  </modelnumber>
        <serialnumber>17034010506402  </serialnumber>
        <GUID>8835E76BE40A6C49B458BEEA0065F60E</GUID>
        <configname>Factory Default </configname>
        <response>
            <opcode>5506</opcode>
            <state>0</state>
        </response>
    </arg-xml>
</outArgs>

DirectIO Status


public class DirectIOStatus {
    public static final int STATUS_SUCCESS = 0;
}

Currently only STATUS_SUCCESS is defined. Any other value should be indicated as an error. The DirectIO method itself is an exception based method (see The DirectIO Method for more information). As a result, use a try-catch statement when calling it. The JposException class contains most of the error information.

The DirectIO Methods

The Zebra JPOS driver allows direct RSM attribute GET/SET access in order to leverage features not otherwise able to be exposed through the JPOS API Specification.

The JPOS DirectIO method has the following prototype (as of Zebra JPOS driver 1.0):


directIO ( command: int32, inout data: int32, inout obj: object ): void { raises-exception }

DirectIO Method Arguments

For the purposes of the Zebra scanner device class, the DirectIO method arguments are defined as:

command: int32: The command is passed to the CoreScanner service which is responsible for communicating with the scanner. This command is defined in the JposService.jar.

inout data: int32: For Zebra devices, this is used to return the status of the executed op-code.

inout obj: object: This is an object type. In Zebra JPOS Direct IO implementation, Java StringBuffer type is used to provide input and get output of the argument in XML format. See DirectIO Command.

Using the JPOS Sample Application to Send Direct I/O Commands

DirectIO operations can be done using the panel highlighted in red, as shown in the screenshot given below. The required DirectIO command can be selected from the drop-down list named as the Command. Upon selecting, the InXML relevant to the chosen command will be displayed on the left side of the panel.

Figure 1: JPOS Sample Application - Direct IO Commands

The OutXML: corresponding to the selected DirectIO command can be retrieved by clicking on the Execute button.

Figure 2: JPOS Sample Application - Direct IO Commands Output

To send Direct I/O commands using the JPOS sample application:

  1. Connect a Zebra scanner and switch to a management enabled host mode such as IBM OPOS, IBM Hand-held, IBM Table-top, or SNAPI.
  2. Open the JPOS sample application and select the Scanner tab.
  3. Enter ZebraAllScanners as the logical name and click Open.
  4. Click Claim.

To retrieve a list of all the scanners connected to the PC:

  • Select DIO_GET_SCANNERS (GET_SCANNERS) as DIO Op-Code from the Direct I/O section.
  • Click Execute. The Direct I/O OutXml text box populates with XML with all the attached scanners.

To retrieve all attributes available in the scanner:

  1. Select DIO_RSM_ATTR_GETALL (RSM_ATTR_GETALL) as DIO Op-Code from Direct I/O section.
  2. In the Direct I/O InXml text box, change the value of the ScannerID XML element to the scannerID from which you want to retrieve attributes. Use the DIO_GET_SCANNERS (GET_SCANNERS) command to find available ScannerIDs.
  3. Click Execute. The Direct I/O OutXml text box populates with XML with attribute numbers of all supported attributes.

To retrieve more information for an attribute:

  1. Select DIO_RSM_ATTR_GET (RSM_ATTR_GET) as DIO Op-Code from the Direct I/O section.
  2. In the Direct I/O InXml text box, change the value of the ScannerID XML element to the required scanner ID, and enter a comma-separated list of attribute numbers as the value of attrib_list.
  3. Click Execute. The Direct I/O OutXml text box populates with XML containing a list of attributes with values and other attribute related details.

To temporarily set or permanently store the value of an attribute:

  1. Select DIO_RSM_ATTR_SET (RSM_ATTR_SET) or DIO_RSM_ATTR_STORE (RSM_ATTR_STORE) as DIO Op-Code from the Direct I/O section.
  2. In the Direct I/O InXml text box, change the value of the ScannerID XML element to the required scanner ID and change the values of data_type and the value XML elements accordingly as obtained by executing the command DIO_RSM_ATTR_GET (RSM_ATTR_GET).
  3. Click Execute. For these Direct I/O op-codes, an OutXml does not populate.

Upon executing each Op-Code, the CoreScanner Status field populates with the status of the underlying CoreScanner driver. Any value other than 0 indicates an error.

Using DirectIO

Following is an example of how to use DirectIO when attached to a single device, assuming a returned scanner/scale ID of '1'.

NOTE: The following code demonstrates how to use DirectIO with scanner JPOS control. The same pattern is applicable to scale JPOS control by declaring and instantiating JPOS scale class, and scale object instead of scanner class in the code.


package dio;

import jpos.*;
import com.zebra.jpos.service.directio.DirectIOCommand; 
import com.zebra.jpos.service.directio.DirectIOStatus; 
import java.io.ByteArrayInputStream;
import java.io.IOException; 
import java.util.logging.Level; 
import java.util.logging.Logger;
import javax.xml.parsers.DocumentBuilderFactory; 
import javax.xml.parsers.DocumentBuilder;
import javax.xml.parsers.ParserConfigurationException; 
import org.w3c.dom.Document;
import org.xml.sax.SAXException;

/**
*
* @author Zebra Technologies
*/
public class DirectIODemo {
    // As defined in JPOS v1.13

    public static Scanner scannerObj = new Scanner();
    // Interfacing with a single scanner connection 
    static int scannerID;

    // main function
    public static void main(String[] args) {
        // Open scanner API, claim, enable and perform get scanners 
        try {
            // open with 'ZebraAllScanners' as logical device name 
            scannerObj.open("ZebraAllScanners");
            
            // standard claim with 5000ms timeout 
            scannerObj.claim(5000); 
            
            // enable device
            scannerObj.setDeviceEnabled(true);

            // object to store DirectIO data
            StringBuffer deviceParams = new StringBuffer();

            // get scanners - this acquires the scanner ID needed to perform directIO on a specific device
            int opCode = DirectIOCommand.DIO_GET_SCANNERS; int[] csStatus = new int[1];
            // OR int opCode = DirectIOCommand.GET_SCANNERS; int[] csStatus = new int[1];

            scannerObj.directIO(opCode, csStatus, (Object) deviceParams); 
            if (csStatus[0] != DirectIOStatus.STATUS_SUCCESS) {
                    System.out.println("Error connecting to device"); return;
            }

            // retrieve ID number of scanner for this example, we assume at least 1 scanner is found
            DocumentBuilderFactory dbFactory = DocumentBuilderFactory.newInstance(); 
            DocumentBuilder dBuilder;
            try {
                dBuilder = dbFactory.newDocumentBuilder();
                Document doc;
                ByteArrayInputStream inIs = new ByteArrayInputStream(deviceParams.toString().getBytes());
                doc = dBuilder.parse(inIs);

                int scannerCount = doc.getElementsByTagName("scannerID").getLength();
                if (scannerCount <= 0) {
                    System.out.println("No scanner found attatched"); return;
                }

                for (int n = 0; n < scannerCount; n++) {
                    System.out.println("Scanner ID : " + doc.getElementsByTagName("scannerID").item(n).getTextContent());
                }

                System.out.println("Selected scanner ID : " + doc.getElementsByTagName("scannerID").item(0).getTextContent()); 
                scannerID = Integer.parseInt(doc.getElementsByTagName("scannerID").item(0). getTextContent());
            } 
            catch (SAXException ex) { 
                Logger.getLogger(DirectIODemo.class.getName()).log(Level.SEVERE, null, ex);
            } 
            catch (IOException ex) { 
                Logger.getLogger(DirectIODemo.class.getName()).log(Level.SEVERE, null, ex);
            } 
            catch (ParserConfigurationException ex) { 
                Logger.getLogger(DirectIODemo.class.getName()).log(Level.SEVERE, null, ex);
            }

            // retrieve model number of device

            // Setup DirectIO to do a GET Attribute setup DirectIO XML string
            String sGetAttribInXML = "<inArgs>\n"
                                    + " <scannerID>" + scannerID + "</scannerID>\n"
                                    + " <cmdArgs>\n"
                                    + " <arg-xml>\n"
                                    + " <attrib_list>535</attrib_list>\n"
                                    + " </arg-xml>\n"
                                    + " </cmdArgs>\n"
                                    + "</inArgs>";

            // create new DirectIO data structure see DirectIO data definition for more information 
            StringBuffer oGETparams = new StringBuffer();

            // copy XML string into DirectIO inXML member 
            oGETparams.append(sGetAttribInXML);

            // set opcode for Atrribute GET
            opCode = DirectIOCommand.DIO_RSM_ATTR_GET;
            // OR opCode = DirectIOCommand.RSM_ATTR_GET;

            // set scanner ID
            int[] csSataus = new int[1];

            // make directIO call to JPOS driver 
            scannerObj.directIO(opCode, csSataus, (Object) oGETparams);

            // check status from DirectIO status member
            if (csSataus[0] != DirectIOStatus.STATUS_SUCCESS) { 
                System.out.println("Error performing DirectIO"); return;
            }

            // output XML string returned. Not that the actual model number will be contained within the <value> XML tag.
            System.out.println("XML string returned: " + oGETparams.toString());

            // disable UPC-A barcode on scanner

            // Setup DirectIO to do a SET Attribute 
            String sSetAttribInXML = "<inArgs>\n"
                                    + " <scannerID>" + scannerID + "</scannerID>\n"
                                    + " <cmdArgs>\n"
                                    + " <arg-xml>\n"
                                    + " <attrib_list>\n"
                                    + " <attribute>\n"
                                    + " <id>6000</id>\n"
                                    + " <datatype>X</datatype>\n"
                                    + " <value>2</value>\n"
                                    + " </attribute>\n"
                                    + " </attrib_list>\n"
                                    + " </arg-xml>\n"
                                    + " </cmdArgs>\n"
                                    + "</inArgs>";

            // create new DirectIO data structure
            // see DirectIO data definition for more information 
            StringBuffer oSETparams = new StringBuffer();

            // copy XML string into DirectIO inXML member 
            oSETparams.append(sSetAttribInXML);

            // set opcode for Atrribute SET
            opCode = DirectIOCommand.DIO_RSM_ATTR_SET;
            // OR opCode = DirectIOCommand.RSM_ATTR_SET;

            // set scanner ID
            csSataus[0] = scannerID;

            // make directIO call to JPOS driver 
            scannerObj.directIO(opCode, csSataus, (Object) oSETparams);

            // check status from DirectIO status member
            if (csSataus[0] != DirectIOStatus.STATUS_SUCCESS) { 
                System.out.println("Error performing DirectIO");
            }
        } 
        catch (JposException ex) { 
            System.out.println("Exception: " + ex.getMessage());
        }
    }
}