EPSON OPOS ADK MANUAL

APPLICATION DEVELOPMENT GUIDE HardTotals (SR-610/ IM-700)

Version 2.61 Feb. 2008

Notes (1) Reproduction of any part of this documentation by any means is prohibited. (2) The contents of this documentation are subject to change without notice. (3) Comments and notification of any mistakes in this documentation are gratefully accepted. (4) This software cannot be used with other equipment that the specified. (5) EPSON will not be responsible for any consequences resulting from the use of any information in this documentation. Trademarks Microsoft, Windows, Windows Vista, Visual Basic and Visual C++ are trademarks or registered trademarks of Microsoft Corporation in the United States and/or other countries. EPSON and ESC/POS are registered trademarks of SEIKO EPSON CORPORATION. Other product and company names used herein are for identification purposes only and may be trademarks or registered trademarks of their respective companies. Copyright 2000-2008 SEIKO EPSON CORPORATION

Version 2.61

Feb. 2008

Contents

Section 1. Introduction....1
Section 2. Details on Settings...2
2.1 Device Information....2 2.2 Setting of Devices....2
Section 3. Function Details....4
3.1 Check Health Method....4 3.2 Property Set Values and Default Values...4 3.3 Supplementary Explanation of Functions...5 3.4 Device Statistics....5
Section 4. Expanded Functions...6
4.1 DirectIO Function....6
Section 5. Device Specific Programming...9
5.1 Backup of Write Data...9
Section 6. Error Information....10
6.1 ResultCode List...10 6.2 Remedial Actions for Principal Errors...13
Section 7. Warnings....14

Section 1. Introduction

This manual describes the method of use and related items, including device-specific precautions, when HardTotals are used with EPSON OPOS ADK. Before the HardTotals can be used, the EPSON OPOS ADK should be installed and the devices to be used should be set using the SetupPOS utility. For setting methods, see the Section 2 of this manual. This manual applies to the following devices. Device List IM-700 Compact Flash SR-610 Compact Flash The operation of HardTotals is not supported in Windows Vista environment.
Section 2. Details on Settings
This section describes connection configurations and how to make the settings for the HardTotals.

2.1 Device Information

The DeviceDescription and DeviceName for each model are as follows.
Model Name EPSON IM-700 Compact Flash EPSON SR-610 Compact Flash
DeviceDescription EPSON IM-700 Compact Flash HardTotals EPSON SR-610 Compact Flash HardTotals
DeviceName IM-700 Compact Flash SR-610 Compact Flash

2.2 Setting of Devices

The SetupPOS utility should be used for setting devices. Regarding how to use the SetupPOS utility, refer to the "EPSON OPOS ADK MANUAL User's Manual (Installer/ SetupPOS/ TMUSB)". 1) Setting CompactFlash Devices When multiple CompactFlash drives are to be used as HardTotals, it is necessary to perform the Add device Device specific settings settings the number of times that corresponds with the number of drives. 2) Device specific Settings When using a CompactFlash device, it is necessary to specify the drive to which the particular CompactFlash device is allocated. Open My Computer to check which drive CompactFlash is allocated to. It is then necessary to specify the CompactFlash drive in Device inherent settings. 3) Precautions when Using CompactFlash Operation is not guaranteed for other drives than the one CompactFlash is allocated to. The default drive is set to D, so be sure to confirm the CompactFlash drive
and use the SetupPOS utility to correct the setting if necessary. After making DeviceEnabled=TRUE, the \EPSONHARDTOTALS directory is created in the specified drive. Data is stored in this directory. This directory cannot be removed even if the OPOS is uninstalled. The CompactFlash device can be referenced like a normal physical drive. It is possible to reference it even while EPSON OPOS ADK is in use, but the operation is not guaranteed if files are deleted or copied manually using Explorer, etc.

Section 3. Function Details
This section describes the functions of the HardTotals in details. Supplementary explanation of the parts not described in detail in "OLE for Retail POS Application Programmer's Guide" is also given here.

3.1 Check Health Method

3.1.1 Internal Test Not supported 3.1.2 External Test Not supported 3.1.3 Interactive Test Performs a test of writing and reading of character strings. The input character strings is written to the registered device, and the result read from the device is displayed.
3.2 Property Set Values and Default Values
3.2.1 Capability Set Value Capability name CapErrorDetection CapSingleFile CapTransactions CapPowerReporting Set Value False False False OPOS_PR_NONE
3.2.2 Property Default Set Values and Setting Ranges Free capacity (FreeData) The free capacity available for the Total devices currently in use. This is also the maximum size when a file is created. This cannot be set. Setting range <= TotalsSize Capacity of devices (TotalsSize) The capacity of the Total devices currently in use. This cannot be set. Number of files (NumberOfFiles) The total number of files in the total devices currently in use. This number is increased or decreased by the Create method or Delete method. This cannot be set.
3.3 Supplementary Explanation of Functions
3.3.1 Control of Exclusive Access Rights Controls the exclusive access rights of the currently used Total devices. HardTotals supports the method (ClaimDevice, ReleaseDevice) for controlling the exclusive access rights of the entire Total devices, and the methods (ClaimFile, ReleaseFile) for controlling the exclusive access rights in file units. For details on each method, refer to the "OLE for Retail POS Application Programmer's Guide".

3.4 Device Statistics

The DeviceStatistics function is added in response to the compliance of the "UPOS 1.8". Please refer to the EPSON OPOS ADK MANUAL APPLICATION GUIDE Device Statistics for the details of the Device Statistics.
Section 4. Expanded Functions
This section describes the expanded functions of the HardTotals device.

4.1 DirectIO Function

The usage of the DirectIO method and DirectIOEvent event is described below. 4.1.1 DirectIO Method Syntax DirectIO Parameter Command pData pString Remarks Command As Long, pData As Long, pString As String Explanation Command number Sets the specific command to ON/OFF (0=OFF/ values other than 0 =ON) Not used The particular processing is performed in accordance with the command number. Command number =TOT_DI_BACKUP If a value other than 0 is entered for pData and the command is executed, since then, a backup file containing the write data is created in the local hard disk before actual writing to the Total device (file) is performed in the methods (Create, Delete, Write, SetAll, Rename) for writing to Total device. Creation of the backup file means that if system failure occurs during writing of data to Total device, the Total device can be restored next time the application is started up. Entering 0 for pData and executing cancels creation of a backup file. This setting changes the settings of all HardTotals opened as a Share.

Return

Either of the following values is returned, and placed in the ResultCode property.
Value OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_CLAIMED OPOS_E_ILLEGAL Others Prerequisites Open 4.1.2 DirectIOEvent Event Syntax
Meaning DirectIO was successful. Control is closed. Another object has issued ClaimDevice. The command is illegal or not supported. The exclusive access right cannot be achieved. See the ResultCode List.
DirectIOEvent EventNumber As Long, pData As Long, pString As String

Parameter EventNumber

Explanation Event number TOT_DIE_FORWARD: Condition after execution of method was restored. TOT_DIE_ROLLBACK: Condition before execution of method was restored. File number Not used.

pData pString

Remarks
When a backup file is created by the DirectIO methods backup function, the restored condition of the Total device (file) established by the backup file is communicated to the application if system failure occurs during writing to a Total device, and there is a risk that the Total device contents may have been corrupted. The file numbers should be read as follows. -1: Means that a failure has occurred during execution of the Create, Delete, Rename methods for restoration of file information. -2: Means that a failure has occurred during rebuilding of a device file using the DirectIO method for restoration of the entire device.
1-9: Means that a failure has occurred during execution of the Create, Write, and SetAll methods for restoration of the file data held in the corresponding file number. The file number corresponds to the order in which the file name was established when the FindByIndex method was use to obtain the file name.
Section 5. Device Specific Programming
This section describes the programming specific to the HardTotals device. The coding examples are real examples created in Microsoft Visual Basic.

5.1 Backup of Write Data

The DirectIO method can be used to specify whether a backup file should be created on the local hard disk when the method for writing to a Total device is executed. For details on the DirectIO method, see the Section 4 of this manual. When a backup file should be created: Dim RC As Long Dim Data As Long Dim Dummy As String Data = TRUE Specify FALSE when file should be not created
RC = OPOSTotals1.DirectIO (TOT_DI_BACKUP, Data, Dummy) If RC = OPOS_SUCCESS Then Start Backup Else Error End If
Section 6. Error Information
This section describes about the error information when executing properties of the methods of the HardTotals. The common properties and methods are informed in "EPSON OPOS ADK MANUAL APPLICATION DEVELOPMENT GUIDE GENERAL DEVELOPMENT". Refer to the guide for more information.

6.1 ResultCode List

The ResultCode and ResultCodeExtended codes when methods are executed are as follows.
Method Name ClaimFile ResultCode OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_ILLEGAL OPOS_EX_BADPARAM + 2 OPOS_ETOT_DELETE OPOS_E_TIMEOUT Create OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_CLAIMED OPOS_E_EXISTS OPOS_E_EXTENDED OPOS_E_ILLEGAL OPOS_ETOT_NOROOM 0 OPOS_ETOT_READFILE OPOS_ETOT_WRITEFILE OPOS_ETOT_INIT_DEVICE OPOS_E_FAILURE OPOS_EX_UNAUTHORIZED ResultCodeExtended Meaning Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Handle is illegal. Timeout period is illegal. Total file is not possible to delete. Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications File name is illegal. Error during reading from device. Error during writing to device. Device is not ready.

There was insufficient permission to access for processing.
Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Method under execution by same object.

Delete

OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_CLAIMED OPOS_E_NOEXIST OPOS_E_ILLEGAL OPOS_E_FAILURE
0 OPOS_ETOT_LOCKED OPOS_EX_UNAUTHORIZED

Method Name Find

ResultCode OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_CLAIMED OPOS_E_NOEXIST OPOS_E_ILLEGAL 0 0

ResultCodeExtended

Meaning Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Method under execution by same object. Error during reading from device.

FindByIndex

OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_CLAIMED OPOS_E_ILLEGAL
OPOS_ETOT_LOCKED OPOS_ETOT_READFILE OPOS_EX_BADPARAM+3 OPOS_EX_BADPARAM+4 ReleaseFile OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_ILLEGAL OPOS_EX_NOTCLAIMED Rename OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_CLAIMED OPOS_E_EXISTS OPOS_E_ILLEGAL OPOS_ETOT_LOCKED OPOS_ETOT_WRITEFILE OPOS_E_FAILURE OPOS_EX_UNAUTHORIZED
The 3th parameter is illegal. The 4th parameter is illegal.
Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Not claimed. Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications File name is illegal. Method under execution by same object. Error during writing to device.

Method Name SetAll

ResultCode OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_DISABLED OPOS_E_CLAIMED OPOS_E_ILLEGAL 0
Meaning Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Method under execution by same object. Error during reading from device. Error during writing to device.
OPOS_ETOT_LOCKED OPOS_ETOT_READFILE OPOS_ETOT_WRITEFILE OPOS_E_FAILURE OPOS_EX_UNAUTHORIZED
Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Write data does not comply with BinaryConversion. Refer to UPOS Specifications

0 OPOS_EX_BADPARAM + 2

OPOS_ETOT_LOCKED OPOS_ETOT_READFILE OPOS_ETOT_WRITEFILE OPOS_EX_BADPARAM+3 OPOS_EX_BADPARAM+4 OPOS_E_FAILURE OPOS_EX_UNAUTHORIZED
Method under execution by same object. Error during reading from device. Error during writing to device.
The 3th parameter is illegal. The 4th parameter is illegal. There was insufficient permission to access for processing.
Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications

ValidateData

OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_CLAIMED OPOS_E_DISABLED OPOS_E_ILLEGAL
RecalculateVali dationData

Method Name BeginTrans

ResultCode OPOS_SUCCESS OPOS_E_CLOSED OPOS_E_CLAIMED OPOS_E_DISABLED OPOS_E_ILLEGAL 0
Meaning Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications Refer to UPOS Specifications

CommitTrans

Rollback
6.2 Remedial Actions for Principal Errors
Timeout error occurs during claim for exclusive access rights. Likewise, none of the methods can be executed. There is a possibility that another application already has obtained exclusive access rights to the specified device (file). Wait until the exclusive access right is released, or close the particular application, and then execute again. When creating a file or changing the file name, OPOS_E_ILLEGAL is returned. This is occurs when the file name is improper. The file name may consist of up to 10 characters (10 bytes), and character codes smaller than 0x20 (space) cannot be used.

Section 7. Warnings

When using the DirectIO method to issue a command, be sure to read the instructions on the particular command in the product manual. Do not connect or disconnect a CompactFlash device while the power is ON. There is a risk that the system may be destroyed. Total file with file name is supported. However, the file name is restricted to 10 one-byte characters (5 two-byte characters). An advanced error detection function is not supported. The Transaction function is not supported. Consequently, the BeginTrans, CommitTrans, RecalculateValidationData, Rollback, and ValidateData methods are not supported. The FreeData property returns the actual file size that can be created with the Create method. During actual execution of a method, a method cannot be executed on the same object as a rule. The CheckHealth, DirectIO, Create, Delete, and Rename methods cannot be executed while a method is being executed on another object. During execution of a method (Read, Write, SetAll) for reading or writing to file, temporary exclusive access right to the file is obtained regardless of whether or not exclusive access right to the file has been obtained. During execution of CheckHealth and methods (DirectIO, Create, Delete, Rename) for rewriting device file information, temporary exclusive access right to the file is obtained regardless of whether or not exclusive access right to the file has been obtained.