Toshiba Global Commerce Solutions

Store Integrator User's Guide

Version 3 Release 5

G362-0561-05
Toshiba Global Commerce Solutions

Store Integrator User's Guide

Version 3 Release 5

G362-0561-05
 Note
Before using this information and the product it supports, be sure to read Safety Information–Read This First, Warranty
Information, Uninterruptible Power Supply Information, and the information under “Notices” on page 111.

June 2014
This edition applies to Version 3 Release 5 of the licensed program Toshiba Global Commerce Solutions Store
Integrator User's Guide (program number 5639-P71) and to all subsequent releases and modifications until
otherwise indicated in new editions.
If you send information to Toshiba Global Commerce Solutions you grant Toshiba Global Commerce Solutions a
nonexclusive right to use or distribute whatever information you supply in any way it believes appropriate without
incurring any obligation to you.
© Toshiba Global Commerce Solutions, Inc. 2013
© Copyright IBM Corporation 2004, 2010
Contents
Figures . . . . . . . . . . . . . . vii Return Codes. . . . . . . . . . . . . 23
New Warning messages in SI log files . . . . 23
Tables . . . . . . . . . . . . . . . ix New INFO messages in SI log files . . . . . 23
Messages during SiSecure operations . . . . . 23
Encrypting additional properties . . . . . . 24
Safety . . . . . . . . . . . . . . . xi
Chapter 4. Planning for Store Integrator 25
About this guide . . . . . . . . . . xiii Recommended SI configurations . . . . . . . 25
Who should read this guide . . . . . . . . xiii Understanding the throttling mechanism . . . . 27
Where to find more information . . . . . . . xiii
Chapter 5. Installing Store Integrator
Notice statements . . . . . . . . . . xv components . . . . . . . . . . . . 29
Installing SI on a 4690 operating system . . . . . 29
Summary of changes . . . . . . . . xvii Interactively installing Store Integrator on a 4690 29
June 2014 . . . . . . . . . . . . . . xvii Silently installing Store Integrator on a 4690 . . 30
February 2013 . . . . . . . . . . . . . xvii Remotely installing Store Integrator on a 4690 . . 30
October 2011 . . . . . . . . . . . . . xvii Interactive Common, AEF, and GUI Installation on
Windows . . . . . . . . . . . . . . . 31
Chapter 1. Overview . . . . . . . . . 1 Interactively installing Store Integrator on a
Application Extension Facility . . . . . . . . 2 Windows operating system . . . . . . . . 32
Store Integrator GUI . . . . . . . . . . . . 3 Silent Store Integrator installation on Windows 33
SI GUI Silver Theme . . . . . . . . . . . 4 Uninstalling on a Windows operating system . . . 33
POS Business Component . . . . . . . . . 11 Interactively uninstalling on Windows . . . . 33
POS Provider . . . . . . . . . . . . . . 12 Silently uninstalling on Windows . . . . . . 34
Installation-related problems. . . . . . . . . 34
Chapter 2. Requirements . . . . . . . 13 Error messages during installation . . . . . . 34
Hardware requirements . . . . . . . . . . 13 Microsoft Windows Program Compatibility
SI terminal and controller requirements . . . . 13 Assistant . . . . . . . . . . . . . . 35
Software requirements . . . . . . . . . . . 13 User data location . . . . . . . . . . . 35
4690 OS . . . . . . . . . . . . . . 14 Installation logs . . . . . . . . . . . . 35
Virtual file system setup . . . . . . . . . 14 Selecting terminal sales components . . . . . . 36
POS applications . . . . . . . . . . . 14 GSA . . . . . . . . . . . . . . . . 36
4610 POS printer . . . . . . . . . . . 15 SA . . . . . . . . . . . . . . . . 36
Java 2 . . . . . . . . . . . . . . . 15 ACE . . . . . . . . . . . . . . . . 38
Java 6 . . . . . . . . . . . . . . . 15 Other POS application . . . . . . . . . . 38
ICEbrowser . . . . . . . . . . . . . 15
Client software . . . . . . . . . . . . 16 Chapter 6. Configuring Store Integrator
Remote Management Agent requirements . . . 16 on 4690 OS . . . . . . . . . . . . . 39
Configuring stand-alone terminals . . . . . . . 39
Chapter 3. Understanding security . . . 17 Device characteristics . . . . . . . . . . 39
Secure Socket Layer . . . . . . . . . . . 17 Selecting load definitions . . . . . . . . . 41
SSL concepts . . . . . . . . . . . . . 18 Configuring user logical file names for terminals 42
Encrypting the userlogon.properties file (deprecated) 18 Using OS 4690 Advanced Java Configuration and
Encrypting sensitive data in Store Integrator Bundling Instead of .RSP files for the SI GUI
property files . . . . . . . . . . . . . . 19 application . . . . . . . . . . . . . 42
New procedure for encrypting the Using OS 4690 Advanced Java Configuration and
userlogon.properties file . . . . . . . . . . 19 Bundling for AEF-only . . . . . . . . . 46
Extracting the user.jar on the 4690 . . . . . . 19 Configuring the controller/terminal . . . . . . 49
Encrypting the userlogon.properties file . . . . 20 Response files for controller/terminals . . . . 49
Inserting updated file back into user.jar . . . . 20 System configuration . . . . . . . . . . . 50
Encrypting the ssl.properties. . . . . . . . . 21 System settings . . . . . . . . . . . . 50
Encrypting automation.properties . . . . . . . 22 Using the Java configuration. . . . . . . . 50
SISECURE.BAT details. . . . . . . . . . . 22 Configuring the controller . . . . . . . . . 51
Invocation . . . . . . . . . . . . . . 22 Configuring the video for graphics support on
the controller . . . . . . . . . . . . . 51

iii
 Configuring the DHCP server . . . . . . . 51 Configuring the controller for remote and virtual
Configuring background applications. . . . . 51 device support . . . . . . . . . . . . . 85
Defining user logical file names for controllers . 52 Adding a new group . . . . . . . . . . 86
Configuring RAM disks (optional). . . . . . 52 Adding a remote printer . . . . . . . . . 86
Configuring TCP/IP . . . . . . . . . . 52 Adding a remote scanner . . . . . . . . . 86
Configuring SSL . . . . . . . . . . . . 53 Adding a remote PIN pad . . . . . . . . 87
Configuring JavaPOS . . . . . . . . . . 53 Adding a remote MSR. . . . . . . . . . 87
Configuring Activate . . . . . . . . . . . 53 Adding a remote tone indicator . . . . . . 87
Java terminal offline configuration . . . . . . . 53 Adding a remote line display . . . . . . . 88
Configuring Logging . . . . . . . . . . . 54 Adding a remote cash drawer . . . . . . . 88
Migrating from SureVision or reinstalling the SI GUI 54 Adding a virtual scale . . . . . . . . . . 88
Migrating from previous SureVision systems . . 54 Deleting a device . . . . . . . . . . . 89
Migrating from SI V1 to SI V2 and above . . . 54 Saving your configuration . . . . . . . . 89
Migrating to SI V3 and above . . . . . . . 55 Starting the application . . . . . . . . . . 89
Migrating to SI V3R2 and above . . . . . . 56 Running the Remote GUI. . . . . . . . . 89
Migrating to SI V3R3 and above . . . . . . 56 Starting POSBC . . . . . . . . . . . . 89
Migrating to SI V3R4 and above . . . . . . 56
Migrating to SI V3R5 and above . . . . . . 57 Chapter 8. Problem determination . . . 91
Cancelling the installation . . . . . . . . . 58 Trace types . . . . . . . . . . . . . . 91
Installing ICEbrowser . . . . . . . . . . . 58 Trace file location . . . . . . . . . . . . 91
SI GUI unique actions . . . . . . . . . . . 59 SI GUI traces . . . . . . . . . . . . . 92
Optional files . . . . . . . . . . . . . 59 Minimal logging. . . . . . . . . . . . 92
Overriding SI GUI screen elements . . . . . 59 Moderate logging . . . . . . . . . . . 92
Using the POS application for the SI GUI . . . 59 Maximum logging . . . . . . . . . . . 92
Configuring CSS. . . . . . . . . . . . . 61 CSS (virtual session) trace . . . . . . . . 92
Running CSS under Java6 . . . . . . . . 61 Remote GUI trace . . . . . . . . . . . 93
Enabling CSS . . . . . . . . . . . . . 61 POSBC trace . . . . . . . . . . . . . 93
Starting CSS . . . . . . . . . . . . . 62 Java logging properties . . . . . . . . . 93
Managing CSS . . . . . . . . . . . . 63 Redirecting standard error . . . . . . . . . 94
Configuring CSS running under Java6 . . . . 63 Session trace . . . . . . . . . . . . . . 95
Configuring failover . . . . . . . . . . 64 Audit tracing . . . . . . . . . . . . . 96
Configuring initial full failover . . . . . . . 66 Response and property files . . . . . . . . . 96
Enabling quick init for failover . . . . . . . 67 Java IO Processor (JIOP) trace . . . . . . . . 97
POS application usage for virtual sessions . . . . 67 JIOP tracing through JDKLogging . . . . . . 97
Transferring from one terminal to another JIOP tracing through non-JDKLogging . . . . 97
terminal . . . . . . . . . . . . . . 67 SYSDEFS.TXT . . . . . . . . . . . . . 97
Monitoring one terminal from another terminal 68 Device Manager trace . . . . . . . . . . . 98
Tender franking and endorsement . . . . . . 68 System properties . . . . . . . . . . . 99
Document printing . . . . . . . . . . . 68 Trace output . . . . . . . . . . . . . 99
Tender limit pickup. . . . . . . . . . . 68 VIRTOUT.nn and VIRTERR.nn . . . . . . . . 99
Manager's key required and other error GSA XML strings . . . . . . . . . . . . 99
conditions . . . . . . . . . . . . . . 68 Stop sign errors . . . . . . . . . . . . 100
Automatic terminal lockup . . . . . . . . 68 Trace logs . . . . . . . . . . . . . . 100
Tender verification for EPS tenders . . . . . 69 RMA Data Capture for Virtual Sessions. . . . . 100
Enabling PIN pads . . . . . . . . . . . 69 Data Capture Parameters . . . . . . . . 100
Price override reason codes . . . . . . . . 69 Troubleshooting common problems . . . . . . 101
Barcode Configuration. . . . . . . . . . 69 POSBC limitations . . . . . . . . . . . 101
Configuring the Service Provider and Deploying Outdated files on the RAM disk . . . . . . 102
Services . . . . . . . . . . . . . . . 69 JavaPOS Device in Use . . . . . . . . . 102
Configuring the Service Provider . . . . . . 69
Deploying services . . . . . . . . . . . 69
Appendix A. Primary application
Digital receipts . . . . . . . . . . . . 71
AEF properties files . . . . . . . . . . . 72 parameters . . . . . . . . . . . . 103
AEF bundles . . . . . . . . . . . . . 72
Appendix B. Optimizing Store
Chapter 7. Installing and configuring Integrator performance . . . . . . . 105
the Windows Client . . . . . . . . . 81 Controller settings in AEFVIRT.TXT . . . . . . 105
POSBC configuration on Windows Client . . . . 81 JIT Compiler . . . . . . . . . . . . 105
Requirements for AEF Remote Device Support . . 82 JVM heap size . . . . . . . . . . . . 105
Windows Client configuration steps . . . . . . 82 Terminal settings . . . . . . . . . . . . 105
Multiple Subnets . . . . . . . . . . . . 84 Optimizing OS 4690 performance. . . . . . . 105

iv User's Guide: Store Integrator User's Guide

Disk balancing . . . . . . . . . . . . . 106 Russian Electromagnetic Interference (EMI)
Checkout Support and Data Integration Facility 106 Class A statement . . . . . . . . . . . 114
In-store processor . . . . . . . . . . . 106 Japanese Electrical Appliance and Material
Logo printing on Remote GUI (ACE) . . . . . 106 Safety Law statement . . . . . . . . . . 114
Japanese power line harmonics compliance
Appendix C. Store Integrator SSL statement . . . . . . . . . . . . . . 115
certificate update instructions . . . . 107 Japan Voluntary Control Council for Interference
Class A statement . . . . . . . . . . . 115
Generating a new certificate . . . . . . . . 107
Japan Electronics and Information Technology
Using the new certificate . . . . . . . . . 107
109
Industries Association (JEITA) statement . . . 115
Korean communications statement . . . . . 115
Notices . . . . . . . . . . . . . . 111 Taiwanese Class A compliance statement . . . 115
Telecommunication regulatory statement . . . . 112 Cable ferrite requirement . . . . . . . . . 116
Electronic emission notices . . . . . . . . . 112 Electrostatic discharge (ESD) . . . . . . . . 116
Federal Communications Commission statement 112 Product recycling and disposal . . . . . . . 116
Industry Canada Class A Emission Compliance Battery return program . . . . . . . . . . 117
statement . . . . . . . . . . . . . . 112 For Taiwan: . . . . . . . . . . . . . 117
Avis de conformité à la réglementation For the European Union: . . . . . . . . 117
d'Industrie Canada . . . . . . . . . . 112 For California: . . . . . . . . . . . . 118
European Union Electromagnetic Compatibility Flat panel displays . . . . . . . . . . . 118
(EMC) Directive Conformance Statement . . . 112 Monitors and workstations . . . . . . . . . 118
European Community (EC) Mark of Conformity Trademarks . . . . . . . . . . . . . . 119
Statement. . . . . . . . . . . . . . 113
Germany Class A statement . . . . . . . 113
Index . . . . . . . . . . . . . . . 121
Australia and New Zealand Class A statement 114
People's Republic of China Class A electronic
emission statement . . . . . . . . . . 114

Contents v
vi User's Guide: Store Integrator User's Guide
Figures
1. Overview of Toshiba Store Integrator . . . . 2 12. Minimum recommended failover
2. Sureview Theme . . . . . . . . . . . 4 configurations continued . . . . . . . . 27
3. Silver Theme . . . . . . . . . . . . 5 13. Example of userfailover.properties file entries 64
4. Silver Theme Customer Screen . . . . . . 6 14. Message of non-failover enabled session 64
5. Silver Theme Lite . . . . . . . . . . . 7 15. Example of partial failover sessions . . . . 65
6. Sureview Theme with the enhanced receipt 8 16. Error messages . . . . . . . . . . . 66
7. Silver Theme with the enhanced receipt . . . 9 17. Property file hierarchy . . . . . . . . . 78
8. Silver Theme with the enhanced scrollbar 10 18. Default hierarchy for JAR files . . . . . . 79
9. SI data input card . . . . . . . . . . 11 19. Example A . . . . . . . . . . . . . 83
10. POS Business Component . . . . . . . . 12 20. Example B . . . . . . . . . . . . . 84
11. Minimum recommended failover
configurations. . . . . . . . . . . . 26

vii
viii User's Guide: Store Integrator User's Guide
Tables
1. OS 4690 V6.2 Classic or higher . . . . . . 13 18. SI GUI optional files . . . . . . . . . 59
2. 4690 V6.2 Enhanced and later . . . . . . 13 19. Properties of AEFLOAD.PRO . . . . . . 62
3. Return Codes . . . . . . . . . . . . 23 20. AEF bundles . . . . . . . . . . . . 72
4. Minimum configurations for failover with 21. Config properties bundles. . . . . . . . 74
sessions running in the 1.4.2 JVM . . . . . 25 22. SSL properties file . . . . . . . . . . 75
5. Toshiba Global Commerce Solutions Program 23. AEF and application JAR files . . . . . . 76
Product numbers for Store Integrator 24. User JAR files . . . . . . . . . . . . 79
components . . . . . . . . . . . . 29 25. POSBC file descriptions . . . . . . . . 81
6. Store Integrator components for a 4690 OS 26. Supported SI devices and corresponding SI
installation . . . . . . . . . . . . . 30 logical name . . . . . . . . . . . . 83
7. Store Integrator components for a Windows 27. Sample batch files for starting remote
installation . . . . . . . . . . . . . 32 applications . . . . . . . . . . . . 84
8. Store Integrator error messages during 4690 28. Logical device names used for remote devices
installation . . . . . . . . . . . . . 34 supported by the Remote GUI and the POSBC . 85
9. Store Integrator installation logs. . . . . . 35 29. Logical device names used for the virtual
10. Errors or warnings during install or uninstall 35 devices supported by the POSBC . . . . . 85
11. Link edit input modules . . . . . . . . 36 30. Trace types. . . . . . . . . . . . . 91
12. List of possible components of JAVAAEF1.L86 37 31. Mapping SI GUI response files to logging
13. Silver theme image sizes (Customer screen levels . . . . . . . . . . . . . . 93
browser window) . . . . . . . . . . 40 32. Property file selection for SI GUI . . . . . 96
14. Classic theme image sizes . . . . . . . . 40 33. Troubleshooting errors . . . . . . . . 101
15. Silver theme image sizes (Si GUI screensaver) 41 34. Potentially active hooks . . . . . . . . 103
16. Response files for starting the SI GUI on a 35. Parameter values for hook activation 103
controller/terminal . . . . . . . . . . 50 36. Resources for disk balancing . . . . . . 106
17. Property file keys . . . . . . . . . . 56

ix
x User's Guide: Store Integrator User's Guide
Safety
Before installing this product, read the Safety Information- Read This First.

Antes de instalar este produto, leia as Informações de Segurança.

Pred instalací tohoto produktu si prectete prírucku bezpecnostních instrukcí.

Læs sikkerhedsforskrifterne, før du installerer dette produkt.

Lees voordat u dit product installeert eerst de veiligheidsvoorschriften.

Ennen kuin asennat tämän tuotteen, lue turvaohjeet kohdasta Safety Information.

Avant d'installer ce produit, lisez les consignes de sécurité.

Vor der Installation dieses Produkts die Sicherheitshinweise lesen.

Prima di installare questo prodotto, leggere le Informazioni sulla Sicurezza.

Les sikkerhetsinformasjonen (Safety Information) før du installerer dette produktet.

Antes de instalar este produto, leia as Informações sobre Segurança.

xi
Antes de instalar este producto, lea la informaci¾n de seguridad.

Läs säkerhetsinformationen innan du installerar den här produkten.

xii User's Guide: Store Integrator User's Guide

About this guide
This guide describes how to install, configure, and use Toshiba Global Commerce Solutions Store
Integrator (SI) software.

Who should read this guide

This guide is intended for anyone responsible for planning, installing, using Toshiba Global Commerce
Solutions Store Integrator, and customizing the system using the configuration process. This guide
assumes a working knowledge of a point-of-sale (POS) application, such as the 4690 General Sales
Application (GSA), the Supermarket Application (SA), or the SurePOS Application Client/Server
Environment for 4690 OS (ACE), and of the 4690 Operating System (OS).

The process of extending the system through user exit programming and other forms of programming is
addressed in the Store Integrator Programming Guide. Customization and extension of graphical user
interface is addressed in the 4690 Store Integrator Graphical user Interface Programming Guide.

Where to find more information

Current versions of Toshiba Global Commerce Solutions publications are available on the Toshiba Web
site at http://www.toshibacommerce.com.
1. Select support.
2. Select Publications.

These guides are available on the Toshiba Global Commerce Solutions Web site:
v Store Integration (G581-0262)
v Retail on demand brochure (G580-3980)
v Store Integrator Programming Guide (G362-0562)
v Store Integrator Graphical User Interface Programming Guide (G362-0563)
v Data Integration Facility User Guide (GC30-4077)
v General Sales Application Planning and Installation Guide (GC30-3690)
v Remote Management Agent and Viewer User's Guide (GC30-4106)
v SurePOS Application Client/Server Environment for 4690 OS Planning and Installation Guide (GC30-4147)
v Supermarket Application Planning and Installation Guide (GC30-3633)
v 4690 OS Programming Guide (SC30-4048)

xiii
xiv User's Guide: Store Integrator User's Guide
Notice statements
Notices in this guide are defined as follows:
Notes These notices provide important tips, guidance, or advice.
Important
These notices provide information or advice that might help you avoid inconvenient or problem
situations.
Attention
These notices indicate potential damage to programs, devices, or data. An attention notice is
placed just before the instruction or situation in which damage could occur.
CAUTION
These statements indicate situations that can be potentially hazardous to you. A caution statement
is placed just before the description of a potentially hazardous procedure step or situation.
DANGER
These statements indicate situations that can be potentially lethal or extremely hazardous to you.
A danger statement is placed just before the description of a potentially lethal or extremely
hazardous procedure step or situation.

xv
xvi User's Guide: Store Integrator User's Guide
Summary of changes
June 2014
This edition includes updates for Store Integrator Version 3 Release 5.

February 2013
This edition includes updates for Store Integrator Version 3 Release 4.

October 2011
This edition includes updates for Store Integrator Version 3 Release 3.

xvii
xviii User's Guide: Store Integrator User's Guide
Chapter 1. Overview
The Toshiba Global Commerce Solutions Store Integrator (SI) delivers the next-generation store platform.
Store Integrator provides the foundation for integrating existing store solutions, adding new solutions
and touchpoints, and integrating the store to the enterprise. Unlike the typical store configuration, SI is a
fully integrated environment based on industry standards. Store Integrator supports the integration of
Toshiba Global Commerce Solutions and Business Partner point-of-sale (POS) solutions and hardware
from various providers.

The Store Integrator provides the following benefits:

v Easier access to real-time information
v Reduced maintenance costs
v Cost-effective and easy integration with existing POS applications
v Custom solutions that are less dependent on the stability of the provider

Retailers typically have enormous investments in customized user-exit programming and in other
modifications and enhancements of their existing POS applications. Store integrator enables existing POS
applications to support the new customer interfaces and to provide important new capabilities, while
retaining the use of the business logic embodied in the existing POS application software.

SI has been designed to easily facilitate POS application integration with various other client applications.
Applications can be integrated through a Java interface, and an XML application programming interface
(API). By integrating with existing POS applications, client applications are able to monitor and control
existing POS logic.

Several examples of client application-integration solutions are as follows:

Home shopping application
The client shopping application uses the existing POS logic for pricing and selling items.
Portable shopper
The client shopper application uses the existing POS logic for pricing and selling items,
calculating transaction totals, and suspending transactions.
Fuel solutions
The client fuel applications use the existing POS logic for entering customer loyalty, pricing and
selling items, paying with credit, or suspending transactions.
GUI solution
The client GUI application monitors transaction activity through XML events to receive data such
as item information, item price, and running transaction totals for display.

Figure 1 on page 2 depicts the overall SI design.

1
Overview

Figure 1. Overview of Toshiba Store Integrator

Toshiba Store Integrator includes the following components:

v Application Extension Facility (AEF)
v Store Integrator Graphical User Interface (SI GUI)
v POS Business Component (POSBC)
v POS Provider/POS Server API

Application Extension Facility

The Application Extension Facility (AEF) allows existing functionality within the General Sales
Application (GSA), the Supermarket Application (SA), and the SurePOS Application Client/Server
Environment for 4690 (ACE) to be accessible through a set of APIs for use remotely or by other
applications.

The AEF API does not prohibit the integration with another POS application. If GSA, SA or ACE is not
installed on the 4690, AEF will be installed with basic support for a non-specific application which would
be used to develop the integration.

The AEF enables the existing POS terminal sales program to run under AEF Client Session Server (CSS)
software on a store controller. AEF CSS can support a non-register device, such as a mobile portable
shopping device, a kiosk, or a Web-based application. In this manner, the terminal sales program appears

2 User's Guide: Store Integrator User's Guide

 Overview

as though it were running in the device (or as part of the Web-based application). Instead, the program is
running in a CSS session on the 4690 controller, and the only software present within the device (or
Web-based application) to provide this functionality is a minimal amount of thin client software.

A terminal sales program running in a CSS session through AEF Remote Device Support is capable of
supporting input/output (I/O) devices attached to a remote client. Under Remote GUI, such a remote
device can be a scanner, POS printer (for example, a 4610), or personal identification number (PIN) pad.

Virtual devices are used when a CSS session is running, yet no physical hardware exists. The devices are
emulated through software so that the POS application functions correctly, as if the physical devices
existed.

The AEF has the following features:

v Programmatic access to POS functions using a Java API
v Integration of POS logic into other applications
v Extension of the POS application through Java
v Remote management functions consisting of monitoring and controlling the real and virtual POS
sessions and their environments
v A Java- based messaging bus capable of transporting XML messages between the point of sale
application service.

The AEF can be used on either the POS controller or the terminal. On the controller, AEF enables the
existing POS terminal sales application to run in a virtual CSS session. Multiple virtual sessions can be
operating simultaneously on the same controller supporting applications that need to integrate with POS
business logic. When the AEF is used on a physical POS terminal, it enables the POS terminal sales
application to be extended by using Java. It also supports the Store Integrator GUI feature.

The AEF provides session failover, a function that automatically switches to backup sessions in a timely
manner. In addition, the AEF can provide customer transaction integrity, which is referred to as full
failover support. ACE supports both full and partial failover. The Toshiba Supermarket Application
supports full failover. GSA does not support failover.

Partial failover support provides terminal number integrity, but not transaction integrity. In the event that
a transaction is in progress when the controller fails over, the client is responsible for replaying the
transaction.

The process of failing over is automatically handled by AEF failover code. For load balancing reasons, the
goal of switchback is to keep the sessions distributed, as in the usual setup. Therefore, after a failover has
occurred, as soon as all the controllers are available, a switchback to the usual setup is requested by the
server. The server sends a switchback-in-progress event to the client, and the client is then responsible for
destroying the session and requesting a new session, which can then be served by that session's primary
controller. The AEF clients that are supplied by Toshiba (such as POSBC and Remote GUI) contain their
own logic for switchback.

Store Integrator GUI

The SI GUI enables you to develop simple, intuitive consumer and operator interfaces for GSA, SA, and
ACE using XML. No programming is required. Those who have invested in the Toshiba SureVision GUI
programming request for price quotation (PRPQ) to create GUIs can protect those investments as they
move to this enhanced GUI.

Integration with other POS applications can also be done. Integration may require some programming
initially to instrument the application for XML messages.

Chapter 1. Overview 3
Overview

SI GUI Silver Theme

SI V3R3 introduced a new Silver Theme to the SI GUI. The Silver Theme brings a contemporary look and
feel to the SI GUI improving the usability of the SI GUI. The Silver Theme is not enabled by default. To
enable it, add the following property to your SV properties bundle:
theme.active=silver

Note: Users who have extensions and customizations to SI GUI components should review the
"Migrating to the SI GUI's Silver Theme" section in the Store Integrator Programming Guide because there
are some specific recommendations for component implementations which will facilitate their integration
with the silver theme.

Figure 2. Sureview Theme

4 User's Guide: Store Integrator User's Guide

 Overview

Figure 3. Silver Theme

Chapter 1. Overview 5
Overview

We have also overhauled the customer GUI to give it a more contemporary look and feel as well. The
new customer GUI is not enabled initially when selecting the Silver Theme. To enable it, add the
following property to your SV properties bundle:
customer.screen.target=silver

Figure 4. Silver Theme Customer Screen

6 User's Guide: Store Integrator User's Guide

 Overview

Silver Theme Lite

As discussed in Chapter 2, the Silver Theme requires a larger JVM heap and more physical memory than
the Sureview theme classic look and feel does. For those who cannot meet the increased physical memory
requirements, the SI GUI also includes a Silver Theme Lite. Silver Theme Lite uses the same GUI images
as the Silver Theme but with fewer colors, shades, shadows, and gradients. The same vibrant icons are
used for both the Silver Theme and Silver Theme Lite designs. The SI GUI activates Silver Theme Lite
automatically when your system does not meet the JVM heap requirements. You are not required to
perform any special configuration procedures to use it

Figure 5. Silver Theme Lite

Chapter 1. Overview 7
Overview

SI GUI touch-enabled receipt

The SI V3R3 also introduced a new SI GUI touch-enabled receipt. The touch-enabled receipt is available
on both the Sureview Theme and the Silver Theme. This new receipt is not enabled by default. To enable
it, add the following property to your SV properties bundle.
enhanced.receipt.enabled=true

Note: The SI V3R4 refresh introduced an alternate method of voiding items as a part of the touch-enabled
receipt function. Touch-enabled receipt functions that require an item to be voided, did so under the
covers. These voids were logged to the TLOG like any other void. SI GUI now voids items in ACE using
an alternate method, where these voids are identified differently in the TLOG. Therefore, ACE operator
void reports will no longer include voids as a result of the touch-enabled receipt function.

Figure 6. Sureview Theme with the enhanced receipt

8 User's Guide: Store Integrator User's Guide

 Overview

Figure 7. Silver Theme with the enhanced receipt

Chapter 1. Overview 9
Overview

SI GUI enhanced scrollbar

SI V3R3 also included a new enhanced scrollbar that allows the operator to jump directly to the top and
bottom of the receipt, as well as page up and down. The enhanced scrollbar is not enabled by default. To
enable it, add the following property to your SV properties bundle:
ScrollBar.enhanced.mode.enabled=true

Figure 8. Silver Theme with the enhanced scrollbar

The page up and page down buttons can also traverse the receipt one line at a time. If you wish to use
them this way, add the following property to your SV properties bundle:
ScrollBar.button.increment.unit=false

Store Integrator GUI V3R4 touch-enabled receipts will support voiding paper coupon items.

10 User's Guide: Store Integrator User's Guide

 Overview

Store Integrator Data Input Cards

Store Integrator GUI V3R4 introduces an enhanced data collection system (Data Input Cards) to allow all
data to be entered in the same fashion while consolidating the components used to collect the data.

The Data Input Cards are not enabled by default. To enable the Data Input Cards, add the following to
your SV properties bundle:
DataInputCard.feature.enabled=true

Data Input Cards are only supported on silver theme and customer specific themes.

Figure 9. SI data input card

POS Business Component

The POSBC is a client API that enables non-Java applications to use the AEF. The POSBC provides a
standard XML API for basic POS operations that allows client programs to perform the tasks required for
order processing through the POS system. In doing so, the POSBC hides some of the complexity of using
the AEF.

The objective of the POSBC is to integrate POS through a standard interface to multiple types of clients in
numerous connectivity and programming environments. Currently, POSBC supports the ACE and SA
applications.

Chapter 1. Overview 11
Overview

The POS printer is a device that is owned and managed by the POSBC. The POS printer can be used by
the POSBC XML clients to manage and print data on the POS printer using a fairly high-level language.

The POSBC supports the concept of logical "receipts," which contain information about the current POS
transaction. A logical receipt is structured so that it can be modified. For example, information can be
added, deleted, or changed. Additionally, a sales receipt can be used to support an electronic scrolling
receipt (such as those available on a Self-Checkout or Personal Shopper display).

Figure 10 describes the relationship of POSBC with SI.

Figure 10. POS Business Component

POS Provider
POS Provider is the client interface that sends batch requests to a POS system. This interface provides the
basic set of operations and tasks that are required for order processing through the point-of-sale system.
POS Provider enables the client to perform the following functions:
v Check the status of the POS system.
v Request the unit price information.
v Request extended prices and transaction totals for an order.
v Pay for an order.
v Confirm responsibility for reversing a charged payment.

12 User's Guide: Store Integrator User's Guide

Chapter 2. Requirements
This section describes the hardware and software requirements for Store Integrator.

Hardware requirements
For detailed information about the Store Integrator resource requirements, use the Knowledgebase Search
on the Toshiba Global Commerce Solutions support site at www.toshibacommerce.com/support and
search for Store Integrator resource requirements.

SI terminal and controller requirements

The following tables provide information about the processor and minimum RAM requirements for a
classic or enhanced terminal running the 4690 Vx Rx operating system. The controller requirements below
do not include capacity for any virtual sessions.
Table 1. OS 4690 V6.2 Classic or higher
Terminal (Processor/RAM) Controller (Processor/RAM)
GUI only use 1.8 GHz / 256 MB
Single Display
- 500 MHz / 512 MB
Dual Display
- 850 MHz / 512 MB
Solution use 2.0 GHz / 512 MB 1.8 GHz / 256 MB

Note: These requirements assume a 200 MB terminal ram disk

Table 2. 4690 V6.2 Enhanced and later
Terminal Configuration Terminal (RAM) Controller (RAM)
GUI only use 1 GB 512 MB

1 GB - C84 and newer

Solution use 1 GB 512 MB

1 GB - C84 and newer

v Terminals
– Any SurePOS 700 terminal supported by Enhanced 4690 OS V6.2 or higher
v Controllers
– Any controller supported by Enhanced 4690 OS V6.2 or higher

If you use the SI customer GUI with complex graphical information, you might exceed the memory
requirements for the terminal and or controller.

Software requirements
This section describes the software requirements for Store Integrator.

13
Requirements

4690 OS
For use with Store Integrator, the 4690 Operating System must be one of the following:
v Version 6 Release 2 Corrective Service Diskette 0CH0 or higher
v Version 6 Release 3 Corrective Service Diskette 0CC0 or higher
v Version 6 Release 4 Corrective Service Diskette 0D10 or higher

Store Integrator running with 4690 OS does not support separating controllers on different networks.

Virtual file system setup

Because Java programs often have file names greater than eight characters in length, the 4690 operating
system provides support for such file names by using a virtual file system (VFS). VFS must be enabled in
the 4690 operating system before you install Store Integrator.

For more information, see the latest 4690 OS Programming Guide at www.toshibacommerce.com/support.
Under "Software" select 4690 Operating System Support.

Note: The 4690 Publications are located under OS.

POS applications
This section describes the current requirements for using Store Integrator with ACE, GSA, or SA. Before
installing Store Integrator, contact Toshiba support to identify and obtain the most recent interim fixes
applicable to the software. The interim fix numbers listed in this guide could have been superseded as a
result of further Authorized Program Analysis Report (APAR) activity.

Contact your application provider or integrator for the requirements for using Store Integrator with
another POS application.

ACE requirements
Store Integrator requires one of the following:
v ACE Version 7 Release 3
v ACE Version 7 Release 4

GSA requirements
Using Store Integrator with GSA requires the following items:
v GSA Version P001 or later
v GSA 4610 Printer Support Feature Version P001 or later. AEF does not support Model 3 or Model 4
printers
v GSA requirements for optional features:
– Price Management Feature Version L001 or later
– Toshiba Electronic Journal program product Version 2.1 (5697-G45) or later
v The GSA terminal sales application (with the proper hooks in place) must be linked again. See
“Selecting terminal sales components” on page 36 for more information.

Note:
1. The only GSA features supported by Store Integrator are those listed above.
2. Toshiba does not recommend that you maintain your own application source. Instead, maintain your
code at the specified CSD and interim fix levels.
3. For information on using the SI GUI's touch enabled receipt on GSA, use the Knowledgebase Search
on the Toshiba Global Commerce Solutions support site at www.toshibacommerce.com/support and
search for GSA Store Integrator Touch Enabled Receipt.
v Price override via the touch enabled receipt is not supported on GSA.

14 User's Guide: Store Integrator User's Guide

 Requirements

SA requirements
Using Store Integrator with SA requires the following software:
v Toshiba Supermarket Application Version P001 or later.
v SA 4610 Printer Support Feature Version P001 or later. AEF does not support Model 3 or Model 4
printers.
v SA requirements for optional features:
– Enhanced Electronic Funds Transfer (EFT) Feature Version P001 or later
– Electronic Marketing Version P001 or later
– SA ValuePack 2001 Version N001 or later
– Toshiba Electronic Journal 4690 Version M001 or later
– Toshiba 4680–90 SA Enhancement Feature Version K001 or later

Using the POSBC with SA requires the following software:

v Toshiba Supermarket Application Version R001 with EFIX 4363 or later.
v SA 4610 Printer Support Feature Version P001 with EFIX 4362 or later
v Requirements for Optional features:
– Electronic Marketing Version P001 with EFIX 4361 or later
– SA Value Pack 2001 Version N001 or later
– Toshiba Electronic Journal 4690 Version M001 or later
– Toshiba 4680–90 SA Enhancement Feature Version Q001 or later

The SA terminal sales application (with the proper hooks in place) must be linked again. See “Selecting
terminal sales components” on page 36 for more information.

Note:
1. The only SA features supported by Store Integrator are those which are listed above.
2. Toshiba does not recommend that you maintain your own application source. Instead, maintain your
code at the specified CSD and interim fix levels.
3. For information on using the SI GUI's touch enabled receipt on SA, use the Knowledgebase Search on
the Toshiba Global Commerce Solutions support site at www.toshibacommerce.com/support and
search for SA Store Integrator Touch Enabled Receipt.

4610 POS printer

4610 POS printer support is required.

Java 2
The 4690 Operating System includes the Java 2 software required for the configuration and execution of
Store Integrator. To install Java 2 on the 4690, you must enable the virtual file system (see “Virtual file
system setup” on page 14).

Java 6
The Enhanced 4690 Operating System also includes the Java 6 software required for configuration and
execution of Store Integrator Client Session Server in the 1.6 JVM.

ICEbrowser
For the SI GUI, ICEsoft's ICEbrowser® is an optional browser that can be used to provide a more
functional browsing experience.

Chapter 2. Requirements 15
Requirements

Client software
Client software using virtual CSS sessions requires using any of the following Microsoft products:
v Microsoft Windows 7 32/64 bit
– We do not support solutions that require remote devices on Windows 7.
– We do not support the SI GUI Developer Studio on Windows 7. SI GUI Developer studio users are
required to run it in the XP mode emulator.
v Microsoft Windows Embedded Point of Service (WEPOS)
v Microsoft Windows Embedded POSReady 2009
v Microsoft Windows Embedded POSReady 7 32/64 bit
– We do not support the SI GUI Developer Studio on POSReady 7. SI GUI Developer studio users are
required to run it in the XP mode emulator.
v IBM Java 1.6 Java virtual machine (JVM)
v IBM Java Communications API (COMM)
v Toshiba JavaPOS

Remote Management Agent requirements

Using Store Integrator with the Remote Management Agent (RMA) requires a V2R6 or later RMA Master
Agent in the store. Any RMA General Agent on a Store Integrator system needs to be V2R6 or later for
the Store Integrator Agent to be discovered.

16 User's Guide: Store Integrator User's Guide

Chapter 3. Understanding security
This section describes the Secure Socket Layer (SSL) and how to encrypt sensitive data.

Secure Socket Layer

With Store Integrator Version 2.0, you can configure a more secure way to protect sensitive data
transmissions between controllers, terminals, and SI-enabled devices. When enabled by an option setting,
SI invokes the SSL protocol on the transport system. By adding this additional security, various types of
sensitive data can be encrypted to prevent possible interception by unwanted users. The types of data
content that can be safeguarded are:
v Credit card numbers
v Pins
v Magnetic stripe reader (MSR) track data
v User names
v Passwords
v Check account information
v Pay-By-Touch, or some other unknown private data

SSL uses externally supplied certificates and keys to validate the authority of an external device (terminal,
application, and others) attempting to connect with the primary server. A default set of keys and
certificates are supplied on the SI installation disk, which allows quick and secure communications to
occur out of the box. However, you can either generate or acquire your own set of keys and certificates
that are unique to your environment.

The default expiring SSL certificates (signed client and server certificates) that are provided during the
installation process are active until August 30, 2014. The procedure for updating custom SSL certificates
can be found in Appendix C, “Store Integrator SSL certificate update instructions,” on page 107.

You are responsible for managing the SSL certificates. In a higher security environment, you can elect to
have your certificates expire more frequently, perhaps every 90 days. Store Integrator will not connect
with expired certificates. Connections to certificates that are expired or not in SI's trusted file store will
result in SSL exception errors during connection attempts.

By using appropriate management tools, such as iKeyman, you can create new certificates or modify
existing ones. iKeyman is a SSL certificate-management GUI tool that can be used to change the
characteristics of the certificates and key files. The rsskeys file is compatible with the iKeyman utility. You
can find further information on the use of iKeyman at: www-128.ibm.com/developerworks/java/jdk/
security/50/. Scroll down the page to "IKeyman," which takes you to the iKeyman User's Guide.

After creating or modifying, you then need to distribute the certificates to all of the appropriate parties.
SI's implementation of SSL requires only server-side certificates.

Several SSL properties are required to be set the same way on both the caller and receiver side. See
Table 22 on page 75 for a discussion of SSL configuration.

17
Understanding security

SSL concepts
This section describes the basic flow of the protocol and provides a general view of SSL in the
background. More detailed information on the internal workings of SSL can be found at:
www-128.ibm.com/developerworks/java/jdk/security/50/. Then, scroll down the page to the link for
the "IBMJSSE2 Guide".

Store Integrator uses a SSL system that operates on the “challenge” system. In this system, the receiving
end of the communication issues a challenge in response to the first contact it receives from the caller.
The challenge communications result in an exchange of public keys that are compared with trusted store
certificates. If these certificates match the challenge, communications proceed. If not, errors are written to
the SI log, and no further communications are permitted from that caller. If the certificate mismatch is
due to a configuration error, you can correct the certificates and restart SI to reset the system so that the
challenge can be reissued.

To restart the CSS, issue the following from the 4690 command line:
v adxcss1l stop
v adxcss1l start

The next part of the negotiation determines the maximum level of encryption level, if any, that both the
caller and receiver can understand. After these protocols have been completed, secure communications
between the two parties are in effect until the socket is destroyed.

The trusted certificates that are used in the challenges are stored in the rssstore file, while the original
keys are stored in the rsskeys file. The rsskeys and rssstore files are “bag” files, so they can contain
multiple entries. The rssstore file contains public keys that the challenging machine will use to verify that
they are communicating to the correct machine. These public keys are protected by a singular password
to the rssstore file. The passwords for these files and the locations of the files are stored in the
ssl.properties bundle. It is important that this file, and any overrides, be placed in the secured section of
the machines on which they are running. The rsskeys file contains private certificates (or keys) that are
used when a challenge is sent to that machine. The rsskeys file is protected by at least two passwords.

Note: A limitation exists in Store Integrator and Remote Management Agent (RMA) such that the internal
private key and the key for the rsskeys file must be the same.

Encrypting the userlogon.properties file (deprecated)

To prevent the discovery of terminal user names and passwords, you can encrypt the
userlogon.properties file and its associated property hierarchy. The encryption algorithm operates on
plain text property files and is included as part of the standard Java archive (JAR) files installed in the
c:\ADX_IPGM directory.

The following example describes how to encrypt the userlogon.properties file.

1. Make a directory on the M: drive so that long file names are supported. (If the directory already
exists, erase everything it contains.)
md m:\user
2. Copy the JAR file that contains the userlogon.properties file to that directory:
m:
cd user
copy c:\user\user.jar
3. Un-JAR the property file into the m:\user directory:
m:\java2\bin\jar -xf user.jar
4. Encrypt the userlogon.properties file:

18 User's Guide: Store Integrator User's Guide

 Understanding security

m:\java2\jre\bin\java -classpath c:\adx_ipgm\siutil.jar;c:\adx_ipgm\c_loging.jar

com.ibm.retail.si.util.PropertyEncoder
userlogon.properties
5. Rebuild the JAR file with the property file that you just encrypted:
m:\java2\bin\jar –cf user.jar *.*
6. Stop CSS, copy the JAR file back to its original location, and distribute it as required:
copy m:\user\user.jar c:\user
adxcsu0l 3 5 user.jar
7. Restart CSS.

SI will decrypt the property file each time it needs to access a user name or password.

Note: To prevent customer security leaks, no decryption programs will be delivered with SI.

Encrypting sensitive data in Store Integrator property files

Prior to SI V3 level 1116, only the applogon properties bundle could be encrypted. Beginning with SI V3
level 1116 any property in any AEF property file bundle can be encrypted.

There are several AEF property file bundles that contain sensitive data that should be hidden from casual
observers. The following bundles currently contain sensitive data:
v applogon.properties (User values are typically set in userlogon.properties)
v ssl.properties (User values are typically set in userssl.properties)
v automation.properties (User values are typically set in userautomation.properties)

Prior to deploying user versions of property files a new utility (SISECURE.BAT) can be used to encrypt
the sensitive data. This utility exists in the ADX_IPGM directory of the 4690, and in the
%COMMON_HOME% directory on a Microsoft Windows machine where SI is installed.

The automatic logon data (operator id and password) is typically contained in the userlogon.properties
file that is located in a jar, user.jar, and normally placed in the c:\user directory. It is generally good
practice to obfuscate the data in order to make it difficult for a casual observer to view sensitive
information.

The automatic logon data for the virtual sessions are specified in the following format:
sessionNum=operatorID,password

There must be a line that corresponds to each virtual session if you wish to use the automatic logon
feature of the AEF API. The sessionNum in the example above is referred to as a key, and the data to the
right of the = sign is called a value. In a real world example, the file may look like:

201 = 486453,4221
202 = 9123,10042

To obfuscate the data, this file can be run through the SISECURE.BAT utility. If the file currently exists, it
is probably located in the user.jar file in the c:\user directory, and would have to be extracted first.

New procedure for encrypting the userlogon.properties file

Extracting the user.jar on the 4690

Note: It is strongly suggested that you back up the original c:\user\user.jar first. A backup will ensure
that you can restore your system if something goes wrong during this process.

Chapter 3. Understanding security 19

Understanding security

On the 4690, you would extract the user.jar file to a temporary working directory. Normally, this is the
VFS disk, M:\user. The process is step intensive, but not difficult. Normally, all editing should be done
on the Master 4690 machine.

Stop css first. Then execute the following:

M:
M:/> mkdir user
M:/> cd user

If you already have the file in the user jar located in c:\user directory, execute:
copy c:\user\user.jar

Else, move your newly created file to the m:\user directory:

M:user/> java2sdk:jar -xf user.jar
M:user/> dir

There should be a userlogon.properties file in this directory.

Encrypting the userlogon.properties file

Now from the M: temp directory, run:
M:user/> c:\adx_ipgm\SISECURE.BAT userlogon.properties

If successful, a table will be generated that will show you how many keys were processed and how many
were encrypted. The output file is the same, in this case, as the original name.
==============================================
Number of keys processed : 2
Number of keys encrypted : 2
Number of keys previously Encrypted: 0
==============================================

May 28, 2009 9:22:00 PM com.ibm.retail.si.util.SiSecure encode

INFO: Writing encrypted property file to "userlogon.properties"
May 28, 2009 9:22:00 PM com.ibm.retail.si.util.SiSecure encode
INFO: Flushed buffer to file
May 28, 2009 9:22:00 PM com.ibm.retail.si.util.SiSecure encode
INFO: Property file update successful

You can type the contents of the userlogon.properties file and see that it obfuscated the value part of the
key \ value pair.
M:user/>type userlogon.properties
201_encrypted=E5004F53514F504E474F4D4D4C3B3B3B3B3B
202_encrypted=E500544C4D4E474C4B4B4F4D3B3B3B3B3B3B

Inserting updated file back into user.jar

Once done, you need to update the user.jar with the new userlogon.properties userlogon. and move it
back to c:\user.

If you had moved c:\user\user.jar into your temporary directory, delete the user.jar first, otherwise you
may get an error from the jar program.
M:user/>Del user.jar

Then execute the following:

M:user/> java2sdk:jar -cf user.jar *.*

These operations will put all files in the current directory into the user.jar.

20 User's Guide: Store Integrator User's Guide

 Understanding security

If you already have a user.jar file, as an alternative, you can be more surgical and update just that one
modified file back into the user.jar. You would not delete the old user.jar file you moved into the temp
directory. The update would be done directly on the moved jar. The update operation would then be
executed by typing:
M:user/> java2sdk:jar -uf user.jar userlogon.properties

When either option has been completed, execute:

M:user/>copy user.jar c:\user

And now the newly updated jar should be then distributed to all other subordinates or alternate
controllers:
adxcsu0l 3 5 c:\user\user.jar

Restart CSS for the new jar to take effect.

Encrypting the ssl.properties

The ssl properties files contains many entries that specify how tcpip connections should be encoded or
not. Some of these key values contain information that should be encrypted to prevent casual users from
obtaining information.

A typical userssl.properties file may contain 8 passwords which are considered sensitive data and should
be encrypted. An example of entries in a userssl.properties file is below:

Note: In this example, we modified the default passwords with new ones for the certificates we made,
the file contains references now to the new passwords.
#
# Access to the file
#
AEF.ServerKeyPassword=myPrivateCodeWord
AEF.GUIKeyPassword=myPrivateCodeWord
AEF.GUI1KeyPassword=myPrivateCodeWord
AEF.KeyPassword=myPrivateCodeWord

#
# Password to the trust file, if used
#
AEF.ServerTrustPassword=myPrivateCodeWord
AEF.GUITrustPassword=myPrivateCodeWord
AEF.GUI1TrustPassword=myPrivateCodeWord
AEF.TrustPassword=myPrivateCodeWord

In order to encrypt this, you either have to modify the keys to include the _encrypted suffix, or use a
regular expression (regex) to automatically encrypt them.

SISECURE.BAT userssl.properties -regex .*Password

The regex expression in this example,

.*Password

means to encrypt any key that ends with the “Password” suffix. Note that the period is important. The
period means, “any character”, and the * implies “any number of characters”. The following is a sample
run using this –regex expression..
May 28, 2009 9:14:10 PM com.ibm.retail.si.util.SiSecure summary
INFO:

Chapter 3. Understanding security 21

Understanding security

==============================================
Number of keys processed : 8
Number of keys encrypted : 8
Number of keys previously Encrypted: 0

and the contents of the file now are:

C:\>type userssl.properties
#
# Access to the file
#
AEF.ServerKeyPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B
AEF.GUIKeyPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B
AEF.GUI1KeyPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B
AEF.KeyPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B

#
# Password to the trust file, if used
#
AEF.ServerTrustPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B
AEF.GUITrustPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B
AEF.GUI1TrustPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B
AEF.TrustPassword_encrypted=E50088946B8D84917C8F805E8A7F80728A8D7F3B3B3B3B3B3B3B3B3B3B3B3B3B3B3B

Note: The program has automatically appended the “_encrypted” suffix to the appropriate keys. Store
Integrator will recognize that these values have been encrypted and will deal with them appropriately.

The new userssl.properties should now be reinserted into the user.jar using the procedure previously
outlined in “Inserting updated file back into user.jar” on page 20.

Encrypting automation.properties
A typical userautomation.properties file contains the following key which is considered sensitive data and
should be encrypted:
com\\ibm\\retail\\AEF\\automation\\automatic.manager.override.number

In order to encrypt this, you should modify the key to include the “_encrypted” suffix:
com\\ibm\\retail\\AEF\\automation\\automatic.manager.override.number_encrypted

and run the SISECURE utility:

SISECURE.BAT userautomation.properties

The new userautomation.properties should now be reinserted into the user.jar using the procedure
previously outline in “Inserting updated file back into user.jar” on page 20.

SISECURE.BAT details

Invocation
SiSecure filename [-output outFile] [-identifier keyID] [-regex expression]

The supplied input property file, filename, is read in, and any sensitive data is encrypted if not already
encrypted.
[-output outFile]
If the –output parameter is present, the results are written to the file specified. If no -output is
present the original file is overwritten with the newly encrypted data.

22 User's Guide: Store Integrator User's Guide

 Understanding security

[-identifier keyID]
The [-identifier keyID] option defines the signature for the protocol used to encrypt and decrypt
the data. The signature must be a registered RSSEncrypt signature. By default, the only registered
signature is "E5".
[-regex expression]
The [-regex expression] option defines the pattern used to find the properties to encrypt. If this
option is not specified, all properties with a key that ends with "_encrypted" are encrypted. This
option accepts only one regular expression.

Return Codes
SiSecure.class will return back DOS error codes based on conditions occurring during execution of the
program. These return codes can be used by batch programs to determine success or failure of the
program. The table below shows the possible return codes:
Table 3. Return Codes
DOS Code Meaning
0 OK, Input Read, Output Written
1 Input File not found
2 Error reading input file
3 Error writing output file
4 Command Line input usage error
5 Illegal or Malformed RegEx entered
6 Supplied Encryptor key Not supported

The SiSecure batch file itself cannot be used to return the error codes. If the error codes are required for
your processing, copy the java launch information from the batch file.

New Warning messages in SI log files

If you deploy user properties files that contain sensitive data which are not encrypted you may see the
following type of messages logged. You should follow the above steps to encrypt the sensitive data and
deploy the encrypted properties files. Only the first unencrypted key will be displayed to prevent log
overflow. If you correct the specified key, check other keys in the file to make sure all are appropriately
encrypted.

WARNING: Security: Property bundle ssl contains at least one property (property AEF.TrustPassword)
that should be encrypted but is not.

New INFO messages in SI log files

Whenever the Encryption logic is loaded, a message will be logged indicating the type of encryptor
available in your installation:

INFO: Encrypt key added to list: E5 - RSSStockEncrypt

Messages during SiSecure operations

Several messages may be output during the course of encrypting the property files. Assuming
USERSSL.PROPERTIES is being encrypted, you may encounter these messages:
Encrypting property file USERSSL.PROPERTIES
Status message showing what is being read and encrypted.

Chapter 3. Understanding security 23

Understanding security

Can't read properties file USERSSL.PROPERTIES

The file you are trying to encrypt doesn't exist in the specified path.
Supplied Encrypt key: E7 is not a valid encoder
The encoder you input doesn't exist or is not supported in your environment.
Writing encrypted property file to USERSSL.PROPERTIES
Encrypted data is being written to the output file.
Usage: SiSecure filename [-output outFile] [-identifier keyID] [-regex expression]
One of the pieces of data supplied to the SiSecure file is incorrect. Check spelling or make sure
you specified legal paths for the files.
Can't write properties file userssl.properties
The output file cannot be written. You either gave a bad path, or possibly the output file is write
protected.
Illegal Regular Expression supplied, nothing encrypted
You passed in a Regular Expression in the -regex parameter that is illegal. Encryption did not
occur. An example would be
*Password instead of .*Password

Encrypting additional properties

In addition to encrypting the properties described above, you can encrypt other properties in your user
properties files. Simply add the “_encrypted” suffix to the property keyword, run the SISECURE.BAT
utility on the property file and deploy the encrypted property file. See Table 20 on page 72 for files that
support encryption.

24 User's Guide: Store Integrator User's Guide

Chapter 4. Planning for Store Integrator
This section describes the recommended and supported SI configurations and the throttling mechanism
when planning for SI.

For more information about Store Integrator resource requirements, use the Knowledgebase Search on the
Toshiba Global Commerce Solutions support site at www.toshibacommerce.com/support and search on
SI resource requirements.

Recommended SI configurations
An SI solution must not exceed the scalability limitations currently in place. The current version supports:
v If failover is not enabled, a store controller can have no more than 80 ACE or 100 SA sessions, and no
more than 20 GSA sessions. A store can have no more than 300 total sessions.
v If failover is enabled, a store can have no more than 25 ACE or SA sessions. This includes a mixed
environment with failover and non failover enabled sessions. Failover is not supported on GSA so this
is not applicable to that environment.
v Failover is not supported for virtual sessions running in the 1.6 JVM.
v A store environment consisting of a master/file server and alternate master/file server configured with
typical application background tasks, running on current hardware.
v Controller systems at 2.0 GHz or better (such as System x 205 or SurePOS 4800-741 or better)
v A typical environment, such as ACE supporting 12 real registers running 30 transactions per hour with
30 items per transaction; all the standard POS (such as ACE, SA, GSA) background applications are
running as well.
Table 4 focuses on configurations using failover.
Table 4. Minimum configurations for failover with sessions running in the 1.4.2 JVM
XX Primary YY Primary
Controller Controller Sessions/YY Sessions/XX Sessions
XX Processor YY Processor backup backup /Usage Response
Configuration & Memory & Memory sessions sessions Details Time Recovery
Typical self Master 2.0 Alternate 2.0 0/4 4/0 4 lanes/ 15 1 second for
-checkout GHz 1 GB GHz 1 GB items per "addItem"
Full
trx/ 14 trx requests
Transaction
per hour per
lane
Fuel Alternate 2.0 Subordinate Pumps 12/11 Pumps 11/12 23 pumps/1 2 seconds for Full
GHZ 1 GB 2.0 GHz 1 add item, "addItem" Transaction
GB preauth, add requests
customer
and tender,
12 trx per
hour per
pump
Remote GUI Remote GUI Remote GUI 2 registers/ 1 second for
1/1 1/1 3 items per "addItem"
Full
trx/ 10 trx requests
Transaction
per hour per
lane

25
Planning for SI

Figure 11. Minimum recommended failover configurations

26 User's Guide: Store Integrator User's Guide

 Planning for SI

Figure 12. Minimum recommended failover configurations continued

Understanding the throttling mechanism

To address virtual session performance, AEF CSS has implemented a throttling mechanism. With session
throttling enabled, the system workload is reduced by restricting the number of sessions that can be
created concurrently. The throttling mechanism keeps a specified number of service slots open in which to
create and initialize sessions. If the service slots are full, any additional session requests are held until a
free slot opens. In this manner, only a specified number of sessions are brought up at the same time.

The properties to enable and configure session throttling are in the CONFIG.PROPERTIES bundle:

Chapter 4. Planning for Store Integrator 27

Planning for SI

###
# Configure AEF settings for local AEFSessionFactory.
#
# When session.throttling.enabled is true, session.throttling.increment is
# used to determine how many sessions can be created at the same time. If
# more than the given increment are attempting to be created at the same
# time, only the increment number will be allowed to do so, and the rest
# will each wait until a slot opens up.
#
factory.id=AEF_SESSION_FACTORY%nodename%
ready.wait.timeout=120000
server.poll.interval=10000
session.throttling.enabled=false
session.throttling.increment=10

The default session.throttling.increment is 10, however, lower numbers have been seen to produce
better results. Setting the increment to 2 or 3 keeps the overall time to bring up a large number of
sessions (~20) to a minimum. The optimal value for the session.throttling.increment is machine
dependent; every controller exhibits unique performance characteristics based on the hardware and
software being run at any particular time.

To change any of these values, create a siuserconfig.properties file. Include this property file in the
SIUSER.JAR file and place it in the ADX_IPGM directory.

28 User's Guide: Store Integrator User's Guide

Chapter 5. Installing Store Integrator components
The Store Integrator components are delivered on a single CD. This CD is used for installation on 4690
OS controllers, and Microsoft®Windows® client machines. Store Integrator GUI code is included on the
CD for customers who want to use this component. The Toshiba Global Commerce Solutions Program
Product numbers for these components are listed in Table 5.
Table 5. Toshiba Global Commerce Solutions Program Product numbers for Store Integrator components
Program Product Component Description
number
5724-AEF AEF Application Extension Facility
5724-GUI SI GUI Store Integrator Graphical User Interface
5724-COM Common Code common to AEF, SI GUI, and other Store Integration elements

The same CD is used to install the SI GUI on GSA, SA, and ACE systems. The 4690 OS installation
procedure automatically determines which of these POS applications is in use on your system, and selects
the appropriate software components. If none of GSA, SA or ACE is present, the installation procedure
will install software components which are the basis for integration with another POS application.

Note: Use of Store Integrator with POS applications other than these three requires modification of the
POS application software to pass the required data in XML format to AEF, and implementation of a
customized installation process.

Carefully read all of the following instructions before attempting to install the Store Integrator software.

Installing SI on a 4690 operating system

Store Integrator can be installed either interactively, silently, or remotely.

Interactively installing Store Integrator on a 4690

For interactive installation of Store Integrator on a 4690 controller, perform the following steps:
1. If Data Integration Facility or SI GUI is already installed, check Apply Software Maintenance (ASM)
to verify that Common, AEF, and SI GUI are not in backup mode.
2. To begin installing Store Integrator, insert the installation CD in the Master Controller and type the
following at a command prompt:
p:\4690\install
3. Accept the license agreement for Store Integrator. An installation menu is displayed.
4. See Table 6 on page 30 to identify the available Store Integrator menu options. Select these options to
install. The installation process takes several minutes.

Note: Select the Store Integrator GUI feature only if you require the GUI on a local (real) terminal. If
you require Remote Device Support (with or without remote GUI display support) on your client
machines for operation under CSS, you do not require the GUI component on the 4690 Controller.

29
Installing SI components

Table 6. Store Integrator components for a 4690 OS installation

Store Integrator menu Components included
option
Common AEF SI GUI
Application Extension U U
Facility
Store Integrator GUI U U U

5. After installation is complete, select the option to view the installation logs (C:\COMNINST.LOG,
C:\AEFINST.LOG, and C:\GUIINST.LOG). Verify that no errors occurred during installation.
6. From the 4690 System Main Menu, select 4, Installation and Update Aids.
7. Select 5, Apply Software Maintenance.
8. Select 2, Activate Maintenance.
9. From the Activate Maintenance panel, click Test, or Accept to process the installation for Common,
AEF, and SI GUI. The software maintenance files are distributed to other controllers on the local area
network (LAN). The controllers restart after distribution is completed.

Silently installing Store Integrator on a 4690

To install Store Integrator using silent mode, run one of the following commands:
v To install the AEF option that includes COMMON and AEF components:
p:\4690\install aef
v To install the GUI option that includes COMMON, AEF and GUI components:
p:\4690\install gui
v To review the results of the silent installation, edit the c:\simaster.log file.

Remotely installing Store Integrator on a 4690

To prepare a directory for remote distribution, the application installation must be prepared on a local
master controller with all controllers on a LAN system up and running. Also, if any Store Integrator
component is in maintenance, you must run ASM to cancel or accept it before beginning the remote
installation.

This process will delete the contents of C:\ADX_IMNT when it begins. Please accept or cancel the
maintenance of any other software products before beginning this process.
1. On the master controller, insert the CD ROM into the CD ROM drive.
2. From command mode type P:\4690\INSTALL and press the enter key.
3. An Installation Menu will be displayed.
v Select option 6 if you wish to prepare a remote installation directory for the Application Extension
Facility.
v Select option 7 if you wish to prepare a remote installation directory for the Store Integrator GUI
on the local master controller.
4. A warning will be displayed prior to the deletion of the contents in C:\ADX_IMNT.
v Press 1 to proceed.
v Press 2 to abort the process and return to the main menu.
5. The remote installation directory creation procedure will produce several files in ADX_IMNT of size
2,500,000 bytes or less. The files created will be named SIFRINST.ZIP and SIFRINST.xxx, where 'xxx'
ranges from 001 to 999 for as many files as are needed. If this file size is too big or small for your
location, then the batch file can be changed by the user to create an acceptable file transmission size
for your location.
6. After the directory preparation is complete, the installation menu will be displayed again.

30 User's Guide: Store Integrator User's Guide

 Installing SI components

v Select option 8 to display the installation log file for the current installation and check for error
messages.
v The output from this step may also be viewed for each individual component by reviewing the
C:\COMNPREP.LOG, C:\AEFPREP.LOG, and C:\GUIPREP.LOG files.
v If there are any errors, contact the Toshiba Support Center before continuing.
7. If you are using ADCS/HCP to transmit the files from the host based controller to the host, then to
the store, there are two problems you may encounter with the transmission.
v ADCS has a 8 meg file size limit. The size of the Store Integrator maintenance packages exceeds
this limit.
v ADCS has a 6 character file name limit, so you will need to use an ADCS/HCP coded name that
will get/put the files in the correct 4690 subdirectory.
v To transfer the SIFRINST.* files with ADCS/HCP coded names, first rename each of the files to
ADXSIFxF.DAT such that each file has a unique name, then use the ADCS/HCP name "!SIFxF" to
transmit each of the files. You will need to rename the files back to the original SIFRINST.* file
names at the remote location before continuing.
8. Create or update the RCP selection file (ADXCSHCF.DAT in ADX_IDT1) and create an RCP
command file, EAMRCP1F.DAT, to decompress the ADX_IMNT directory, initiate the REMOTE batch
file to copy the install files and perform installation/migration, and put the installation/maintenance
into TEST mode on the remote controller. The selection file (ADXCSHCF.DAT) needs to contain the
name of the command file: EAMRCP1F.DAT. The command file (EAMRCP1F.DAT) needs to contain
the following command:
v C:\ADX_SPGM\COMMAND -C C:\ADX_IMNT\SIREMOTE.BAT
v You may also include the command to run Apply Software Maintenance in this file.
v ADXCST0L N 1AU 1BC if you are installing the Application Extension Facility only
v ADXCST0L N 1AU 1BB 1BC if you are installing the Store Integrator GUI
9. Transfer the files SIFRINST.* from C:\ADX_IMNT to your host processor, then to the ADX_IMNT
directory in your target store. In addition, you will need to transfer the SI Compression Utility,
SICMPUTL.BAT, and the SI Remote Install Utility, SIREMOTE.BAT, to the ADX_IMNT directory in
your target store. The BAT files can be found on the SI installation CD in the \4690 subdirectory. You
will also need to transfer the RCP selection file(s) and the RCP command file(s) to the ADX_IDT1
directory of your target store.

Note: ADCS users must rename the transmitted files to the original file names before continuing.
10. Invoke the Remote Command Processor (RCP) using the START USER PROGRAM feature of ADCS
or the INITIATE CLIST command of Netview DM.
v After the installation/maintenance has been applied, retrieve the status file,
ADX_SDT1:ADXCSHSF.DAT, and the remote install log file(s), C:\SIREMOTE.LOG,
C:\COMNINST.LOG, C:\AEFINST.LOG, C:\GUIINST.LOG, to determine the success or failure of
the RCP. It is critical to insure the maintenance was successful.
11. If the installation was successful and you did not include the Apply Software Maintenance command
in the RCP selection file, please apply the software maintenance at this time.

Interactive Common, AEF, and GUI Installation on Windows

You can install the Common, AEF and GUI components on a Windows system. This enables you to use
Windows to access remote Client Session Server (CSS) sessions.

The level of Store Integrator (AEF.JAR) files on the 4690 controller and on the client must always be the
same (which is automatically the case if both sets of files are obtained from the same installation CD). A
mismatch in JAR files might cause RMI exceptions and other unpredictable results. Therefore, when
updates of this software become available, you must upgrade the 4690 OS and Windows Client software
simultaneously so that the levels of each always match.

Chapter 5. Installing Store Integrator components 31

Installing SI components

Note: The POSBC's "RcptArch" and "Persist" directories are not migrated when installing a new level of
the AEF on your Windows machine. All POSBC recovery data and archived receipts will be lost after the
installation is complete. It is recommended that you complete any outstanding transactions and print all
receipts in your receipt archive before installing a new level of the AEF.

Interactively installing Store Integrator on a Windows operating system

Note: Before installing Store Integrator on a Windows operating system, ensure that Toshiba JavaPOS
1.13.3 or later, which provides the JRE used by Store Integrator, has been installed. For more information,
please see Chapter 7, “Installing and configuring the Windows Client,” on page 81.

To begin installing on Windows, perform the following steps:

1. Log on with administrator authority.
2. Insert the installation CD into the CD drive.
3. To run the installation program, open a command prompt window and enter the following command:
X:\windows\setup.exe

where X is the CD drive.

Note: InstallShield searches for the location of the installed Java Runtime Environment (JRE) on the
machine. If the JRE is not in the default location, this search can take a long time. If you know the
location of the JDK, you can bypass the search and install using the following command:
X:\windows\setup -is:javahome <jdkpath>

where jdkpath is the path to the JRE directory.

4. On the Welcome to the InstallShield Wizard for Store Integrator panel, click Next.
5. The default installation directory is displayed. To use the default, click Next to continue. Otherwise,
click Browse to select a different directory, and then click Next.
6. A list of installation options is displayed. Use Table 7 to identify the options to be installed based on
the Store Integrator menu option selected. If you want to install the SI GUI, click Next. Otherwise,
click the radio button next to the installation option of your choice and click Next. The suggested
install location for clean installs should be C:\Program File\Toshiba and not C:\Program Files\IBM.
A "clean" install is defined as no previous version of SI is currently installed. In the case that a prior
install of SI leaves an IBM/StoreIntegrator folder after the uninstall, SI will suggest that
Toshiba/StoreIntegrator be the install folder for this scenario, which also will be considered "clean".
Table 7. Store Integrator components for a Windows installation
Store Integrator menu Components included
option
Common AEF SI GUI
Application Extension U U
Facility
Store Integrator GUI U U U

7. A list of SI AEF features is displayed. If you want to enable AEF Secure Sockets Layer (SSL), then
select that option. If you want to enable POSBC Server SSL (tracks AEFSSL), then select that option.
8. A summary panel is displayed with the information pertaining to the installation. If any of the
information is not correct, click Back to return to the previous panel and change your selection. When
all selections are correct, click Next.
9. The installation process takes several minutes. When the process is complete, click Finish.

Each selected option is installed to its own directory, which is identified by its name and version number.
A maximum of two versions of each component are allowed on the system: the current version and a

32 User's Guide: Store Integrator User's Guide

 Installing SI components

backup version that you can reactivate if the current version does not work as expected. This is similar to
the 4690 OS Apply Software Maintenance process. For example, if Store Integrator's GA level is 1010056,
the AEF directory name is AEF1010056. The default installation location for Store Integrator is:
C:\Program Files\Toshiba\StoreIntegrator

You can change this value by using the Destination panel at initial installation. The AEF files go to the
C:\Program Files\Toshiba\StoreIntegrator\AEF1010056

directory. The CLASSPATH and other environment variables are updated to point to AEF1010056. You
can uninstall AEF at any time by issuing the following command:
C:\Program Files\Toshiba\StoreIntegrator\_uninstAEF1010056\uninstall

If there is a maintenance release of Store Integrator 1010059 and you select AEF, it is installed to:
C:\Program Files\Toshiba\StoreIntegrator\AEF1010059

The CLASSPATH and other environment variables are modified so that they point to the AEF1010059
directory instead of the AEF1010056 directory. The AEF1010056 directory becomes the backup program
directory, and AEF1010059 directory becomes the active program directory. If you do not want to keep
the backup directory, issue the following command at any time:
C:\Program Files\Toshiba\StoreIntegrator\_uninstAEF1010056\uninstall

If you need to go back to the previous version, you can remove the AEF1010059 by calling the following
command to remove the AEF component:
C:\Program Files\Toshiba\StoreIntegrator\_uninstAEF1010059\uninstall

Alternately, if there is another maintenance release of Store Integrator called 1010064 and you select AEF,
you are asked to uninstall AEF 1010056; if you already have both 1010056 and 1010059 on the system.
After removing 1010056, you can continue to install version 1010064.

After the installation is complete, AEF1010059 becomes the backup program directory, and AEF1010064
becomes the active program directory.

Silent Store Integrator installation on Windows

To install Store Integrator using silent mode, the response file needs to be prepared first. The sample
response files are on the CD for referencing (windows\responseW.txt). Then start the product Installer
using the command:
silent <response file with absolute path> [path to multisuite.jar] [-forceExit]

For example,
silent c:\windows\responseW.txt d:\windows

where d is the CD-ROM drive.

Note: The AEF, COMMON, and GUI folders must be in the same location as the multisuite.jar

Uninstalling on a Windows operating system

An uninstallion on Windows can only be performed at the component level.

Interactively uninstalling on Windows

You can choose to uninstall components that are currently installed on your system. If the GUI option is
installed on your system, from %SI_HOME%, enter the following commands to uninstall:
v uninst COMMON

Chapter 5. Installing Store Integrator components 33

Installing SI components

v uninst AEF
v uninst GUI

If the AEF option is installed on your system, from %SI_HOME%, enter the following commands to
uninstall:
v uninst COMMON
v uninst AEF

Silently uninstalling on Windows

You can choose to uninstall components that are currently installed on your system. If you use the silent
mode for an uninstall, the response file must be prepared prior to uninstalling. The sample response files
are on the CD. For Windows refer to:
windows\<component dir>\responseW.txt

where <component dir> is COMMON, AEF or GUI

If the GUI option is installed on your system, from %SI_HOME%, enter the following commands to uninstall:
v uninst COMMON -silent <response file>
v uninst AEF -silent <response file>
v uninst GUI -silent <response file>

If the AEF option is installed on your system, from %SI_HOME%, enter the following commands to
uninstall:
v uninst COMMON -silent <response file>
v uninst AEF -silent <response file>

Note: The SI uninstaller does not remove the uninst.bat or the responsew.txt file used to uninstall the
product from the command line. You are free to remove these files after you have uninstalled all of the SI
components.

Installation-related problems
This section explains how to handle some problems associated with Store Integrator installation.

Error messages during installation

If an error message is displayed during the 4690 OS installation process, see Table 8 for an explanation.
The logs referred to in the response messages are installation logs (see “Installation logs” on page 35).
Self-explanatory error messages are generated by the installation process. If you have problems with
program execution after installing Store Integrator, see Chapter 8, “Problem determination,” on page 91.

Note: For Windows installation, a file named log.txt contains installation error messages. See Table 10 on
page 35 for the location of this file.
Table 8. Store Integrator error messages during 4690 installation
Message Explanation
The following file could not be created. The The installation utility could not create one of the files
installation will not continue. File = filename needed for installation. Verify that there is enough disk
space and the file system is not damaged. Retry the
installation.
The following directory either does not exist or is The expected temporary installation directory was not
empty. The installation will not continue. Dir = found. View the logs to locate the failure.
dirname

34 User's Guide: Store Integrator User's Guide

 Installing SI components

Table 8. Store Integrator error messages during 4690 installation (continued)

Message Explanation
There was an error reading/writing the following One of the files being modified could not be read or the
file. The installation will be terminated. File = new file could not be written. If the file has an extension
filename of .DAT, verify that the file exists in the directory noted.
If the file extension is .NEW, verify that there is enough
disk space available.
The following file could not be found. One of the files needed for installation or modification
was not copied to the temporary installation directory.
View the logs to find out where the failure occurred.

Microsoft Windows Program Compatibility Assistant

Microsoft Windows 7, and its derivatives, can launch the Program Compatibility Assistant (PCA) after
running the Store Integration installation/uninstallation programs on these platforms. If you see this
dialog, you can safely choose "This program installed correctly" if you completed the install/uninstall, or
cancel if you cancelled the install/uninstall.

User data location

If you silently install two levels of SI back-to-back in the same console window, you may end up with
user data folders in %ALLUSERSPROFILE% and in %SI_HOME%. To resolve this issue, you must uninstall both
versions of SI and then reinstall them, closing the console window and opening a new one between
installs.

We recommend that you do not attempt to silently install two levels of SI using the same console
window. The SI installer uses environment variables during the installation process and changes made
during the first install will not be reflected during the second install in this scenario. This applies to
installation and uninstallation.

Installation logs
Log files are generated by the 4690 OS installation process for Store Integrator. Each file corresponds to a
specific Store Integrator component (see Table 9).
Table 9. Store Integrator installation logs
Log file Store Integrator component
C:\SIMASTER.LOG All components if silent install performed
C:\COMNINST.LOG Common
C:\AEFINST.LOG AEF
C:\GUIINST.LOG SI GUI

On the Windows platform, the Store Integrator installer only writes a log file when errors or warnings
occur during the install or uninstall process. You will find this log file in the following locations:
Table 10. Errors or warnings during install or uninstall
Action Log File Path
Install %TEMP%/log.txt
Uninstall %SI_HOME%/log.txt

Chapter 5. Installing Store Integrator components 35

Installing SI components

Selecting terminal sales components

This section describes how to select terminal sales components.

GSA
For GSA to send data to AEF, you must link the necessary AEF interfaces into the terminal sales program
(EALTS10L.286).

When the AEF component is installed, the following files are copied to ADX_UPGM from the Store
Integrator CD:
v EALAEFC.LBJ (interface module)
v EALAEFUE.LBJ (interface user exit module)
v COMMAND.OBJ (C routine for retrieving command line prompts)

Before performing the terminal sales link edit, make the following changes to your link edit list
(EALTS10L.INP):
1. Add the following files to the list:
v EALAEFC.LBJ
v EALAEFUE.LBJ
v COMMAND.OBJ
2. Delete EALAEFS.LBJ (if present).

You must specifiy the maximum stack size in the link edit when linking the AEF interfaces into the
terminal sales program. The maximum stack size is FFE. Example of the link command: "link86
EALTS10L [i, STACK[MAX[FFE]]]".

For more information about linking GSA, see the GSA Planning and Installation Guide and the OS4690
Programming Guide .

SA
For SA to send data to AEF, you must link the necessary AEF interfaces into the terminal sales program
(EAMTS10L.286). To link AEF into your application, replace the JAVAGUIS.L86 stub module in the input
file (EAMTS10L.INP) for the link edit with the correct one from Table 11.
Table 11. Link edit input modules
Module Application
JAVAAEF1.L86 v AEF support only
v AEF support with SI GUI
JAVAAEF2.L86 AEF support and PRPQ SV (not SI GUI)
JAVAAEF3.L86 AEF support and ValuePack GUI Customer Display (not SI GUI)

These link edit input modules reflect a three-tier structure of calls to the Java virtual machine. This
structure results from the possible combinations of AEF with the SI GUI, with the SureVision PRPQ, with
the ValuePack GUI Customer Display, or with no GUI display support at all. (If you are using AEF with
SI GUI or with no GUI display support, select module JAVAAEF1.L86 for the link edit step.) If the L86
modules contain user exit code (either carried over from your previous SA implementation or required
for your current implementation), you must rebuild the chosen L86 module before performing the link
edit step. For more information on the structure of these modules and how to rebuild them, refer to the
“Requirements for User Exits, Extensions, and Source Modifications” section of the Store Integrator
Programming Guide (SC30-4084).

36 User's Guide: Store Integrator User's Guide

 Installing SI components

If there is a need to replace the Supermarket sales module (EAMTS10L.286) on a SA system that is
configured with failover sessions, CSS should be stopped on all systems prior to replacing the sales
application.

You must specify the maximum stack size in the link edit when linking the AEF interfaces into the
terminal sales program. The minimum stack size is FFE. An example of the minimum stack size is:
"link86 EALTS10L [i, STACK[MAX[FFE]]]".

For more information on linking options see "Chapter 9: Using the Linker Utility and the POSTLINK
Utility" in the latest 4690 Operating System Programming Guide at www.toshibacommerce.com/support.
Under "Software" select 4690 Operating System support.

Note: 4690 publications are located under "OS".

For current SureVision users

If you are already using the SureVision PRPQ and you want to migrate to SI GUI, your version of
JAVAGUIB.L86 will no longer be used. The entry for it in the link edit list must be replaced with
JAVAAEF1.L86. If you have user exit code within JAVAGUIU.LBJ that must be carried over from your
SureVision implementation, you must rebuild the JAVAAEF1.L86 file.

This is necessary because a new exit (Exit 5) has been added to JAVAGUIU.LBJ. Like the other four exits,
Exit 5 is packaged in a separate include module (JGUIU05.J86) for inclusion within JAVAGUIU.BAS. It is
included in the standard Supermarket Application User Exit installation package, along with the other
four JGUIU0n.J86 include modules for the other four exits.

When installing these user exit modules, be careful not to overlay your own previously modified user
exit modules, and be sure that they are included when recompiling JAVAGUIU.BAS. SA include modules
JAVAGUIV.J86, JGUIUVA.J86, and EAMXXCPY.J86 are also needed for the compilation.

For the link edit, you must incorporate this newly compiled user exit code (JAVAGUIU.LBJ) and the other
modules that comprise this library module into a new version of JAVAAEF1.L86. An input file
(JAVAAEF1.INP) for use with the LIB86 Library Utility has been provided for that purpose. The
installation process automatically copies it from the SI GUI CD into ADX_UPGM. See the 4690 OS
Programming Guide (SC30-4048) for information concerning use of the L86 utility.

Table 12 lists the components of JAVAAEF1.L86.

Table 12. List of possible components of JAVAAEF1.L86
Component Description
JAVAGUIU.LBJ First-tier routines called from the base SA
JASVGUIS.LBJ Stub version of SureVision PRPQ second-tier calls
JAVPGUIS.LBJ Stub version of ValuePack GUI Customer Display second-tier calls
JAVAAEFR.LBJ Real, as opposed to stub, version of AEF second-tier calls
COMMAND.OBJ C routine for retrieving command-line prompts

Note: The ValuePack GUI Customer Display support and Store Integrator GUI are mutually exclusive.

All of these component modules are part of the SA User Exit installation package except for
JAVAAEFR.LBJ, which is copied automatically into the ADX_UPGM directory from the SI GUI CD as part
of the installation process.

If you are already using the SureVision PRPQ but do not wish to migrate to the SI GUI, then your
version of JAVAGUIB.L86 must be replaced with JAVAAEF2.L86, as noted above, and the entry changed
to JAVAAEF2.L86 in the link edit list. You will have to rebuild JAVAAEF2.L86 if you have user exit code
Chapter 5. Installing Store Integrator components 37
Installing SI components

within JAVAGUIU.LBJ that must be carried over from your SureVision implementation. For further
discussion of this process, and for other relevant information, see the Store Integrator Programming Guide
(SC30-4084).

For more information about linking the Supermarket Application terminal sales program in general, see
the SA Planning and Installation Guide (GC30-3633).

ACE
An unmodified ACE system requires the substitution of a new terminal sales program, JSIFTS10.386 for
ACETSFSL.386. JSIFTS10.386 contains the necessary AEF functionality and is included with ACE Version
6 or above.

ACE users who have modified terminal sales programs should use the make command (build process) to
create a new terminal sales program (using the ACE Toolkit and including the AEF interface module,
DACEAEF.OBJ). ACE source code customers receive DACEAEF.OBJ and DACEAEF.CPP with Version 6 of
ACE. These files are required if user extensions are to be made to AEF or to the SI GUI.

SI V3 improved the memory utilization of the ACE application, allowing SI to run more ACE virtual
sessions in a given machine. Based on this new code, user replacement of the JSIFTS10.386 module will
require a reload of the 4690 controllers to replace the ACE sales application module.

Other POS application

The terminal sales options for integrations with other POS applications are specific to the application.
Please contact the application integrator for information.

38 User's Guide: Store Integrator User's Guide

Chapter 6. Configuring Store Integrator on 4690 OS
This section describes the steps for configuring AEF and SI GUI on the 4690 OS.

Configuring stand-alone terminals

This section explains how to configure the device characteristics and load definitions for terminals that
will run using AEF.

Note: If you are configuring a controller/terminal instead of a stand-alone terminal, see “Configuring the
controller/terminal” on page 49.

To configure a stand-alone terminal, select the following from the System Main Menu: (4) Installation
and Update Aids -> (1) Change configuration -> (5) Generic Terminal Configuration

Device characteristics
On the 4690 Terminal Configuration panel, select Device Characteristics. Select a device group to edit or
create a new device group for the set of terminals you are configuring. Make sure you give it a
meaningful name and description.

Set up the configuration for the particular hardware present on your systems. The following items need
to be configured for AEF:
v Java Redirection
v POS displays
v Keyboards
v Enhanced RAM disk for 4690 Java Bundle Preloading
v Video displays
v Graphics

Java Redirection
To configure Java Redirection, perform the following steps:
1. Click Java Redirection.
2. Click Enable Advanced Java Redirection.
3. Click Advanced.
4. Click only the ANDISPLAY, ANDISPLAY2, ANDISPLAY3, and I/O Processor and Tone devices.

Multiple cash drawers:

JavaPOS does not support multiple cash drawers. If you want to use the ACE multiple cash drawer
feature, do not redirect cash drawers.

Printer redirection is not supported. Even when the Advanced setting is selected, the Store Integrator
does not redirect the printer.

Configuring POS displays

If you will be using an operator display, select System Display -> Other. If there is no System Display
option, skip this step. (For video displays, see “Configuring video displays” on page 40.)

Configuring keyboards
To configure keyboards, click JavaPOS (default).

39
Configuring SI on 4690 OS

Note: POS Keyboards combined with a touch GUI can only be used when the system is in a state that
accepts numeric input. Number keys (0-9), and the Enter and Clear keys are the only keyboard input that
is supported.

Enhanced RAM disks for 4690 Java Bundle Preload

For additional information, see “Using OS 4690 Advanced Java Configuration and Bundling Instead of
.RSP files for the SI GUI application” on page 42.

Configuring video displays

Although video displays are not required for terminals running AEF without the SI GUI, they are likely
to be present. If so, select the following check boxes:
v Video display enabled
v Video is System Display (if using Operator Display)
v Enable screen saver

Select the following option from the list:

v 25 lines by 80 characters

Customer screen browser window recommended image sizes

This document contains recommendations for the maximum images sizes used in the browser
(advertising) window of the customer screen when it is desired to only display an image. The image
should be specified in an HTML file.

Note: An image file can be specified directly in VIEWER1.DAT (and VIEWER2.DAT) to display in the
browser window, but this is not recommended. An example of the HTML to display an image name
'image.jpg' is simply:
<html>
<body>
<image src="image.jpg">
</body>
</html>

For Silver Theme, use the following table as a guide for maximum image sizes. 'View 1' refers to the
upper browser (advertising) window on the right side of the customer display and 'View 2' refers to the
lower browser window on the right side of the customer display. All screen dimensions are of the form
width x height.
Table 13. Silver theme image sizes (Customer screen browser window)
View 1 View 2
Screen Resolution Defined size Maximum image size Defined size Maximum image size
800x600 395 x 254 375 x 228 395 x 170 375 x 145
1024x768 506 x 325 486 x 300 506 x 218 486 x 193

For Classic Theme, here are the recommended image sizes.

Table 14. Classic theme image sizes
View 1 View 2
Screen Resolution Defined size Maximum image size Defined size Maximum image size
800x600 370 x 330 350 x 305 370 x 152 350 x 127
1024x768 474 x 422 454 x 397 474 x 194 454 x 169

40 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

SI GUI screensaver recommended image sizes

These are the recommendations for the maximum image sizes used for the screen saver of SI GUI
terminals (defined in screenSaver.dat) and the customer GUI (cGUI) (defined in CGUIscreenSaver.dat).

Table 15 applies to Silver Theme and Classic Theme. All screen dimensions are of the form width x
height.
Table 15. Silver theme image sizes (Si GUI screensaver)
GUI Terminal Customer Display
Screen Resolution Maximum image size Maximum image size
800x600 430 x 360 430 x 370
1024x768 430 x 360 430 x 370

Configuring graphics
From the menus, select one of the screen resolutions and one of the color formats that are supported by
your hardware. The SI GUI supports screen resolutions of 800 by 600 pixels or 1024 by 768 pixels. The
supported color formats are 256 or 64 K. The recommended screen resolution is 800 by 600 pixels with a
color format of 64 K.

Select the other device characteristics that are appropriate for your terminal configuration.

Note: On a 4690 controller/terminal, the terminal will use the configured resolution of the controller if
the resolution configured for the terminal does not match the resolution configured for the controller.

Note: SI specify the maximum screens resolution supported in single display mode are 1024 x 768

Note: By changing the following statement into a user defined max resolution of the customer display in
the CustSV.properties file; that will override the SI default setting. For example, by changing the
secondary display to 800 x 600 can be done by adding the following statement in the CustSV.properties
and zipped into svuser.jar. customer.screen.max.resolution=1.

Click Save. Select Terminal Configuration to return to the Terminal Configuration panel.

Selecting load definitions

On the 4690 Terminal Configuration panel, select Load Definitions. Select a load definition to edit or
create a new load definition for the terminals that you are configuring.

For each terminal (or range of terminals) running AEF, select the load definition and click Edit. Make
sure that the following information is entered:

Configuring general settings

Click to highlight the Device Characteristics name setting that is appropriate for the terminal load.

Configuring primary applications

Select Start a primary application.

Enter the following in the Application name field for the application you are using:

GSA:
R::ADX_IPGM:EALTS10L.286

SA:
R::ADX_IPGM:EAMTS10L.286

Chapter 6. Configuring Store Integrator on 4690 OS 41

Configuring SI on 4690 OS

ACE:
R::ADX_IPGM:JSIFTS10.386

Other POS application:

Contact integrator

Normally, the Parameters field would not contain an entry. However, if the ValuePack GUI Customer
Display or SureVision PRPQ (not being upgraded to SI GUI) is in use, then parameters are required (see
Appendix A, “Primary application parameters,” on page 103).

Configuring Java Applications

Note: See “Using OS 4690 Advanced Java Configuration and Bundling Instead of .RSP files for the SI
GUI application.”

Configuring TCP/IP
From the TCP/IP panel:
1. Select Enable TCP/IP.
2. Select either Obtain an IP address from a DHCP server or Specify an IP address.
3. If you select Specify an IP address, provide the following:
v The unique IP Address for this terminal
v A Subnet Mask that matches the value defined in the controller IP configuration (see the
ADX_SDT1:ADXIPxxZ.BAT file where xx is the controller node ID)
v The Host Name for this terminal (for example, TERM### where ### is the terminal number).

Note: The Host Name must be listed in the ADX_SDT1:ADXHSIHF.DAT file, along with the IP
Address. See step 2 in “Configuring TCP/IP” on page 52.

Completing load definitions:

After you enter all load definition entries:
1. Click Save at the bottom of the panel and return to the Terminal Configuration panel.
2. Click the Terminal Configuration link at the top of the panel to return to the 4690 Terminal
Configuration panel.

Configuring user logical file names for terminals

For AEF to work correctly, you must add ADXMAXTH=320 to the C:\ADX_IDT1\ADXTRMUF.DAT file.
You might need to create the ADXTRMUF.DAT file if it does not exist.

Using OS 4690 Advanced Java Configuration and Bundling Instead of

.RSP files for the SI GUI application
Starting with OS 4690 Version 4, you may skip running the TOF.BAT utility when making changes to the
Operating System, the Base Application, or the SIGUI. You are not required to run TOF or TOFLite and
reload the terminals.

This functionality allows you to define bundles of files to be preloaded to the terminal when it is
powered off and back on or reloaded. These bundles contain the files which would normally be included
when running TOF or TOFLite. As part of this functionality, running TOF or TOFlite is completely
eliminated. TOF.BAT creates resource and dependency files (TOFCreate), then creates a legacy preload zip
file for the legacy X: terminal RAM disk (ADXTRM0L) , then finally builds the terminal loadshrink
(ADXRTCCL). There are several advantages to using this functionality. Previously, running TOF (20+
minutes) or TOFLite (5-8 minutes) then reloading the terminals could take 10-30 minutes time. When
implementing the preload bundling functionality, you will be able to fully load a GUI terminal
significantly faster.

42 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

The savings mentioned above are realized through the concept of bundling. When the ADXPLDRB
program is run, it will compare the files in each bundle to the files on the controller. If any of the files in
the bundle changed, then the bundle is rebuilt. If there are no changes, then the bundle is skipped. It is
advantageous to create a bundle with modules that change often and separate bundles with modules that
are changed less frequently.

Instead of running TOF or TOFLite, ADXPLDRB may be run in command mode and terminals manually
reloaded. Also, ADXRTCCL runs appreciably faster and the terminal loadshrink file significantly
decreases in size.

Depending on how you decide to bundle your files, it can take as little as 3 minutes to have the terminals
reloaded. The other advantage in using this feature revolves around full Java2 multiapp support. With
the TOF method, there were still some Java2 classes that were not accessible when offline due to the NFS
connection between the terminal and the controller. This solution eliminates that issue as the Java2 JVM is
also preloaded to the terminal.

When running ADXPLDRB manually to rebuild bundles, run the command "adxpldrb -force
-loadshrink." These options force all bundles to be rebuilt as well as the terminal loadshrink. If your
changes are not apparent upon terminal reload, then you must activate terminal configuration.

ADXPLDRB is run in several situations, manually, during Terminal Configuration Activation, and
following Apply Software Maintenance:
v Whenever ADXPLDRB is launched manually, the log file created is ADX_SPGM:ADXPLDRC.LOG.
v Whenever Terminal Configuration is activated, ADXPLDRB is launched and the log file created is
ADX_SPGM:ADXPLDMN.LOG.
v Whenever OS 4690, Sales application, or Store Integrator maintenance is applied, ADXPLDRB is
launched in background and you may observe the background execution. When ADXPLDRB is
launched by Apply Software Maintenance, the log file created is ADX_SPGM:ADXPLDRS.LOG.

You should examine the respective log file following any of the above situations.

Listed below are the changes required in OS 4690 configuration to successfully use this functionality.
These are the steps used in place of selecting Legacy Java Application (which is where you would define
a specific Store Integrator response file).

For Store Integrator versions prior to Version 3, Release 2, please refer to the Toshiba Global Commerce
Solutions Knowledgebase at www.toshibagcs.com/support which contains information about the process
of using preload bundling for prior Store Integrator releases. Go to Knowledgebase Searches, and in
Point of Sale, search for configuration and bundling.

Starting with Store Integrator Version 3, Release 2, sample files are included on the Store Integrator
Installation CD in application-specific directories in the /4690/GUI directory. An example of this would
be /4690/GUI/ACE. The files found in each application-specific /4690/GUI folder are:
v JAVAAPP.XML
v PRELOAD.XML
v SAVECFG.BAT
v RESTCFG.BAT

The JAVAAPP.XML file contains sample Java applications for the various terminal configurations. Each
character in the application name represents one part of the applications configuration. The list below
describes what each character means.
v POS Application [A|S|G|O] (ACE, SA, GSA or Other)
v Terminal type [T|C] (Standalone Terminal or Controller/terminal)

Chapter 6. Configuring Store Integrator on 4690 OS 43

Configuring SI on 4690 OS

v Display configuration [O|C|D] (Operator, Customer, Dual Display)

v Heap size [S|M] (Small-68M, Medium-96M)
For example, "ATOM" represents an ACE terminal, operator display, and a medium sized heap for use
with the Silver Theme.

OS 4690 Configuration for users with existing preload-style Java applications and
bundles
If you already have ‘preload-style’ java applications defined, or preload bundles defined, then you MUST
export that configuration information, then manually merge it with the Store Integrator samples, and then
import the merged information back into OS 4690 configuration.

To export the existing java application definitions and preload bundles, run the SAVECFG.BAT file on
your OS4690 Master Controller. If you do not have this file, you must first copy it to the controller from
the installation CD /4690/GUI/APP directory (where APP is one of ACE, GSA, or SA.) The
SAVECFG.BAT file creates two files called JAVAAPP.XML and PRELOAD.XML.

Note: The files provide here for the other POS application (OPA directory) are provided as a starting
point for integrators to use to develop exporting application definitions and preload bundles for the
application.

You must then manually merge the contents of the

Store Integrator-supplied files:

/4690/GUI/APP/JAVAAPP.XML (where APP is one of ACE, GSA, SA or OPA)

/4690/GUI/APP/PRELOAD.XML (where APP is one of ACE, GSA, SA or OPA)

with the exported JAVAAPP.XML and PRELOAD.XML.

Note: When working in the exported JAVAAPP.XML and PRELOAD.XML files, do not remove or
rename any existing java applications or preload bundles. Please use 4690 Terminal Configuration
for this purpose because the 4690 Configuration import utilities do not correct the Terminal Load
Definitions. Also, do not remove or rename any existing java applications or preload bundles that
you have created yourself. Ensure that your entries are not modified. If there are duplicates found
between your exported java applications and exported preload bundles, and those supplied by Store
Integrator, this will indicate that you have a previous version of Store Integrator installed.
Duplicates found would be, for example, ATOM java application, or preload bundle COMMON, and
you should use the definitions found on the SI CD in javaapp.xml and preload.xml.

Also note that the file names that should be imported after the merge, should be called javaapp.xml
and preload.xml. The import utility expects these file names when you run RESTCFG.BAT.

Continue to the next section to see how to import the merged java application and preload bundle
definitions.

OS 4690 Configuration for users without existing preload-style Java applications

and bundles or those who have exported or merged
If you do not already have ‘preload-style’ java applications or preload bundles defined, or after
performing the above export and merge, you must import the java applications and preload bundle
definitions.

To import java application definitions and preload bundles, run the RESTCFG.BAT file on your OS4690
Master Controller. If you do not have this file, you must first copy it to the controller from the installation
CD /4690/GUI/APP directory (where APP is one of ACE, GSA, or SA.) The RESTCFG.BAT file requires
two input files, JAVAAPP.XML and PRELOAD.XML.

44 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

Note: The files provide here for the other POS application (OPA directory) are provided as a starting
point for integrators to use to develop importing application definitions and preload bundles for the
application.

If you are importing Store Integrator-supplied definitions for the first time, ensure that you are using the
application-specific sample files for the sales application installed on your system:

/4690/GUI/APP/JAVAAPP.XML (where APP is one of ACE, GSA, SA or OPA)

/4690/GUI/APP/PRELOAD.XML (where APP is one of ACE, GSA, SA or OPA)

If you are importing merged java application definitions and preload bundle definitions after export and
manual merge, the merged information must be provided to the import utility in files named
JAVAAPP.XML and PRELOAD.XML.

The import utility saves the imported java application definitions and preload bundle definitions in the
inactive Terminal Configuration files. Once the import utility has completed, you should verify that the
OS 4690 inactive Terminal Configuration has the definitions for both java applications and preload
bundles as you intend, and then activate Terminal Configuration.

Configuration changes for a standalone terminal:

To change the configuration of a stand-alone terminal, complete the following steps:

Note: On a 4690 standalone terminal you must preload c:\adx_ipgm\silver.jar to the root of the disk
drive on your terminals. The SI GUI dynamically loads silver.jar when needed so do not add silver.jar to
the classpath.
1. Go to device characteristics for the SI GUI terminal:
a. Select the RAM disks option.
b. Select the Q disk only.

Note: There is NO need for a RAM disk X

c. Enter the desired disk size (75 to 100 meg is usually enough).
d. Save changes and exit.
2. Go to Load definitions:
a. Select the terminal you wish to change.
b. Select Java Applications.
c. On this screen, select Enable Java application at start-up.
d. Select the primary application that matches the configuration you are running (customer display,
operator display, or Dual Display).
e. Change the preload drive to be the Q drive.
f. Save changes and exit.
3. Select the JVM preload option from the left hand side of the screen.
a. Make sure you change the JVM preload drive value here to be Q or M.
b. The M drive can be used only if you have a hard drive in the terminal.
c. Choosing Q will cause the JVM to be preloaded to the Enhanced RAM disk instead of the terminal
hard drive.
d. Save changes and exit.
4. Select the Preload Bundles option from the left hand side of the screen.
a. Change the Drive letter to Q.
b. Select the 7 bundles from the left hand side to the right hand side of the screen.
c. Save changes and exit.

Chapter 6. Configuring Store Integrator on 4690 OS 45

Configuring SI on 4690 OS

These seven bundles are:

PRO
SVUSER
One of : (depending upon the installed sales application) ACEJARS,
GSAJARS, or SAJARS
ELITE
4690JARS
AEFJARS
COMMON

Note: Elite should only be chosen if the ICESoft Browser is being used.
5. Activate terminal configuration and reload the terminals.

Note: Whenever a *.JAR file or *.ZIP file or *.PRO file contained in any of your defined preload bundles
is modified by replacing on the system ADXPLDRB must be run in command mode before reloading the
terminals.

Configuration changes for Controller/Terminals:

1. Go to Load definitions.
a. Select the terminal you wish to change.
b. Select Java Applications.
c. On this screen, select Enable Java application at start-up.
d. Select the primary application defined earlier (in this example we choose ACOS).
e. Change the preload drive to be C.
f. Save changes and exit.
2. Select the JVM preload from the left hand side of the screen.
a. Change the JVM preload drive to be M.
b. Save changes and exit.
3. Activate terminal configuration and reload the controller/terminals.

IMPORTANT: After successfully loading your terminals or controller or terminals, you may (optionally)
go change the Java Application Advanced characteristics and remove the entries for Redirected STDERR
and STDOUT. If you do not remove these entries, the STDERR and STDOUT files in the SILOGS
directory will grow forever. You should continue to redirect at least the STDERR file as this is helpful in
problem determination. After any change to STDOUT or STDERR redirection files, Terminal
Configuration Activation would be required.

Using OS 4690 Advanced Java Configuration and Bundling for

AEF-only
For the purpose of configuring and launching AEF only (no SI GUI) in a terminal or controller/terminal,
SI provides a set of sample XML files on the SI CD.

A likely configuration that would use this AEF-only SI application would also run the ACE full screen
application that sends AEF events to SI, but displays the ACE fullscreen application similar to using
ACETSFSL.386. See below for information on configuring this combination in a 4690 terminal or
controller/terminal.

Note: In this configuration there is a known problem in the 4690's Java I/O Processor where key
sequences entered via the keyboard are not echoed to the 2x20 display area of the video display when
running full screen ACE. This will be resolved with APAR IO14903. Contact Toshiba support for more
information.

46 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

The SI install CD has 4 files in the /4690/AEF/ACE folder. These four files are not installed when you
install SI AEF or SI GUI (which includes AEF):
v SAVECFG.BAT -> a sample BAT file that may be used to export active 4690 Java application and
preload bundle definitions
v RESTCFG.BAT -> a sample BAT file that may be used to import AEF-only 4690 Java application and
preload bundle definitions
v JAVAAPP.XML -> application ACEAEF, "SI AEF/Common for ACE" and ACEAEFCT, “SI
AEF/Common for ACE C/T”
v PRELOAD.XML -> terminal preload bundle definitions:
– AEFPRO, “Property Files”
– SIUSER, “User supplied files"
– 4690JARS, “4690JARS”
– AEFJARS, “AEFJARS”
– COMMON, “COMMON”
– POSBC, “POSBC”

Note: If you have any SI GUI (or other java application) preload bundles or java applications
defined in your system , you will need to export these definitions using the SAVECFG.BAT file and
merge yours with the definitions found in JAVAAPP.XML and PRELOAD.XML on the SI CD in the
/4690/aef/ace folder.

When working in the exported JAVAAPP.XML and PRELOAD.XML files, do not remove or rename
any existing java applications or preload bundles. Please use 4690 Terminal Configuration for this
purpose because the 4690 Configuration import utilities do not correct the Terminal Load
Definitions. Also, do not remove or rename any existing java applications or preload bundles that
you have created yourself. Ensure that your entries are not modified. If there are duplicates found
between your exported java applications and exported preload bundles, and those supplied by Store
Integrator, this will indicate that you have a previous version of SI installed. Duplicates found
would be, for example, ACEAEF java application, or preload bundle AEFPRO, and you should use
the definitions found on the SI CD in javaapp.xml and preload.xml.

Also note that the filenames that should be imported after the merge, should be called javaapp.xml
and preload.xml. The import utility expects these file names when you run RESTCFG.BAT.

The SAVECFG.BAT exports the active java application and preload bundle definitions to files javaapp.xml
and preload.xml. Ensure that you run this utility in a different folder than the folder into which you have
copied the javaapp.xml and preload.xml from the CD before merging the two sets of java applications
and preload bundles.

One situation in which you might have pre-existing java application definitions and preload bundles
would be if you had installed SI GUI V3R2. If you had imported the SI V3R2 GUI java applications and
bundles, you would already have the bundles listed below:
v 4690JARS
v AEFJARS
v COMMON

The above bundles are the same for both SI GUI and SI AEF-only.

Bundles AEFPRO, SIUSER, and POSBC are new for this AEF-only configuration as are the ACEAEF and
ACEAEFCT java applications.

Once any existing java applications and preload bundles have been merged into files called javaapp.xml
and preload.xml with the new AEF-only configuration application and bundles, the user would run the

Chapter 6. Configuring Store Integrator on 4690 OS 47

Configuring SI on 4690 OS

RESTCFG.BAT utility to import the definitions into the 4690 Inactive configuration files. If a user does not
have any pre-defined java applications or preload bundles, the user would run the RESTCFG.BAT utility
to import the javaapp.xml and preload.xml contained on the SI CD in the /4690/aef/ace folder.

If you are a new user of SI or an existing SI user who has not imported the SI GUI java applications and
preload bundles into your 4690 configuration, then in order to configure the AEF-only application you
MUST import both the javaapp.xml and preload.xml contents using the RESTCFG.BAT process.

After importing java applications and preload bundles, continue configuration steps.

Configuration Changes for Terminals:

1. Select Terminal Device Characteristics
a. Create (or edit existing) a Device Characteristics group to represent your AEF-only terminal
and/or controller/terminal
b. Select Java Redirection
c. Select “Enable Advanced Java Redirection”
d. Select Advanced Java Redirection
e. Select “ANDISPLAY,” Select “ANDISPLAY2,” Select “ANDISPLAY3,” Select “I/O Processor and
Tone”
f. Save changes and exit Terminal Device Characteristics
2. Select Terminal Load Definitions
a. Select the terminal number you wish to change or define a new terminal number
b. Select General Settings: Select a terminal device characteristics group name which was
created/edited in step 1 above
c. Save changes
3. Select Primary Application
a. For Application name, specify R::ADX_IPGM:JSIFTS10.386
b. For Parameters, specify i1
c. Save changes
4. Select Java Applications
a. Select Java 2 (not java 2 legacy) as your java environment
b. Select ACEAEF as your primary java application
c. Choose Q: for the Preload drive
d. Choose either Q: or M: for the JVM Preload target drive (for M: the terminal must have a hard
drive)
e. For Preload bundles, select the following bundles and add them to the terminal’s Q: Enhanced
RAM disk:
v AEFPRO, “Property Files”
v SIUSER, “User supplied files"
v 4690JARS, “4690JARS”
v AEFJARS, “AEFJARS”
v COMMON, “COMMON”
v POSBC, “POSBC”
f. Save changes and exit
5. Activate terminal configuration and load your AEF-only terminal.

Configuration Changes for Controller/Terminals:

1. Select Terminal Device Characteristics

48 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

a. Create (or edit existing) a Device Characteristics group to represent your AEF-only terminal
and/or controller/terminal
b. Select Java Redirection
c. Select “Enable Advanced Java Redirection”
d. Select Advanced Java Redirection
e. Select “ANDISPLAY,” Select “ANDISPLAY2,” Select “ANDISPLAY3,” Select “I/O Processor and
Tone”
f. Save changes and exit Terminal Device Characteristics
2. Select Terminal Load Definitions
a. Select the terminal number you wish to change or define a new terminal number
b. Select General Settings: Select a terminal device characteristics group name which was
created/edited in step 1 above
c. Save changes
3. 3. Select Primary Application
a. For Application name, specify R::ADX_IPGM:JSIFTS10.386
b. For Parameters, specify i1
c. Save changes
4. Select Java Applications
a. Select Java 2 (not java 2 legacy) as your java environment
b. Select ACEAEFCT as your primary java application
c. Choose C: for the Preload drive
d. Choose M: for the JVM Preload target drive
e. Save changes and exit
5. Activate terminal configuration and reload the AEF-only controller/terminal

IMPORTANT: After successfully loading your terminals or controller/terminals, you may (optionally) go
change the Java Application Advanced characteristics and remove the entries for Redirected STDERR and
STDOUT. If you do not remove these entries, the STDERR and STDOUT files in the SILOGS directory
will grow forever. You should continue to redirect at least the STDERR file as this is helpful in problem
determination. You may choose to change the filename referenced in the entries for Redirected STDERR
and STDOUT as well. After any change to STDOUT or STDERR redirection files, Terminal Configuration
Activation would be required.

Configuring the controller/terminal

The configuration for the terminal side of a controller/terminal is the same as in “Configuring
stand-alone terminals” on page 39, except for the following items:
v JavaTOF is not needed. Do not define a RAM disk in the Device Characteristics to be used by this
Controller/Terminal.
v The response files to be specified as the Java application name in the load definition are different from
those for stand-alone terminals (see “Response files for controller/terminals”). The format is as follows:
@ADX_IPGM:respfile.RSP

where respfile is the name of the response file.

Response files for controller/terminals

To run AEF with the SI GUI on a controller/terminal, the response file also depends on the display mode
of the terminal. Use Table 16 on page 50 to select the appropriate file for your display mode and the level

Chapter 6. Configuring Store Integrator on 4690 OS 49

Configuring SI on 4690 OS

of debugging data. If you are not sure how much debugging data you need, use the file that provides
moderate debugging data for the display mode you are using (OPRCTMID.RSP, CSTCTMID.RSP, or
DDCTMID.RSP).

Note: Using any of the response files, you can obtain additional debugging data by redirecting standard
output to a file (see “Redirecting standard error” on page 94).
Table 16. Response files for starting the SI GUI on a controller/terminal
Response file
Debugging data
Operator display only Customer display only Dual display
Minimal OPERCT.RSP CUSTCT.RSP DDCT.RSP
Moderate (recommended) OPRCTMID.RSP CSTCTMID.RSP DDCTMID.RSP
Maximum OPRCTDBG.RSP CSTCTDBG.RSP DDCTDBG.RSP

System configuration
Click Home at the top of the panel to change to the 4690 Configuration panel. From there, select the
System Configuration link at the left of the panel.

If you are not already in the 4690 Configuration panel, select the following from the System Main Menu:
(4) Installation and Update Aids > (1) Change configuration > (3) System Configuration.

System settings
LAN terminal definition
If a new stand-alone terminal has been defined, then its address must be included by performing the
following steps:
1. Click LAN Terminal Definition in the left panel.
2. From the LAN Terminal Definition, click New.
3. On the New LAN Terminal Definitions, in the Enter the terminal range to define (1-999), input the
new terminal address in the From: space
4. In the Enter controller IDs for this LAN Terminal Definition, input the Primary Controller and
Backup Controller values in their appropriate spaces.
5. Click Submit.

Using the Java configuration

Configuring the time zone
1. From the left panel of the 4690 System Configuration window, select Time Zone under Java
Configuration.
2. Using the menu, select the appropriate system time zone.
3. Save the change.

Modifying the Java classpath

The classpath required by AEF is specified in the response file that you use (for example, OPERMID.RSP
) and not by the Java 2 controller classpath. If you need to modify the classpath (to add your own JAR
files to the application), make a copy of the response file you are using and add your JAR entries to the
classpath in your copy of the response file. Then use your copy of the response file for the Java
Application entry under “Configuring stand-alone terminals” on page 39 or “Configuring the
controller/terminal” on page 49.

50 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

Configuring the controller

Perform the steps in this section for all defined controllers.

Controller Configuration is where you can customize the following settings:

v Video configuration
v NFS data
v DHCP server
v Background applications
v User logical names
v RAM Disks

To access Controller Configuration, from the System Main Menu, select (4) Installation and Update
Aids then (1) Change configuration then (2) Controller Configuration.

Configuring the video for graphics support on the controller

After you open the Controller Configuration menu for a particular controller, place an X next to the
Video Attributes option and press Enter. Enter the following information:
v MONOCHROME SUPPORT ONLY = 2 (NO)
v JAVA GRAPHICS USED = 1 (YES)
v SCREEN RESOLUTION = 2 (800 x 600) (or a resolution that is supported for your hardware)
v PALETTE = 2 (64k colors) (or number of colors that is supported for your hardware)

Note: If this system is a controller/terminal, make sure that the video settings for the controller match
the settings used in the terminal device characteristics (terminal device groups). Unexpected results can
be experienced on the controller/terminal if these settings are not consistent.

Configuring the DHCP server

If the DHCP server is configured, under Global Options, select Router. A router IP address of the format
x.x.x.x must be specified. If you do not have a router on the network, then the IP address of the master
store controller should be used instead as the router IP address.

Configuring background applications

The NFS server and portmapper applications are mandatory for NFS and must be configured for all
controllers. Set these up as background applications.

Note: You must define the Portmapper application first, followed by the NFS Server.

Portmapper Application: ADX_SPGM:ADXHSIPL.286

NFS Application: ADX_SPGM:ADXHSINL.386

Priority: 5

Settings for Master/File Server and Alternate Master/Alternate File Server:

v Start When Master: Y
v Stop When Not Master: N
v Start When Not Master: Y
v Stop When Master: N
v Start When File Server: N

Chapter 6. Configuring Store Integrator on 4690 OS 51

Configuring SI on 4690 OS

v Stop When Not File Server: N

v Start When Not File Server: N
v Stop When File Server: N

Settings for subordinate controller:

v Start at IPL: Y

Defining user logical file names for controllers

The following logical file names must be defined for each controller:

HOSTNAME = cn
where cn is the controller node ID
TERMJAVA = 2
ADXMAXTH = 320
ADXDNS2S = 1

If the logical files are not defined, select (4) Installation and Update Aids -> (1) Change configuration ->
(2) Controller Configuration

Place an X next to User Logical File Names and press Enter. Select (1) Define a Logical File Name and
enter the Logical File Name you are adding. Then set the appropriate value.

Note: If the User Logical File Name already exists, then select (2) to display the existing value and verify
that it is set correctly.

Configuring RAM disks (optional)

Virtual session load time can be improved by the use of a Controller RAM disk.

After you open the Controller Configuration menu for a particular controller, place an X next to the RAM
Disks option and press Enter.
1. Click on Enhanced RAM Disk Q in the left panel.
2. Check Create RAM Disk.
3. For Disk size, enter 30.
4. Click Save, and then Exit.

Configuring TCP/IP
Follow these steps to configure the TCP/IP settings:
1. The 4690 TCP/IP driver is loaded on a controller during initial program load (IPL) if there is a file in
the ADX_SDT1 directory with the name ADXIPcnZ.BAT, where cn is the controller node ID. Make
sure the loopback address is set in the ADX_SDT1:ADXIPcnZ.BAT file. Ensure that the following lines
are included (as shown):
adxhsi2l 256
ifconfig lan0 x.x.x.x netmask y.y.y.y
ifconfig lo0 127.0.0.1
route add default x.x.x.x 1

Note: If you are configuring a 4690 Enhanced mode controller, the following statement:
ifconfig lan0 x.x.x.x netmask y.y.y.y

should be modified as follows:

ifconfig lan0 x.x.x.x netmask y.y.y.y eloopaddr last

52 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

where x.x.x.x is the IP address of the controller and y.y.y.y is the subnet mask.
2. The ADX_SDT1:ADXHSIHF.DAT file is used to correlate a host name to an IP address. In this file
there must be entries for localhost, for each controller, and for terminal host names. If DHCP is being
used, the terminal entries will be updated automatically by the DHCP server. Otherwise, the terminal
names and address entries must be updated manually to insure that the AEF log files have the correct
names. The local host address must be set to the loopback address (127.0.0.1). This file must contain
the correct addresses for your system. An example hosts file is:
127.0.0.1 localhost
10.1.1.2 cc
10.1.1.3 dd
10.1.1.4 term270
3. Make sure that each of the controller user logical file names HOSTNAME are included in this file (for
example, CC) and set to the IP address for that individual controller. Also include any of the
HostName and IP addresses of any terminals configured to use a specific IP address. See “Defining
user logical file names for controllers” on page 52 and “Configuring TCP/IP” on page 42.

Systems with multiple network cards

If your system has multiple network interface cards (NICs), you must make the following modifications
to the files listed here (where x.x.x.x is the IP address of the NIC that connects the system to the Store
Integration network):
1. In the AEFVIRT.TXT file, insert –Djava.rmi.server.hostname=x.x.x.x immediately after
JAVA2BIN:java.386.
2. Verify that ADXIPcnZ.BAT contains the following line:

route add default x.x.x.x 1

where cn is the controller node ID.

Export file
Verify that m:\ is listed on a separate line in the export file
C:\ADX_SDT1\ADXHSIXF.DAT.

The file should contain the following lines:

c:\
m:\

Configuring SSL
For the list of SSL Properties files and their descriptions, see Table 22 on page 75.

Configuring JavaPOS
AEF uses JavaPOS (JPOS) to control devices connected to the terminal. The devices are automatically
configured and there is no need for manual JPOS configuration.

Configuring Activate
Activate the configuration for the terminal, controller and system. When all of the activations have
completed, reboot all the controllers in the network, and then reload all the terminals.

Java terminal offline configuration

For a complete explanation of the Java Terminal Offline (JavaTOF) OS feature and the parts of the PRO
file, see the 4690 OS Programming Guide,. If you are using the SI GUI, see the Toshiba 4690 Store Integrator
Graphical User Interface Programming Guide for more information about running the SI GUI under JavaTOF.

Chapter 6. Configuring Store Integrator on 4690 OS 53

Configuring SI on 4690 OS

Note: The steps in this section are required only if you are not “Using OS 4690 Advanced Java
Configuration and Bundling Instead of .RSP files for the SI GUI application” on page 42.

Configuring Logging
The AEF installation process creates the C:\SILOGS directory. You must verify that this directory exists
on all controllers in your environment.

To create this directory on a controller, enter the following command:

MKDIR C:\SILOGS

Migrating from SureVision or reinstalling the SI GUI

This section describes how to migrate from SureVision.

Attention: If you have customized any of the following files, create backup copies, because if you are
migrating from SureVision or reinstalling the SI GUI, these files will be overwritten:
c:\adx_ipgm\svuser.jar
c:\adx_ipgm\svbusp.jar
c:\adx_ipgm\svibm.jar
c:\adx_ipgm\svstore.jar
c:\adx_ipgm\svcomp.jar
c:\adx_ipgm\siuser.jar
c:\adx_ipgm\sibusp.jar
c:\adx_ipgm\siibm.jar
c:\adx_ipgm\sistore.jar
c:\adx_ipgm\svproduc.jar
c:\adx_ipgm\j.pro
c:\adx_ipgm\jcst1.pro
c:\adx_ipgm\jcst2.pro
c:\adx_ipgm\sureview.duj
c:\adx_ipgm\sureview.dux
c:\adx_ipgm\sureview.rci
c:\adx_ipgm\sureview.pro

Note:
1. If user modifications were made to any other *.PRO or *.RSP files, make sure those changes are
reintegrated into the new files after the maintenance is applied. For a list of *.PRO files that are
merged during the install, see “Migrating to SI V3 and above” on page 55. These files do not need to
be backed up to prevent being overridden if migrating to SI V3 or above.
2. Your changes will be lost unless you created backups, except for the files that are merged in SI V3 or
above.

Migrating from previous SureVision systems

Background images are now used in the default XML screen files. If you have your own background
images in custom XML panels, you must apply the changes to the new XML. You might also need to
move custom rectangles to fit the new background images.

If you customized the customer screen XML for dual display, the XML must have an additional attribute
of secondaryGUI=true set for the DisplayScreenAction and the line-display XML elements.

Migrating from SI V1 to SI V2 and above

The sample AEF/CSS configuration file, adxae00f.dat, contains new properties. Add these properties to
your adxaeXXf.dat configuration files, where XX is your controller ID.
v threadpool.max.threads=100
v threadpool.thread.timeout=3600000

54 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

v threadpool.initial.threads=30

These values (listed previously) are the default values. See “Enabling CSS” on page 61 for a description
of these fields.

Along with the needed changes above, if migrating to a version above SI V2, please read the following
section(s) for the other important update information.

Migrating to SI V3 and above

Merging Property Files
In the SI V3 release, several files are now being merged during the installation process. These files are
being merged to remove the need to create backups of important files that would need merging into the
new versions and to remove the need to insert new properties into existing property files that do not get
overridden during the installation process. The files that are now being merged are:
c:\adx_ipgm\j.pro
c:\adx_ipgm\aefload.pro
c:\adx_ipgm\sminlogs.pro
c:\adx_ipgm\smidlogs.pro
c:\adx_ipgm\smaxlogs.pro
c:\adx_ipgm\svlog.pro
c:\adx_ipgm\svlogmid.pro
c:\adx_ipgm\svlogdbg.pro
c:\adx_ipgm\sureview.pro
c:\adx_ipgm\dd.pro
c:\adx_ipgm\SVCGUI.PRO
c:\adx_ipgm\cust.pro
c:\adx_ipgm\oper.pro
c:\adx_ipgm\jcst1.pro
c:\adx_ipgm\jcst2.pro

During the merge process, user comments will not be preserved unless they are marked as being user
comments. To flag a comment as a user comment that must not be removed during the merge, start the
comment using the start flag #user_start and end the comment using the end flag #user_end. See the
following example:
#user_start
# Here is where the user comment text goes
# The comment can be multiple lines
#user_end

Also during the merge process, if the file contains a key whose value does not match the latest published
value, the merge process will put in the new key/value pair as a comment above the active key/value
pair. The comment will concatenate the date and time to the end of the key. This is done so the controller
administrator can check to see what the previous default value was and when the file was last merged.
The following is an example of when the merge process modifies a value and comments in the latest
key/value pair:
#sockets_032608_1032=100
sockets=140

If the current value is different than the new value, but is equal to what the previous default value was,
the new value will be inserted. If the values match, no changes will be made and no commented out
key/value pair will be inserted.

Property File Keys

Some property file keys have changed and any extensions of the AEF that overrides the old keys must be
updated to use the new keys. If this does not occur, the AEF will no longer invoke the extensions. The
following table outlines which keys were changed and their new values.

Chapter 6. Configuring Store Integrator on 4690 OS 55

Configuring SI on 4690 OS

Table 17. Property file keys

Classes Properties Bundle New Key Value
NoSalePriceVerify PriceVerify

Migrating to SI V3R2 and above

When migrating to SI V3R2 on Microsoft Windows Clients, you must install Toshiba JavaPOS level 1.13 at
the same time. This is because SI V3R2 requires the IBM Java 1.6 JVM, which is included with Toshiba
JavaPOS 1.13. Versions of SI prior to SI V3R2 do not support the IBM Java 1.6 JVM, therefore you cannot
install Toshiba JavaPOS 1.13 before migrating to SI V3R2.

SI GUI Traction Changes

Beginning with SI GUI V3R2, all tractions are now loaded and stored internally in the order in which
they were read from the XML files. In previous versions of the SI GUI, the tractions once loaded were not
guaranteed to fire in the order in which they were defined. This potentially could cause issues with
tractions that were expecting certain tractions to fire before itself. To aid developers with the move to SI
V3R2 or newer from older versions of SI GUI, a new tool is being supplied on the installation CD to help
flag any tractions that have changed in the order they are going to fire in.

This tool is provided as-is and is located on the installation CD under the \tools\gui\sitoad directory.
This directory contains the SI TOAD Tool and a SITOAD.DOC file explaining how to setup and use the
SI TOAD Tool. Once an analysis has been performed on the current lab version of SI GUI and on the new
version of SI GUI once the lab has been upgraded, it is up to the developers to analyze the data to
determine if any tractions need to be moved around inside of the customer extension files. The SI TOAD
Tool will flag tractions that need to be visually analyzed by the developers. The tool will show which
tractions now fire in a different order when ran under the new SI GUI version. The developer must
determine if the traction firing in the new order will cause any problems.

When visually analyzing the tractions, it is good to keep a few things in mind. First, is there any SI POS
data being set by other tractions firing off of the same trigger values that is needed by the current
traction when the current traction performs its actions. If the data is manipulated by another traction
needed for the current traction, the order needs to be modified so the current traction fires last.

Another thing to check for when analyzing the tractions is whether the current traction fires any basic
input actions that require all screen changes to have been made, especially by a different traction. If a
different traction sets up the screen's visual components and brings forth a special input field for the user
to input text into, it is important for the current traction to fire its basic input actions.

Migrating to SI V3R3 and above

For instructions for enabling the silver theme after migrating to SI V3R3, see “Store Integrator GUI” on
page 3.

For migrating extensions from the Sureview Theme to the Silver Theme in SI V3R3 see the information
about migrating SI GUI to the silver theme in the Store Integrator Graphical User Interface Programming
Guide (G362-0563).

Java TOF is deprecated as of SI V3R3 in favor of preload bundling.

Migrating to SI V3R4 and above

Starting with SI V3R4, the default install location on a clean install is C:\Program Files\Toshiba, not
C:\Program Files\IBM .

56 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

The ICEBrowser will be not be supported starting in 2013. If support is desired migrating to the HTML
Editor Kit browser, HEKBrowser will be required. See the Store Integrator Graphical User Interface
Programming Guide, in the chapter describing screen components, for more information.

POSBC POS Receipt events now contain all receipt lines that occur between the post print receipt lines
and the trailer receipt lines. Your POSBC clients may see more data at the end of the transaction than in
previous versions of SI.

Migrating to SI V3R5 and above

When using the touch receipt on with SI V3R5 and ACE V7R5, the SI GUI automatically uses a new
voiding mechanism when modifying items if you have enabled the touch receipt void reason code in
ACE. You may see fewer guidance messages on item modifications.

On ACE, when using the touch receipt to apply a rain check to an item sold by quantity, the SI GUI will
ask the operator to enter the number of items to sell at the rain check price. The operator can enter any
number between 1 and the current quantity. There is no way to disable this behavior, however, the SI
GUI pre-populates the input field with the current quantity so that the operator can apply the rain check
price to all of the items by just hitting Enter on the keypad. The SI GUI also highlights the input field so
the operator can enter a new quantity without first hitting the Clear button on the keypad.

SI V3R5 introduces a new capability to the Client Session Server where the classes properties bundle is
loaded with support for session roles. The session roles apply to all modules except the following
modules that have no affiliation with an individual session:
v AEFBase
v AEFMulticastThread
v AEFSessionFactory
v AEFSessionFactoryInfo
v AEFSessionPool
v LoadBalancer
v SessionServer

When installing or migrating to SI V3R5 and above from WEPOS or POSReady 2009, a new environment
variable, %SI_APP_DATA% is created.

For new installations on WEPOS or POSReady 2009, the value of %SI_APP_DATA% is c:\documents and
settings\all users\application data\toshiba\storeintegrator location.

For migrations to SI V3R5 and above, the value of %SI_APP_DATA% is the same as found in
%SI_HOME%.

For new WEPOS or POSReady 2009 installations, the folders found in the %SI_APP_DATA% location,
that were formerly found in the %SI_HOME% location, are:
v security
v silogs
v temp
v user

Install and uninstall

The following sections decribe new installs and administrator privileges.

New installs:
To respect the enhanced file and folder restrictions of Microsoft Windows 7/POSReady 7 and later, we
have moved the location of Store Integrator's temporary files, log files, and user files to a new location.

Chapter 6. Configuring Store Integrator on 4690 OS 57

Configuring SI on 4690 OS

For new installs on Windows, by default we will install the program code into c:\Program
Files\Toshiba\StoreIntegrator and the program data to c:\ProgramData\Toshiba\StoreIntegrator. You
can change the program code location as you have in the past, but we will always install the program
data in c:\ProgramData\Toshiba\StoreIntegrator. Migrations will continue to install both the program
code and data to the location selected during the initial installation.

Adminstrator privileges:
All recent Microsoft Windows operating systems, including Windows 7 and POSReady 7, require
administrator privileges to successfully install and uninstall programs. If you attempt to install or
uninstall SI without administrator privileges, you may leave the product partially installed since we are
not able to modify the Windows registry.

Cancelling the installation

If a previously installed version of this software has been accepted, it cannot be cancelled. If installed
components are in maintenance mode or backup mode, you can cancel the current installed version. Each
component must be cancelled individually. Cancelling the installation will return the previous version of the
application software that was accepted and run. For additional details concerning ASM, see the 4690 OS
User's Guide (SC30-4048).

To cancel Store Integrator installation, perform these steps:

1. Under ASM, cancel all of the installed components: AEF, Common, and the GUI (if selected).
2. If a previous version of SureVision was installed, copy
C:\ADX_IPGM\ADXCBTBD.DAT

to
C:\ADX_IBUL\
3. If no previous version of AEF was applied, some installed files are not removed. Delete the following
files manually:
C:\ADX_IPGM\ADXCBTCD.DAT
C:\ADX_IPGM\ADXCATUD.DAT
4. If no previous version of the SI GUI was applied and you are removing the SI GUI from your system,
you must delete the following file manually:
C:\ADX_IPGM\ADXCBTBD.DAT
5. If you are removing Store Integrator from your system, you must delete any files in the following
directories before you manually remove the directories:
C:\SILOGS
C:\SILIC\LICENSE
6. Delete any files related to Store Integrator that you created.

Installing ICEbrowser
Before installing the SI GUI, verify that all of the ICEbrowser JAR files exist in the appropriate directories.
The response files used by the SI GUI (such as OPERCT.RSP) are designed to work with the ICEbrowser
JAR files to be installed in the C:\ELITE directory. If your JAR files are not in the C:\ELITE\ directory,
then you must modify the response file so that the classpath points to the correct directory.

For information concerning how to obtain and install ICEbrowser for use with SI GUI or Remote GUI,
see the Toshiba Global Commerce Solutions retail industry Knowledgebase at
www.toshibacommerce.com/support. In the Knowledgebase Search section, search for ICEsoft.

ICESoft is ending support for the ICEBrowser in 2013. See “Migrating to SI V3R4 and above” on page 56
for more information.

58 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

SI GUI unique actions

Actions that are unique to the SI GUI are described in this section.

Optional files
The Store Integrator CD includes optional files for your POS application (GSA, SA or ACE). Table 18
indicates where you can find these files.
Table 18. SI GUI optional files
Application Location Description
GSA P:\4690\GUI\GSA Sample files for operator and customer displays
SA P:\4690\GUI\SA Produce images and sample files for operator and customer displays
ACE P:\4690\GUI\ACE
OPA P:\4690\GUI\OPA Produce images and sample files for operator and customer displays to be
used as a starting point for integration with other POS applications.

Note: To use any of these optional files, you must manually distribute them to all controllers in your
environment.

For further information regarding the optional files available for use with the GSA, SA, and ACE
applications, see the 4690 Store Integrator Graphical User Interface Programming Guide (GC30-4121). You can
find names and descriptions of the optional files, along with instructions for using them. In some cases,
these sample files illustrate the process of adding or overriding XML elements.

Overriding SI GUI screen elements

For more information on how to override screen elements, see the “Changing the Store Integrator User
Interface” and “Modifying XML” sections of the 4690 Store Integrator Graphical User Interface Programming
Guide (GC30-4121).

Using the POS application for the SI GUI

This section describes the POS application usage for the SI GUI.

Note: Contact the integrator for information on other POS application usage with the SI GUI.

Using ACE
To display scale weights on the operator display when weighing an item, you must copy two trigger
actions contained in the satrigs.xml file to your custom XML file (company.xml, user.xml, and so on).
These trigger actions are sa_show_scale_weight and expecting_weight. For more information about
trigger actions, see the 4690 Store Integrator Graphical User Interface Programming Guide (GC30-4121).

Pressing tender buttons (such as Cash) repeatedly in rapid succession before the GUI has a chance to
refresh can cause the terminal to “double-tender.” To prevent this, go to ACE Personalization under
Security/Tendering and set the Allow Tender Cashing In A Sales Transaction option to NO.

The SAMPLE.xml file includes an example button for WIC EBT tender. To use the button (for customers
that use that tender), paste the XML for the button with ID WICEBT into the appropriate page in the
customer's TenderActions notebook. The default type and variety for the WIC EBT tender is 61. To use a
different type and variety for WIC EBT, modify the XML for the WIC EBT button as follows:
v Locate the following line:
1[78][96]

This is the key sequence for selecting a WIC EBT tender. The [96] indicates the tender type and the 1
indicates the variety. If the actual type and variety for WIC EBT is 46, change the line to this:

Chapter 6. Configuring Store Integrator on 4690 OS 59

Configuring SI on 4690 OS

6[78][94]
v Locate the following line:
96

The 96 indicates the function code sent to ACE to confirm the selection of WIC EBT tender. If the
actual WIC EBT tender type is 4, change 96 to 94.

By default, ACE can display a produce drill-down panel with produce images. The Produce button is
shown on the Item Entry panel and requires that SVPRODUC.JAR exist in C:\ADX_IPGM. To remove the
produce drill-down panel, remove the SVPRODUC.JAR file from the classpath, or remove the file from
C:\ADX_IPGM. If the produce drill-down panel is removed, then the Produce button must be removed
from the Item Entry panel in XML.

For more information, see the 4690 Store Integrator Graphical User Interface Programming Guide (GC30-4121).

Using GSA
In the initial release of AEF, if you are running a terminal sales program with the GSA Terminal Offline
Feature in a CSS virtual session, there is a processing delay when the offline Item Record File is being
loaded into simulated RAM storage. For information regarding the circumvention of this delay, see the
Store Integrator Programming Guide (SC30-4084).

The POSAutomationProvider does not support tender for CSS sessions other than charge.

Neither SI GUI nor Remote GUI supports the multiple currency feature. The SI GUI and the Remote GUI
have limited support of GSA transaction types. Neither support layaway transactions or cash on delivery
(COD) transactions.

When performing cash counts in GSA, you must use either the touch interface or the POS Keyboard, but
not both during the same transaction. After you use the POS keyboard, the summary panel for each
tender type is intentionally removed.

The tender buttons in the SI GUI are arranged such that the frequently used tenders appear before the
less frequently used tenders. The tender order in GSA should be changed to match the tender order that
appears on the SI GUI. The GSA tender order can be changed through Application Personalization in the
Balance Due/Tender options.

Tax Code configuration: By default, all No Tax codes end with the digit 2 (12, 22, 32, and so on). All
Manual Tax codes end with 1, and all regular tax plans tax codes are numbered from 01 to 09. These
rules must be followed for the tax codes to be displayed on the default GSA panels. However, GSA
personalization enables you to override the tax codes for the GSA panels.

Using SA
The SA TOF, EM PRPQ, Value Pack 2001, and EFT Enhanced features have also been tested with AEF.

The POSAutomationProvider does not support tender for CSS sessions other than charge and EFT.

If you are running a terminal sales program in AEF with the SA Terminal Offline Feature in a CSS virtual
session, a processing delay can occur when the offline Item Record File is being loaded into simulated
RAM storage. For information regarding the circumvention of this delay, see the “Requirements for User
Exits, Extensions, and Source Modifications” section of the Store Integrator Programming Guide (SC30-4084).

The weights and measure on the scale display of the operator terminal is certified. If you wish to not use
it as a primary scale display, you can instead enable a palette that displays the scale weight value to the
operator when an item requiring weight has been entered and the item is placed on the scale. This allows
the operator to view the weight and press Yes or No to accept or reject the weight. To enable this feature,
edit ADX_IPGM:J.PRO and change the text EnableScale=true to EnableScale=true.

60 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

By default, SA can display a produce drill-down panel with produce images. The Produce button is
shown on the Item Entry panel and requires that the SVPRODUC.JAR exist in C:\ADX_IPGM. To remove
the produce drill-down panel, remove the SVPRODUC.JAR file from the classpath, or remove the file
from C:\ADX_IPGM. If the produce drill-down panel is removed, then the Produce button should be
removed from the Item Entry panel in XML.

For more information, see the 4690 Store Integrator Graphical User Interface Programming Guide (GC30-4121).

Automatic till exchange:

Following the error B085 TILL EXCHANGE REQUIRED, a till exchange is automatically performed.

Configuring CSS
The following sections tell you how to enable CSS and how to specify the CSS command.

Running CSS under Java6

Release V3R5 of SI introduces the option to run CSS under Java6 on enhanced 4690 controllers. AEF is
now installed in C:/ADX_IPGM and on the f: drive in the /si directory. The benefits of running CSS
under Java6 are improved performance and an increase in the number of sessions active at one time.
Partial failover is supported when running under Java6, but full failover support is not available.

Enabling CSS
The following steps enable CSS, and initiate it during IPL:
1. Copy the template file ADX_IPGM\ADXAE00F.DAT to ADX_IPGM\ADXAEcnF.DAT, where cn is
the controller node ID.
2. Set the distribution type for the new file to 5 (Compound file, distribute at close).
3. Set the css.enabled property to true (css.enabled=true).

Note: To enable CSS under Java6, set property css.launchFile to the name of a file which contains
the command line for running under Java6 (css.launchFile=aefvirt.j6). CSS is started and stopped
the same way as if it is running under Java 1.4.2 or Java6. It is highly-recommended that you change
the location of stderr and stdout with property: css.std???=f:/si/logs/virt*. All logs will be
located in directory f:/si/logs.
4. Set the css.executeOnIPL property to true (css.executeOnIPL=true).
5. Set the virtual terminal numbers per your assigned terminal numbers to: css.terminals=200-219.
Terminals can also be listed individually: css.terminals=200,202,205,... or as a mixture of ranges
and individual numbers: css.terminals=200,202-205,207....

Note: The virtual terminal numbers must be unique. They cannot duplicate real terminal numbers or
virtual terminal numbers from other controllers.
6. Set the css.reserved.terminals property to reserve specific terminals (css.reserved.terminals=200-
204). Terminals for which a session number has to be reserved (as opposed to using any available
session) are those designated for operation with Remote Device Support or the Remote GUI. As
shown in step 5, terminals can be listed individually.

Note:
a. The reserved terminal numbers specified must be included among those listed in step 5.
Otherwise, a warning message is written to the AEF log and the offending terminal numbers are
ignored.
b. The required range for session numbers is from 1 to 999.
7. Set the initial CSS session pool size css.initial.pool.size=initsess, where initsess is the initial
number of sessions that are automatically created when CSS starts.

Chapter 6. Configuring Store Integrator on 4690 OS 61

Configuring SI on 4690 OS

Note: This procedure enables CSS only. The actual session creation is controlled by AEF and the
configuration bundle files.
8. Set the maximum number of threads that will be created for use by CSS and dependent applications
threadpool.max.threads=100.
9. Set the length of time (in milliseconds) that a threadpool thread can be inactive before it is removed
from the pool of available threads and destroyed threadpool.thread.timeout=3600000.
10. Set the number of threads to be created on startup of CSS: threadpool.initial.threads=30.

Starting CSS
The file AEFLOAD.PRO is used to configure AEF and controller RAM disk enablement. If CSS is
configured to run under Java6, there is an additional property for the logging config file.

Table 19 describes the properties.

Table 19. Properties of AEFLOAD.PRO
Property Description
aef.logger This property selects which logger file is to be used, sminlogs.pro, smidlogs.pro,
or smaxlogs.pro for minimal logging, moderate logging or maximum logging, in
that order. For moderate logging, smidlogs.pro, is the recommended default.
aef.enhanced.logger This property is used when running CSS under Java6. The property selects which
logger file is to be used, sminlogs.pro, smidlogs.pro, or smaxlogs.pro for
minimal logging, moderate logging or maximum logging in that order. For
moderate logging,smidlogs.pro is the recommended default.
ramDisk.enable To speed up the loading time for virtual sessions, a controller RAM disk can be
used to store JAR files that are only used during initialization. The default value
of this property is true. However, if the system does not contain a defined
controller RAM disk, the normal loading process is followed.
Note: All of the following properties are ignored if ramDisk.enable is false.
ramDisk.drive Sets the disk drive assignment for the controller RAM disk. Only the Q: drive is
supported.
ramDisk.filex Files to be loaded into the controller RAM disk where x is a distinct, but not
necessarily a sequential number. Files maintain the same directory structure in the
RAM disk. If the directories do not exist in the RAM disk, they are created, such
as ramDisk.file1 = ADX_IPGM:aef.jar If the file does not exist, a message is
logged in virtout.xx and the system continues without modifying the classpath
for the missing file. There is no limit to the number of files that can be moved to
the RAM disk as long as the RAM disk is configured to a correct size. The RAM
disk loader always looks at the first 50 entries, and then scales back to 10 entry
increments. As long as it continues to find file entries, it looks for 10 more.
ramDisk.loadx This property defines extra files that you want the loader to place into RAM disk.
None of these files will modify the generated classpath. Resources, images, and
other user files can be placed here. Only user programs or extensions will have
access to the loaded files.
ramDisk.verifyx The files defined with this property must be placed in the RAM disk before AEF
can launch. If these files cannot be located, the system will cancel the operation
and exit. The defined RAM disk drive letter will be prepended to the “verify” files
before the file search begins. CSS cancels the operation after the verify timeout
(the default is 60 seconds) if the files are not found. Error messages for the files
that are not located will be written to the virterr.xx file.

62 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

Table 19. Properties of AEFLOAD.PRO (continued)

Property Description
verify Timeout This is the maximum time (in seconds) that CSS will wait for verification files
(specified through ramDisk.verifyx) to be loaded or available. If the files are not
present by the end of the timeout, CSS will cancel teh operation and a list of the
missing files will be displayed in virterr.xx status files. All missing files must be
found in this time period; this is not a per file delay. The default value is 60
seconds.
ramDisk.verbose This property controls the controller RAM disk classloader log output level to
virterr and virtout. The default value is false. If true, the classpath and class
loader information are logged to show the location of each loaded file.
ramDisk.veryVerbose When this property is set to true, the log displays all loads of classes into the
ClassLoader. It is used primarily for debugging; the default value is false.
ramDisk.disableClassLoader If true, the classpath is not substituted with any files that were defined with the
ramDisk.filex properties. Those files will still be loaded to the RAM disk; but if
they are to be used, the classpath must be manually updated. The default value is
false.

Managing CSS
The ADXCSS1L command can be used to control and monitor the CSS virtual session JVM.

Options are as follows:

start Starts the CSS JVM (fails if already running).
restart Stops and restarts the CSS JVM.
stop Stops the CSS JVM
stat Shows status of CSS JVM.
poll Periodically shows status of CSS JVM.
help Shows the adxcss1l options.

Note: See the comments provided in the ADX_IPGM:ADXAE00F.DAT file when changing configuration
options. Certain changes to the CSS configuration might require a controller reboot, instead of just
restarting CSS.

Configuring CSS running under Java6

The following steps must be followed for any user extension jars, modified properties files including
failover, and logging configuration files when running CSS under Java6. These steps outline a procedure
to get these files put on the f: drive. The files must be put in a zip file named CSSJ6PAT.ZIP.
1. Create zip file CSSJ6PAT.ZIP with the jar command (i.e., java2sdk:jar). CSSJ6PAT.ZIP must be created
in ADX_IPGM:.
2. Set the distribution parameter on CSSJ6PAT.ZIP (adxcsu0l 3 5 CSSJ6PAT.ZIP). It is a good habit to
always set the distribution property on this file because it is required in a multi-controller
environment.
3. Use utility CSSJ6PAT.BAT to apply the files to thef: drive (the utility stops CSS, extracts the zip to the
f: drive, and then starts CSS).

Note: In a multi-controller environment, the command must be run on each controller.

Upgrading the level of Store Integrator (SI) through ASM will re-extract the contents of the zip file (if it
still exists) on the reboot, which will preserve all user extensions through the upgrade.

Chapter 6. Configuring Store Integrator on 4690 OS 63

Configuring SI on 4690 OS

Important notes:
1. The master copy of any files in the SI install should be in C:/ADX_IPGM to help ensure that the exact
same configuration will be run under Java 1.4.2 or Java6 and on all controllers in a multi-controller
environment.
2. The "case" of the file names in the zip file must match the classpath in the aefvirt launch file.
Typically, this will be in lower case.

Configuring failover
This section describes the failover configuration. Failover is only supported for users of the SurePOS
Application Client/Server (ACE) or Supermarket Application (SA). ACE supports both full and partial
failover. SA supports full failover only.

Note: Full failover is not supported for CSS sessions running in the 1.6 JVM.

The failover.properties file

Configuring a system with failover capability requires setting up primary and backup sessions on each
controller. A primary session is one that will be served by a given controller. A session server searches the
primary session first for the use of a session. A backup session is one that will be served by another
defined controller in the event of the unavailability of the primary controller.

The following example of a userfailover.properties file, illustrates the entries that are used to specify
primary and backup sessions:

failover.enabled.controllers=CC,DD
CC.primary.sessions=300-310
DD.primary.sessions=400-410,420
CC.backup.sessions=400-410,420
DD.backup.sessions=300-310

Figure 13. Example of userfailover.properties file entries

In Figure 13, CC and DD are configured to back up each other. CC serves primary sessions 300 to 310,
and DD serves primary sessions 400 to 410 and 420. In the event of a failure of DD, CC would then
provide backup for sessions 400 to 410 and 420. If CC fails then, conversely, DD will provide backup for
sessions 300-310.

Note: If a session is being used on the primary controller that is not failover-enabled, and the primary
controller goes down, an error will be logged for that session on the backup controller. Figure 14 is an
example of the message for a non-failover-enabled session 626:

SEVERE: :sessionID=626: Terminal Number 626 is not valid.

Start:

Message: Unable to locate the factory for terminal number 626.

Error Code: INVALID_TERMINAL_NUMBER
Extended Error Code: NONE

Figure 14. Message of non-failover enabled session

Note:
1. After a failover occurs, the available recovered session running on the backup controller might be in a
"Terminal Secured" state. On the client's next request to the session, it might receive an
Inconsistent_State_Error. In this case, POSBC is working as designed. When POSBC receives a
RemoteException due to a remote method call not returning, it will go into an
INCONSISTENT_STATE. When this happens, the client must send an Initialize (recovery=false)
to return from this state. The POSBC client will then have to replay the transaction that was in
progress.

64 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

2. After a failover occurs, a successful initialization is required to trigger session switchback to the
original controller. If you receive an exception from an initialize request when you trigger a
switchback after failover, send a second initialize request.

The optional property, partial.failover.terminals denotes a list of terminals with partial failover
support instead of the full failover support (which is the default). Full failover support provides the client
with transaction integrity and terminal number integrity. Partial failover support provides terminal
number integrity, therefore clients using partial failover are responsible for replaying any transaction that
is in progress when a controller fails over.

Continuing the example in Figure 13 on page 64, you can specify that sessions 300 to 302, 405 to 408, and
420 be partial failover sessions.

partial.failover.terminals=300-302,405-408,420

Figure 15. Example of partial failover sessions

Note: The failover functionality assumes that the failover.properties file will maintain a consistent set of
primary and backup controllers for any particular session between runs. If a change is made to any of the
failover.property entries for either the primary or the backup controller for a given terminal number, the
system will be unable to process the information. When changing the primary and backup session
assignments, the associated ownership files on both the server and client need to be deleted.
v On the server (4690) side, these are the C:\CSS\OSTMP[terminal number] files.
v The ownership files on the client machine will be %SI_HOME%\user\RCMDATA.[terminal number].

Configuration of persistence files:

You can configure the location of the persistence file properties that are used in failover. The following
example shows the default location values for these properties contained in the failover properties
bundle:
# Base Persistence Files
# Each entry is defined by following each File Key with a ’.local’ entry, and
# a ’.remote’ entry. The value of each will be the fully qualified file
# location on each controller. Each instance of {TERM} will be replaced with
# the value of the terminal number which the persistence file is for, and each
# instance of {NODEID} will be replaced with the controller NodeID of the local
# or remote controller, respectively. The NodeIDs are derived in the following
# way:
# local - AEFUtil.getNodeID()
# remote - FailoverConfig.getRemoteController(terminalNumber)

NVRAM.local=C:/CSS/NVRAM{TERM}
NVRAM.remote=adxlx{NODEID}n::/CSS/NVRAM{TERM}

OwnershipStamp.local=C:/CSS/OSTMP{TERM}
OwnershipStamp.remote=adxlx{NODEID}n::/CSS/OSTMP{TERM}

The following persistence file property is specific to your POS application. The properties shown in the
following example are the defaults contained in the ACE appfailover.properties file.
# The ACE TotalsSave file EAMTSxxx’
TotalsSave.local=C:/EAMTS{TERM}
TotalsSave.remote=adxlx{NODEID}n::/EAMTS{TERM}

Configuring ADXAEnnF.DAT for Failover:

In addition to specifying which sessions will be configured for failover with their primary and backup
controllers, the session numbers must also be configured on both the primary and backup controllers in
their ADXAEnnF.DAT files and specified as reserved terminals.

For Figure 13 on page 64, each controller would contain:

Chapter 6. Configuring Store Integrator on 4690 OS 65

Configuring SI on 4690 OS

css.terminals=300-310,400-410,420
css.reserved.terminals=300-310,400-410,420

Note: For non-failover terminal configurations, configuring the same CSS terminal number on multiple
controllers will produce an error message, an example of which follows. The only case where configuring
the same terminal number on multiple controllers is acceptable is when those duplicate terminal numbers
are also specified for failover in the failover properties bundle:

This CSS instance is configured with terminal numbers

already in use by another CSS instance.
Check ADXAExxF.DAT files for conflicting terminal numbers.
Conflicting factories: [FactoryID1] and [FactoryID2]

Figure 16. Error messages

Initializing a backup session:

When a controller fails and primary sessions are failed over to a backup controller, the backup sessions
are initialized to be able to recover transactions and provide support. To speed up the initialization time
for the backup sessions, a controller RAM disk can be used to store files, which will improve
initialization load time. For instructions on setting up a controller RAM disk, refer to “Configuring RAM
disks (optional)” on page 52. Further information on the use of the controller RAM disk is located in
“Starting CSS” on page 62.

Note:
1. In an ACE environment, application files can also be placed on the controller RAM disk to further
assist in the virtual session initialization. Refer to the SurePOS Application Client/Server Environment for
4690 OS Planning and Installation Guide . GC30-4116.
2. A terminal that was inside a transaction can come up on the primary controller in a “secured” state;
however regular processing through the AEF can occur. This state assumes that the default operator
ID and passwords are being used; if they are not, then a manual sign-on must occur from the client
before continuing.

Scalability:
The maximum number of sessions a store can run simultaneously is 300, which must include the
configuration of the backup sessions.

Note: A backup session can be activated at any time; therefore, configured backup sessions are included
in the total sessions used on a controller.

Due to system resource limitations, no more than 25 sessions can be configured to be primary or backup
on each controller. For example, if a client wants to configure 25 backup sessions on a controller, then
only 25 sessions can be configured for that controller. Thus, if all the backup sessions are activated on the
controller at the same time, the controller can handle the load.

Configuring more than the published maximum number of sessions results in an unsupported controller
setup and could cause system-wide transactional errors.

Configuring initial full failover

The first time a system is configured with full failover support, you must indicate the session ownership
states.
1. First, both the primary and the backup controllers for a session that is configured for failover must be
brought up on the network.
2. After both controllers have CSS started and running, the client application can be started.

66 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

The client application will then request the failover configured session, which will initialize the session
ownership states.

If these steps do not occur before the primary controller goes down, then the session will not be available
for full failover on the backup machine.

Note: If the primary controller of a failover configured session has never served the terminal number,
the first time the session is started, you will receive system messages logged that relate to the session not
being able to access nonvolatile random access memory (NVRAM), and that the system is unable to
recover its transaction or both. These messages are normal, and should only occur the first time the
session is started. For ACE, these messages will be a series of messages for each terminal session in
question: X283, X285, and then X500.

Enabling quick init for failover

Version 6 of ACE includes a feature that allows a virtual session to be started in "Standby" mode. This
increases the initialization speed of virtual sessions. This function is available for ACE only and is
enabled by default in SI.

The Store Integrator default setting for quick init is in appsession.properties, quick.init.enable = true.
Setting this property to false will disable quick init.

For more information about Store Integrator and ACE enablement of quick init, see the Knowledgebase
Search at the www.toshibacommerce.com/support website and search on "Enabling Quick Init for
Failover".

Note: With quick init enabled, the adxcss1l stat command will no longer display an accurate number of
active sessions. Running ACE in standby mode starts the application and therefore causes the stat
command to report every configured terminal application, even if it's not currently active.

POS application usage for virtual sessions

During ACE or SA POS configuration, disable Auto Sign Off for all automated sessions to avoid errors
that are caused by timing issues. This option can generate an error (such as B077 CHECK PASSWORD)
because the POS application session went into a terminal secured state just before receiving a request
(for example, AddItem). You can either turn off the Auto Sign Off option and eliminate the error, or keep
the option on and resubmit your request after receiving the error.

Terminal sales programs operating in virtual sessions under CSS do not have direct access to the I/O
devices that would normally be attached to a real terminal. In some cases, the virtual sessions also have
access only to files that are local to the controller hosting the sessions. Do not attempt to perform
operations that are not physically possible in such an environment. You might have to avoid using some
options entirely. In other cases, you might have to include tests in your code that allow certain operations
to be performed on real terminals, but not while operating in CSS sessions. For more information about
testing for CSS sessions, see the Store Integrator Programming Guide (SC30-4084).

Transferring from one terminal to another terminal

For SA and ACE, the files that support the terminal transfer functions are local files. Consequently, under
normal SA and ACE operation, you can only transfer a transaction from one terminal to another terminal
on the same controller. With virtual sessions under CSS, this same consideration applies. You can only
transfer transactions from virtual sessions to other virtual sessions on the same controller, or between real
terminals located on the same controller as the virtual sessions.

Chapter 6. Configuring Store Integrator on 4690 OS 67

Configuring SI on 4690 OS

Monitoring one terminal from another terminal

For GSA, SA, and ACE, the files used for the terminal monitor function are local files. Therefore, in
normal operation, you can only use one terminal to monitor another terminal on the same controller.
With virtual sessions under CSS, it is theoretically possible to monitor virtual sessions only from other
virtual sessions on the same controller, or from real terminals on the same controller.

Tender franking and endorsement

Tender franking is specified during the personalization of the base POS application. For an emulated
printer in a virtual session under CSS, the system generates a normal prompt for a document to be
inserted. However, the system will hang while waiting for an event that cannot be satisfied.

Likewise, if you have specified tender endorsement when using an emulated printer under CSS, then the
resultant document insertion prompt will cause the same hang condition. The hang condition occurs
because the requested document cannot physically be inserted for printing.

Document printing
The same considerations applicable to tender franking and endorsement also apply to other forms of
document printing (such as further tender document printing, warranty document printing, and so on).
Avoid changing option settings and adding user code to the base product to implement document
printing.

Tender limit pickup

SA and ACE, through personalization, allow you to specify maximum cash drawer amount limits. If such
a limit is reached, the system stops and displays a prompt that requires the operator to perform a tender
pickup (withdrawal). You can prevent the tender limit tests from stopping the system by setting these
limits to very high values (such as 99999.99) that will never occur. If you test whether the system is
operating under CSS and change the limit variables through programming, you can allow normal limits
to continue in use when operating in real terminals.

Manager's key required and other error conditions

With ACE, certain personalization option settings require the scanning of a manager's ID, as well as use
of a manager's key. The ACE Terminal-Specific Options feature allows selected options to be enabled or
disabled for specific terminals. (Other options remain the same for all registers.) You can define
terminal-specific options for the terminal addresses used by CSS sessions. The options settings for these
sessions can differ from those of the corresponding options for addresses applicable to real terminals. In
this way, you can retain capabilities like the manager's key requirement and the scanning of a manager's
ID when operating in real terminals. Terminal-Specific Options provides a convenient way of setting
high-tender-limit-pickup values for CSS sessions and normal ones for real terminals, suppressing tender
franking in CSS sessions, and dealing with other personalization differences previously described in this
section.

Within AEF, various mechanisms exist to handle conditions (such as a manager's key required but not
present and other error conditions) that could cause the system to hang under CSS. Often, the
requirement for a manager's key cannot be suppressed through a personalization change, such as when
the manager's key is called for in a state table entry or by a program test. See the Store Integrator
Programming Guide (SC30-4084) for information regarding these mechanisms and the other preparatory
steps needed so that a POS terminal sales program, intended for operation in real terminals, can operate
successfully in virtual terminals under CSS.

Automatic terminal lockup

Through personalization, some POS applications might allow users to specify an automatic
terminal-lockup timeout. When a limit such as this is reached, the operator's session will be locked, and
the operator will need to enter a password to unlock and use that terminal. When an automatic-terminal

68 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

lockup timeout occurs, there is the possibility of a timing window where an AEF action does an initial
check to make sure the POS application was not in secure mode, sends a key sequence across, and the
application then goes into lock state causing the key sequence to fail.

To prevent hitting the window where AEF actions fail, disable the personalization option for the
automatic terminal lockup for all CSS sessions.

Tender verification for EPS tenders

When using SA, tender verification must be turned on for EPS tenders.

Enabling PIN pads

Make sure that you enable PIN pads in ACE (in ACE Personalization>EPS>Device>PINPad Config)
only for those virtual sessions that are actually using a PIN pad. To isolate this setting to only specific
sessions, create terminal specific options for those sessions using a PIN pad.

Price override reason codes

In ACE, if you are configured with fuel items, make sure that the option Prompt for reason code when
Price key pressed is OFF. If this option is ON, you will receive a B003 message when trying to sell a
keyed price fuel item.

Barcode Configuration
In order for virtual sessions to process selected barcode label types, the user must select the appropriate
labels in the Hand-held Devices section of the STORE Device Characteristics when using the 4690
Terminal Configuration utility.

Configuring the Service Provider and Deploying Services

Configuring the Service Provider

To enable the service provider you must simply add the SI messaging jar files to the CSS or SI GUI
classpath on the 4690. The required jar files are:
v c:\adx_ipgm\bc_api.jar
v c:\adx_ipgm\ecore.jar
v c:\adx_ipgm\ecoresdo.jar
v c:\adx_ipgm\ecorexmi.jar
v c:\adx_ipgm\common.jar
v c:\adx_ipgm\commjsdo.jar

For the SI GUI, you must edit the Java configuration(s) for your terminals and add the required jar files
to the classpath. For CSS, you must add the required jar files to the CSS classpath in aefvirt.txt.

The classpaths in the default aefvirt.txt and SI GUI configuration files on the SI install CD already contain
the necessary jar files. You only need to add them yourself if you are migrating from an older version of
SI, as these configuration files are not updated automatically in order to preserve your customizations.

Deploying services
Solution integrators are responsible for creating a services properties bundle file containing the following
information:
v The list of service implementations in the solution.
v The events that the AEF will make to available services.

Chapter 6. Configuring Store Integrator on 4690 OS 69

Configuring SI on 4690 OS

To enable a service implementation, you must add a property mapping defining the fully-qualified
classname of the main service module to your services properties bundle. You can define multiple service
implementations, but they must have unique keys in the following format:
v service.[company].[unique_id]=fully.qualified.classname
– service
- Static part of the key that identifies the property as a service implementation mapping - Required.
– [company]
- The name of the company that provided the service - Required.
– [unique_id]
- Data used to uniquely identify and separate services from the same company. Optional if a
company only provides one service.

To make events available to services, you must add the event name to the following property in your
services properties bundle:
v enabled.service.events=comma delimited list of events

Your service provider must provide the list of events their service requires. See the POSBC schema for
details on event structure.

You must place the services properties file in a jar file on the SI jar file override hierarchy. Example:
v Jar file: sibusp.jar
v Contents:
– sibuspservices.properties
- Contents:
v service.aCompany.1=org.A.company.services.AService
v service.bCompany.1=org.B.company.services.BService1
v enabled.service.events=event1,event2,event3

The solution integrator is also responsible for putting the jar files containing deployed service
implementations on the classpath of each SI application in their solution. The following steps outline how
this is accomplished:

Note: This tutorial assumes that the terminals are configured to match SI’s example terminal
configuration files.
v In C:\ADX_IPGM on the master controller, edit aefvirt.txt and add the path to the services jar file(s) to
the end of the classpath
– The classpath begins at the –cp argument and is one line of semi-colon delimited files.
– Warning:
- XE on 4690 has a line length limit of 1000 characters and will truncate the line when saved if it
exceeds that value causing CSS to fail. Avoid editing aefvirt.txt with this text editor unless you are
100% sure your edits will not cause the line to exceed the maximum line length.
v In 4690 terminal configuration:
– Create a new preload bundle named services.
– In the preload bundle, add the service jar files as optional files.
– Add this new preload bundle to the list of preload bundles for your terminals.
– Edit the Java application configuration for the following applications and add the service jar files to
the end of their classpaths:
- AEF:
v ACEAEF

70 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

v ACEAEFCT
- SI GUI:
v ACEOPER
v ACECUST
v ACEDD
v ACECTOPR
v ACECTCST
v ACECTDD
– Activate terminal configuration.

Digital receipts
Producing a digital receipts requires point of sale configuration, as well as SI configuration. At this time,
we only support producing digital receipts when using ACE. See the SurePOS Application Client/Server
Environment for 4690 OS: Planning and Installation Guide for ACE configuration information.

In order for SI to produce a digital receipt, solution integrators must create a services properties file as
described in “Deploying services” on page 69 with the details of their digital receipt service. TSolution
integrators must enable at least the following events in the properties file:
v CouponAddedEvent
v CouponVoidedEvent
v CustomerEventItemAddedEvent
v DiscountEvent
v ItemVoidedEvent
v ItemReturnedEvent
v PointsEvent
v POSReceiptEvent
v PSCouponAddedEvent
v PSCouponVoidedEvent
v PSGiftCardAddedEvent
v PSGiftCardVoidedEvent
v TenderAddedEvent
v TenderVoidedEvent
v TransactionCompletedEvent
v TransactionRecoveredEvent
v TransactionReplayCompleteEvent
v TransactionRetrievedEvent
v TransactionStartEvent
v TransactionSuspendedEvent
v TransactionTotalEvent
v TransactionTransferredEvent
v TransactionVoidedEvent

It is highly recommended that you turn off the digital receipt capabilities in ACE and SI if they are not
being used to avoid impacting solution performance.

Chapter 6. Configuring Store Integrator on 4690 OS 71

Configuring SI on 4690 OS

AEF properties files

AEF bundles are sets of property files that are used to configure AEF properties files in groups called
bundles.

AEF bundles
When a file is loaded, every properties file in the bundle is checked. The files within each bundle are
read in the order shown in Table 20. If you add any intermediate files to the bundle, the next File field
allows the files to be read in the correct order.

If the value of a property is specified in multiple files, the last value read is used. The user*.properties
files are read last, enabling you to override AEF defaults with your own values. For detailed information
about the variables in the property files, refer to 4690 Store Integrator Graphical User Interface Programming
Guide (GC30-4121).
Table 20. AEF bundles
AEF Bundle Files Description
Automation 1. automation.properties Specifies how automation calls
2. appautomation.properties behave when errors are encountered
3. siibmautomation.properties or when an override is needed.
4. sibuspautomation.properties
5. sicompanyautomation.properties
6. sistoreautomation.properties
7. siterminalautomation.properties
8. siuserautomation.properties
9. userautomation.properties 2
10. userautomation_xxx.properties1 automation
Class 1. classes.properties Tells AEF what Java class should be
2. appclasses.properties used to perform a specific job.
3. siibmclasses.properties
4. sibuspclasses.properties
5. sicompanyclasses.properties
6. sistoreclasses.properties
7. siterminalclasses.properties
8. siuserclasses.properties
9. userclasses.properties 2
Configuration 1. config.properties Configures properties that do not fit
2. appconfig.properties into other bundles.
3. siibmconfig.properties
4. sibuspconfig.properties
5. sicompanyconfig.properties
6. sistoreconfig.properties
7. siterminalconfig.properties
8. siuserconfig.properties
9. userconfig.properties 2
Error 1. error.properties Specifies error helpers that handle
2. apperror.properties specific errors.
3. siibmerror.properties
4. sibusperror.properties
5. sicompanyerror.properties
6. sistoreerror.properties
7. siterminalerror.properties
8. siusererror.properties
9. usererror.properties2

72 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

Table 20. AEF bundles (continued)

AEF Bundle Files Description
Function code 1. fcode.properties Maps logical key names to function
2. appfcode.properties codes.
3. siibmfcode.properties
4. sibuspfcode.properties
5. sicompanyfcode.properties
6. sistorefcode.properties
7. siterminalfcode.properties
8. siuserfcode.properties
9. userfcode.properties 2
Internationalization 1. i18ntext.properties Stores text that is displayed to the
2. appi18ntext.properties user of an AEF application (must be
3. siibmi18ntext.properties translated into the local language).
4. sibuspi18ntext.properties
5. sicompanyi18ntext.properties
6. sistorei18ntext.properties
7. siterminali18ntext.properties
8. siuseri18ntext.properties
9. useri18ntext.properties 2
Key sequence 1. sequence.properties Specifies key sequences for POS
2. appsequence.properties operations on a terminal.
3. siibmsequence.properties
4. sibuspsequence.properties
5. sicompanysequence.properties
6. sistoresequence.properties
7. siterminalsequence.properties
8. siusersequence.properties
9. usersequence.properties2
Logon 1. applogon.properties Specifies a default user ID and
2. siibmlogon.properties password combination for a specific
3. sibusplogon.properties terminal.
4. sicompanylogon.properties
5. sistorelogon.properties
6. siterminallogon.properties
7. siuserlogon.properties
8. userlogon.properties 2
Services 1. services.properties Service provider properties
2. appservices.properties
3. siibmservices.properties
4. sibuspservices.properties
5. sicompanyservices.properties
6. sistoreservices.properties
7. siterminalservices.properties
8. siuserservices.properties
9. userservices.properties
SSL 1. ssl.properties Configures SSL settings
2. appssl.properties
3. siibmssl.properties
4. sibuspssl.properties
5. sicompanyssl.properties
6. sistoressl.properties
7. siterminalssl.properties
8. siuserssl.properties
9. userssl.properties

Chapter 6. Configuring Store Integrator on 4690 OS 73

Configuring SI on 4690 OS

Table 20. AEF bundles (continued)

AEF Bundle Files Description
Session 1. session.properties Configures session-specific settings.
2. appsession.properties
3. siibmsession.properties
4. sibuspsession.properties
5. sicompanysession.properties
6. sistoresession.properties
7. siterminalsession.properties
8. siusersession.properties
9. usersession.properties 2
10. usersession_xxx.properties1
State 1. states.properties Maps logical application states to
2. appstates.properties state numbers.
3. siibmstates.properties
4. sibuspstates.properties
5. sicompanystates.properties
6. sistorestates.properties
7. siterminalstates.properties
8. siuserstates.properties
9. userstates.properties 2
Substate 1. appsubstates.properties Maps logical application substates to
2. siibmsubstates.properties substate numbers.
3. sibuspsubstates.properties
4. sicompanysubstates.properties
5. sistoresubstates.properties
6. siterminalsubstates.properties
7. siusersubstates.properties
8. usersubstates.properties2
Tender map 1. tendermap.properties Maps tender names to
2. apptendermap.properties application-specific tender types.
3. siibmtendermap.properties
4. sibusptendermap.properties
5. sicompanytendermap.properties
6. sistoretendermap.properties
7. siterminaltendermap.properties
8. siusertendermap.properties
9. usertendermap.properties 2
1
Where xxx is the terminal that will load the property file.
2
These properties are deprecated and will be deleted in the future.

Config properties bundle

The bundle file, config.properties, contains general SI configuration properties. The properties are
described below.
Table 21. Config properties bundles
Property description
multicast.ttl Specifies the Time To Live ( TTL ) for a multicast packet. Each gateway will
decrement 1 from the TTL. When the TTL == 0, the packet will no longer be
routed. Must be in the range of 1 to 10.

Use this property if you need to run a remote SI client on a different subnet
than the server. To find the appropriate value, add 1 for each gateway the
packet passes through.

Default: 1

74 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

SSL properties file

The bundle file, ssl.properties, contains properties for configuring SSL. The properties are described in
Table 22:
Table 22. SSL properties file
Property Content Code for Version 2 of SI
alias Defines the set of SSL parameters to Yes
be applied. The other properties in
the list must have the alias
prepended. For example, if the alias
is Site1 and the property is
KeyFileName, then the property
reference is Site1.KeyFileName.
DEFAULT: Default alias name for that Yes
v DEFAULT.alias = AEF application. You can override these
values.
v AEF.alias = AEF
v AEFIO.alias = AEF
v JIF.alias = JIF
Site1.enable True enables SSL; false or not present Yes
disables SSL. The defaults are
AEF.enable=false and JIF.enable=false
Note: Define the following properties as a group:
v <alias> *KeyFileName
v <alias> *TrustFileName
v <alias> *KeyPassword
v <alias> *TrustPassword
All must be defined to have a valid entry. A typical example of the SI default entries (with an alias of AEF):
AEF.ServerKeyFileName=c:\\adx_idt1\\rsskeys
AEF.ServerKeyPassword=RSSintegrator
AEF.ServerTrustFileName=c:\\adx_idt1\\rssstore
AEF.ServerTrustPassword=RSSintegrator

v Site1.KeyFileName Fully qualified path to the key file Yes

(Server is 4690; GUI is stand-alone
v Site1.ServerKeyFileName
terminals.)
v Site1.GUIKeyFileName

v Site1.KeyPassword Access to keystore Yes

v Site1.ServerKeyPassword
v Site1.GUIKeyPassword
Site1.SecurityLevel Token LOW or HIGH
v LOW = digital signing, no
encryption
v HIGH = 128-bit encryption,
including digital signing
Note: If you are using
FIPS-compliant security, you must
select HIGH.
Site1.CipherSuite Select this option if security level is Yes
not low. It is ignored if
SecurityLevel=Low. Valid options are
MD5, DES, 3DES, RC4.

Chapter 6. Configuring Store Integrator on 4690 OS 75

Configuring SI on 4690 OS

Table 22. SSL properties file (continued)

Property Content Code for Version 2 of SI
Note: When setting the provider and protocol, not all combinations are valid. The AEF code does not validate or
check between the properties.
IBMJSSE and IBMJSSE2 work with both TLS and SSL_TLS.
IBMJSSEFIPS only works with TLS.

For additional information on providers and their protocols, see: www.ibm.com/developerworks/java/jdk/

security/index.html. From that main page, select your configuration. For example, from the security index, select
SDK (J2SE 5.0), and then select the platform (Windows 32-bit).
Site1.provider Selects which SSL suite to use: Yes
IBMJSSE, IBMJSSE2, or
IBMJUSSEFIPS.

v Site1.TrustFileName Fully qualified name of the trust file, Yes

if used.
v Site1.ServerTrustFileName
v Site1.GUITrustFileName

v Site1.TrustPassword Password to the trust file name. Yes

v Site1.ServerTrustPassword
v Site1.GUITrustPassword
Site1.protocol TLS or SSL_TLS Yes

SI configuration hierarchy
The file names on the C: drive of a 4690 system are restricted to an 8.3 format. As a result, it is difficult to
give the property files meaningful names. To address this problem, the files in the AEF bundles are
included in JAR files. The OS deals with the 8.3 file names of the JAR files, while the configuration files
contained in the JARs can use long file names. Table 23 lists the JAR files for AEF and the POS
applications.
Table 23. AEF and application JAR files
JAR file Contents
AEF.JAR Base property files
AEFACE.JAR ACE-specific property files
AEFGSA.JAR GSA-specific property files
AEFSA.JAR SA-specific property files

Note: Other POS applications may have application specific properties in a jar file such as 'AEFOPA.JAR'.
What ever the jar file name, it must be added to the classpath.

You can use the SI*.PROPERTIES to add new properties or override existing properties. Figure 17 on page
78 depicts the property file hierarchy. As you move down the chart, the properties in the files closer to
the bottom will override properties defined higher in the hierarchy.

For example, if a new.property is added in siibm*.properties, and you place a setting for new.property in
siuser*.properties, the value in siuser*.properties will be the one to take effect.

Note:
1. For current users, user*.properties files are supported. For new users, you should use
siuser*.properties. However, do not use both user*.properties and siuser*.properties files at the same
time.

76 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

2. Property file names are case-sensitive and must be in all lowercase letters; otherwise unexpected
behavior can occur.

Chapter 6. Configuring Store Integrator on 4690 OS 77

Configuring SI on 4690 OS

Figure 17. Property file hierarchy

You must include any si*.properties files in SI*.JAR in the C:/ADX_IPGM/ directory. See Table 24 on
page 79 for a list of the SI*.JAR files.

78 User's Guide: Store Integrator User's Guide

 Configuring SI on 4690 OS

Table 24. User JAR files

JAR file Description
SIIBM.JAR For session configurations and extensions from Toshiba.
SIBUSP.JAR For session configurations and extensions from business partners.
SICOMP.JAR For store configurations.
SISTORE.JAR For store configurations.
SIUSER.JAR Properties for user configurations.
USER.JAR Properties for virtual (CSS) terminals.
Note: Place this JAR file into the C:/USER/ directory.
USERSIM.JAR Properties for virtual (CSS) terminals.
Note: Place this JAR file into the C:/USER/ directory.

Figure 18 depicts the default hierarchy for JAR files.

Figure 18. Default hierarchy for JAR files

The JAR file hierarchy is determined by the order of the JARs on the classpath. Figure 18 depicts the
default hierarchy as specified in the classpath in AEFVIRT.TXT.

Note: For current users, USER.JAR and USERSIM.JAR are supported; however, you should use a
combination of USER.JAR and SIUSER.JAR for virtual session configuration. Configurations that apply to
both virtual sessions and real terminals should go into SIUSER.JAR, along with configurations that apply
only to real terminals. Configurations that apply only to virtual sessions should go into USER.JAR.

Chapter 6. Configuring Store Integrator on 4690 OS 79

Configuring SI on 4690 OS

For an example of the default hierarchy, if siibmssl.properties is in both SIIBM.JAR and SIUSER.JAR, the
system will use the siibmssl.properties file in SIUSER.JAR.

The default AEF response files already include the USER.JAR, and USERSIM.JAR files in the classpath.
Because these files are not part of AEF, you must create them if you intend to use them. These files must
be distributed to all controllers in the environment with a distribution attribute of 5, Compound on
Close.

80 User's Guide: Store Integrator User's Guide

Chapter 7. Installing and configuring the Windows Client
This section describes how to configure Windows Clients to use POSBC. This section also describes how
to install AEF Remote Device Support, and how to configure the Windows Client and the 4690 controllers
to use it.

POSBC configuration on Windows Client

You can use a set of properties files to configure the POSBC. See “AEF properties files” on page 72 for a
discussion of the properties bundles and property value overrides.
Table 25. POSBC file descriptions
Bundle Files Description
POSBC v posbc.properties General configuration for the POSBC.
v appposbc.properties
v siibmposbc.properties
v sibuspposbc.properties
v sicompanyposbc.properties
v sistoreposbc.properties
v siterminalposbc.properties
v siuserposbc.properties
v userposbc.properties¹
Business Component v bclistener.properties Set the implementation class that the listener
listener will use to construct business components
v appbclistener.properties
(BC's).
v siibmbclistener.properties
v sibuspbclistener.properties
v sicompanybclistener.properties
v sistorebclistener.properties
v siterminalbclistener.properties
v siuserbclistener.properties
v userbclistener.properties¹
JIF Server v jifsrvc.properties Sets general properties such as the Business
Component listener class.
v appjifsrvc.properties
v siibmjifsrvc.properties
v sibuspjifsrvc.properties
v sicompanyjifsrvc.properties
v sistorejifsrvc.properties
v siterminaljifsrvc.properties
v siuserjifsrvc.properties
v userjifsrvc.properties¹

81
Windows Client installation and configuration

Table 25. POSBC file descriptions (continued)

Bundle Files Description
POSBC classes v posbcclasses.properties Instructs POSBC what Java class performs a
specific task.
v appposbcclasses.properties
v siibmposbcclasses.properties
v sibuspposbcclasses.properties
v sicompanyposbcclasses.properties
v sistoreposbcclasses.properties
v siterminalposbcclasses.properties
v siuserposbcclasses.properties
v userposbcclasses.properties¹
Internationalization v posbci18ntext.properties
v appposbci18ntext.properties
v siibmposbci18ntext.properties
v sibuspposbci18ntext.properties
v icompanyposbci18ntext.properties
v sistoreposbci18ntext.properties
v siterminalposbci18ntext.properties
v siuserposbci18ntext.properties
v userposbci18ntext.properties¹

¹ These properties are deprecated and will be deleted in the future.

Requirements for AEF Remote Device Support

The Remote Device Support feature of the Store Integrator allows a client with locally attached devices to
use a CSS virtual session to perform POS functions. To use this capability, you must install the AEF
software on your 4690 OS controller server (see “Installing SI on a 4690 operating system” on page 29)
and configure it for CSS operation (see “Configuring CSS” on page 61).

Both POSBC and the Remote GUI use remote devices and provide sample aefio.xml files. You can set up
a system to run both POSBC and the Remote GUI at the same time; however, POSBC and the Remote
GUI cannot access the same remote devices on the same box at the same time. Specifically, only one
remote device server can be running at a time. So, either POSBC or Remote GUI can create a remote
device server.

The use of JavaPOS to provide remote POS device support results in some differences in the behavior
between POS devices attached to a local 4690 terminal and the same POS devices attached to a remote
client. See the Store Integrator Programmers Guide Appendix H, for more information regarding remote
POS device support.

Windows Client configuration steps

For each client machine, perform the following steps:
1. Before installing Store Integrator, both a Windows platform (see following specific platforms) and
Toshiba JavaPOS/Java 1.6 (see Step 2) must be installed.
v Microsoft Windows 7, Microsoft Windows Embedded Point of Service (WEPOS), Microsoft
Embedded POSReady 2009, or Microsoft Embedded POSReady 7.
v Java 1.6 (IBM version of the Java JVM, which is included with the Toshiba JavaPOS package)

82 User's Guide: Store Integrator User's Guide

 Windows Client installation and configuration

Note: Make sure the environment variable JAVA_HOME is set to the directory in which the bin
directory resides (java.exe will reside in the bin directory). Typically this is the JRE directory. For
example:
JAVA_HOME=C:\POS\IBMJRE;C:\POS\IBMJRE\jre\bin
v Store Integrator
2. Install Toshiba JavaPOS 1.13.3 or later, and make sure you install the JRE so that you get the IBM
Java Communications API. Toshiba JavaPOS provides the necessary drivers for POS devices used in
a Java environment, and can be downloaded from the Module Update Check page of the Toshiba
Global Commerce Solutions Web site. Select the link for installing JavaPOS 1.13.3 or later, if it has
not already been installed prior to installing Store Integrator, which is described in Chapter 5,
“Installing Store Integrator components,” on page 29.
a. Change the installation drive and folder name, if required.
b. Select the installation defaults.
3. Attach your selected supported devices to the USB, RS485 or serial ports of the client machine.
4. JavaPOS 1.13.3 or later requires a Windows reboot.
5. Configure the local devices for use by Toshiba JavaPOS.
a. Create a jpos.xml file to configure the devices that you will be using. For information related to
creating this file, see the Configuring Devices chapter in the UnifiedPOS User’s Guide,
Keyboards, and Code Pages. (This document was copied to your system when you installed
Toshiba JavaPOS.)
b. Change the jposEntry logicalName for each of your configured devices so that it matches the SI
logical name. See Table 26.
Table 26. Supported SI devices and corresponding SI logical name
Supported devices listed in jposSample.xml SI configuration SI logical name
Scanner Remote GUI Scanner1
POSPrinter 4610 (receipt station only) Remote GUI and POSBC POSPrinter1
MSR Remote GUI and POSBC MSR1
ToneIndicator (on POSPrinter or 4820 Touch Display) Remote GUI ToneIndicator1
LineDisplay (single-sided only) Remote GUI LineDisplay1
CashDrawer (single only) Remote GUI CashDrawer1
Note:
1. The PIN pad, which is also supported by Remote GUI and POSBC, does not require an entry in the jpos.xml file.
2. SI only supports compatibility mode for the Toshiba 4610-2CR, Toshiba 4610-2NR and Toshiba 4610-1NR
printers. For instructions to enable compatibility mode, use the Knowledgebase search on
www.toshibacommerce.com/support and search for UPOS 1.12 SI.

c. Copy your jpos.xml file into the \pos\ibmjpos\config directory on your Windows machine.
6. If you are using a Remote GUI terminal, you might need to configure Remote Device Support
properties. The following properties must be present in the CustSV.properties file. This file is placed
in the %SI_HOME%\user\xxx directory by the Remote GUI installation process (where xxx is the
application, ACE, SA or GSA). This file contains general configuration options that affect the
behavior of the client software. These default values can be modified by changing the lines in the
CustSV.properties (or verifying that existing lines are correctly set and editing them if necessary).

aefio.device.group=guijpos

Figure 19. Example A

Chapter 7. Installing and configuring the Windows Client 83

Windows Client installation and configuration

Figure 19 on page 83 illustrates a group name that must match to a configured group in the
AEFIO.XML file. See “Configuring the controller for remote and virtual device support” on page 85.

application.resizeable = false

Figure 20. Example B

For Figure 20, set to true to allow the Remote GUI screen to be minimized and maximized.
7. For POSBC, the default value that is set for the aefio.device.group property is:
aefio.device.group=scojpos. This default property is in the posbc.properties file. If you want to
change the setting, place your change into userposbc.properties and place the file in
%SI_HOME%\user\posbc. (The %SI_HOME% environment variable is set during installation.)

Note: See “SI configuration hierarchy” on page 76 for instructions on modifying properties files.
8. (OPTIONAL) For Remote GUI, install the ICEbrowser JAR files in any directory. For information
concerning how to obtain and install ICEsoft's ICEbrowser for use with SI GUI or Remote GUI, go to
the Knowledgebase on www.toshibacommerce.com/support and search on “ICEbrowser”.
9. For Remote GUI, the installation process provides sample batch files for starting remote client
applications. Each batch file is specific to a particular POS application. Use Table 27 to identify the
batch file that you will use. In Table 27, installpath is where you installed the SI GUI, using the
setup.exe program. The default installpath is C:\Program Files\IBM\StoreIntegrator.
Table 27. Sample batch files for starting remote applications
Application Batch file Directory
ACE ace_gui.bat installpath\%GUI_HOME%\ace
GSA gsa_gui.bat installpath\%GUI_HOME%\gsa
SA sa_gui.bat installpath\%GUI_HOME%\sa

10. For Remote GUI, modify the installpath\user\app\cust_env.bat file as follows:

a. Set the @set TERMINAL_NUMBER= line to the 4690 virtual terminal address. Be sure that the specified
terminal has been defined as a reserved terminal (see “Enabling CSS” on page 61).
b. Set the @set MY_IP= line to the IP address of the Windows Client machine where the Remote
Device Support/Remote GUI will run.
c. Optionally (ICEbrowser is not required for StoreIntegrator V3R3) specify the ICEBrowser install
directory in the cust_env.bat file, which is in the %SI_HOME%\user\xxx directories where xxx is
the application, ACE, SA, or GSA. Set the @set ICESOFT_PATH= line to the directory where you
installed the ICEbrowser JAR files in step 8.
11. Any files in the installpath\user\app directories will not be overwritten should you install a new
level of the SI GUI.

Multiple Subnets
You can run a remote SI client on a different subnet than the server. To accomplish this, you must set the
multicast time to live, multicast.ttl, property in the config properties bundle large enough such that the
multicast packets can reach all of the subnets. To find the appropriate value, add 1 for each gateway the
packet passes through. We do not support solutions running on multiple subnets that block multicast
packets.

Things to consider when running on multiple subnets:

1. Increasing the number of hops between the client and server increases network latency and will
negatively impact response times.

84 User's Guide: Store Integrator User's Guide

 Windows Client installation and configuration

2. Increasing the time to live on a multicast packet increases the network activity on all of the systems
connected to the external subnet, not just the client and server. This is because, by definition,
networks deliver multicast packets to all hosts connected to a given subnet.

Configuring the controller for remote and virtual device support

A sample AEFIO.XML file is included on the installation CD, and can be found in the
p:\4690\gui\samples directory when configuring devices for Remote GUI, or POSBC. Copy this file into
the ADX_IDT1 directory on the 4690 controller. Set this file's distribution type to 5 (Compound File,
Distribute on Close). This file contains the device group guijpos for Remote GUI, or the device group
scojpos for POSBC. This file also contains a device group sample with examples of all supported devices.

The AEFIO.XML sample file defines device proxies for the remote devices currently supported by Store
Integrator for attachment to your remote client. For remote devices, the logical names are used in the file
JPOS.XML, which provides corresponding device configuration information within the client itself (see
step 5 on page 83 in the Windows Client installation and configuration steps section).

Table 28 indicates the logical device names used for the each device supported by the Remote GUI and
the POSBC.
Table 28. Logical device names used for remote devices supported by the Remote GUI and the POSBC
Remote GUI POSBC
4610 Printer Receipt station only POSPrinter1 POSPrinter1
Scanner Scanner1 Not supported
MSR MSR1 MSR1
Tone Indicator ToneIndicator1 Not supported
Serial Port SerialPort1/SerialPort2 SerialPort1/SerialPort2
2x20 Single-sided Display LineDisplay1 Not supported
Cash Drawer CashDrawer1 Not supported

The AEFIO.XML sample file also contains the virtual devices currently supported by the POSBC. Table 29
indicates the logical device names used for the each device supported by the POSBC.
Table 29. Logical device names used for the virtual devices supported by the POSBC
POSBC
Scale Scale1

If you have multiple clients with different devices attached, then you must create multiple device groups
in AEFIO.XML. If you have a client with no devices attached, then you must also have a device group
that contains no devices. The AEFIOCFG.BAT file is used to define or modify the device groups in
AEFIO.XML. It is important to note that, unlike JPOS.XML, you cannot go into AEFIO.XML with an
editor to make modifications to it; you must use AEFIOCFG.BAT to make even simple modifications to
AEFIO.XML.

The following steps describe how to use AEFIOCFG.BAT to set up your device groups that reflect the
actual combinations of supported remote devices that you intend to use, if your requirements differ from
the devices provided in the default device group GUIJPOS or SCOJPOS. (If you are not using a PIN pad,
there is no need to delete entries from any device group in AEFIO.XML for SerialPort1 or SerialPort2.)
However, if you are not using a scanner and printer (for Remote GUI) or scanner, printer, and MSR (for
POSBC), then those entries not used must be deleted from their respective device groups.

Chapter 7. Installing and configuring the Windows Client 85

Windows Client installation and configuration

If other device groups are required to support differing configurations besides those stated above, then
other device group names would have to be used. AEFIOCFG.BAT would be used to add the new device
groups to AEFIO.XML. Client machines would then specify these new device groups in the
CustSV.properties file.

Use AEFIOCFG.BAT to modify the guijpos or scojpos groups, or to add other device groups. The
AEFIOCFG.BAT file has been placed in the \ADX_IPGM directory by the installation process, and must
be run from that directory.

Note: Check to be sure that your existing AEFIO.XML file is in directory ADX_IDT1. In the absence of a
preexisting AEFIO.XML, there is a default device group that is automatically defined (called default).
This group contains no devices. You can use this group for a Remote GUI or POSBC client with no
attached devices (other than the GUI display itself in the context of the Remote GUI).

Adding a new group

To add a new group to aefio.xml, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Click Edit -> New -> Group.
3. In the New Group dialog box, click the Name field to select it. Type the new device group name.
Click OK. The group is created.

Adding a remote printer

To add a remote printer device to this group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select a group. Click Edit -> New -> Device.
3. In the New Device dialog box:
a. Click the Name field to select it. Type POSPrinter1.
b. Click Category -> POSPrinter.
c. Click Type -> Remote.
d. Click OK. The POSPrinter1 device appears in the group and is selected.
4. To add the deviceName property to POSPrinter1, click Edit -> New -> Property.
5. In the New Property dialog box:
a. Set Name to deviceName.
b. Click Type -> String.
c. Set Value to POSPrinter1.
d. Click OK. The deviceName property appears in the Property list for POSPrinter1.

Adding a remote scanner

To add a remote scanner device to a group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select a group. Click Edit -> New ->Device.
3. In the New Device dialog box:
a. Click the Name field and type Scanner1.
b. Click Category -> Scanner.
c. Click Type -> Remote.
d. Click OK. The Scanner1 device appears in the group and is selected.
4. To add the deviceName property to Scanner1, click Edit -> New -> Property.
5. In the New Property dialog box:

86 User's Guide: Store Integrator User's Guide

 Windows Client installation and configuration

a. Set Name to deviceName.

b. Click Type -> String.
c. Set Value to Scanner1.
d. Click OK. The deviceName property now appears in the Property list for Scanner1.

Adding a remote PIN pad

To add a remote PIN pad device to the group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select the group. Click Edit -> New -> Device.
3. In the New Device dialog box:
a. Click the Name field, and type SerialPortn, where n is the number of the serial port that is
opened by the 4690 POS application.
b. Click Category -> SerialPort.
c. Click Type -> Remote.
d. Click OK. The SerialPortn device appears in the group and is selected.
4. If necessary, modify the port property of SerialPortn, by following these steps:
a. Click on the COMn property.
b. Click Edit->Modify->Property.
c. Change the value to COMn, where n is the number of the port on the Windows Client machine
where the PIN pad is plugged.
d. Click OK.

Adding a remote MSR

To add a remote MSR device to the group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select the group. Click Edit -> New -> Device.
3. In the New Device dialog box:
a. Click the Name field and type MSR1.
b. Click Category -> MSR.
c. Click Type -> Remote.
d. Click OK. The MSR1 device appears in the group and is selected.
4. To add the deviceName property to MSR1, click Edit -> New -> Property
5. In the New Property dialog box:
a. Set Name to deviceName.
b. Click Type -> String.
c. Set Value to MSR1.
d. Click OK. The deviceName property appears in the Property list for MSR1.

Adding a remote tone indicator

To add a remote tone indicator to the group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select the group. Click Edit -> New -> Device.
3. In the New Device dialog box:
a. Click the Name field, and type ToneIndicator1.
b. Click Category -> ToneIndicator.
c. Click Type -> Remote.

Chapter 7. Installing and configuring the Windows Client 87

Windows Client installation and configuration

d. Click OK. The ToneIndicator1 device appears in the group and is selected.
4. To add the deviceName property to ToneIndicator1, click Edit -> New -> Property.
5. In the New Property dialog box:
a. Set Name to deviceName.
b. Click Type -> String.
c. Set Value to ToneIndicator1.
d. Click OK. The deviceName property now appears in the Property list for ToneIndicator1.

Adding a remote line display

To add a remote line display to the group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select the group. Click Edit -> New -> Device.
3. In the New Device dialog box:
a. Click the Name field, and type LineDisplay1.
b. Click Category -> LineDisplay.
c. Click Type -> Remote.
d. Click OK. The LineDisplay1 device appears in the group and is selected.
4. To add the deviceName property to LineDisplay1, click Edit -> New -> Property.
5. In the New Property dialog box:
a. Set Name to deviceName.
b. Click Type -> String.
c. Set Value to LineDisplay1.
d. Click OK. The deviceName property now appears in the Property list for LineDisplay1.

Adding a remote cash drawer

To add a remote cash drawer to the group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select the group. Click Edit -> New -> Device.
3. In the New Device dialog box:
a. Click the Name field, and type CashDrawer1.
b. Click Category -> CashDrawer.
c. Click Type -> Remote.
d. Click OK. The CashDrawer1 device appears in the group and is selected.
4. To add the deviceName property to CashDrawer1, click Edit -> New -> Property.
5. In the New Property dialog box:
a. Set Name to deviceName.
b. Click Type -> String.
c. Set Value to CashDrawer1.
d. Click OK. The deviceName property now appears in the Property list for CashDrawer1.

Adding a virtual scale

To add a virtual scale device to the group, follow these steps:
1. Run AEFIOCFG.BAT. The AEF Device Accessor Configuration panel is displayed.
2. Select the group. Click Edit -> New -> Device.
3. In the New Device dialog box:

88 User's Guide: Store Integrator User's Guide

 Windows Client installation and configuration

a. Click the Name field, and type Scale1.

b. Click Category -> Scale.
c. Click Type -> Virtual.
d. Click OK. The Scale1 device appears in the group and is selected.
4. To add the deviceName property to Scale1, click Edit -> New -> Property.
5. In the New Property dialog box:
a. Set Name to deviceName.
b. Click Type -> String.
c. Set Value to Scale1.

Deleting a device
To delete a device from an existing group, follow these steps:
1. Select the group.
2. Click the device you want to delete.
3. Click Edit -> Delete -> Device.
4. Click OK.

Saving your configuration

After all devices have been configured, follow these steps to save your configuration data:
1. Click File -> Save.
2. Click File -> Exit.

Starting the application

This section describes how to run the Remote GUI and start POSBC.

Note: Remote GUIs or client applications of any type cannot be assigned the same terminal number as
another Remote GUI or client application. All terminal IDs must be different.

For integrations with POS applications other than ACE, SA or GSA, contact the integrator for information
on running the Remote GUI and POSBC.

Running the Remote GUI

To start the Remote GUI, follow these steps:
1. On the 4690 controller, start CSS. The session number of your remote client, as specified in
CUST_ENV.BAT, must be designated as a reserved terminal number (see “Enabling CSS” on page 61).
2. On the Windows machine, after CSS has started, run installpath\GUI2011xxx\app\app_gui.bat (where
installpath is the installation directory you selected in step 5 on page 32, xxx is the build level of the
Store Integrator code, and app is ACE, SA, or GSA, depending on your POS application). You can add
the name of the batch file to the Startup folder, so that the remote program execution can be started
automatically.

Starting POSBC
To start the POSBC, follow these steps:
1. On the 4690 controller, start CSS. The session number of your remote client must be designated as a
reserved terminal number (see “Enabling CSS” on page 61).
2. On the Windows machine, after CSS has started, run installpath\AEF2011xxx\runposbc.bat (where
installpath is the installation directory you selected in step 5 on page 32 and xxx is the build level of
the Store Integrator code).

Chapter 7. Installing and configuring the Windows Client 89

Windows Client installation and configuration

Users might need to modify properties in bclistener.properties, jifserver.properties, or posbc.properties. To

override properties in these files, create siuserxxxx.properties files (where xxxx is the name of the
property file that you are changing). An example of this would be siuserbclistener.properties. These files
are then placed in the %SI_HOME%\user\posbc directory. See Table 25 on page 81 for information about
the configuration properties files.

90 User's Guide: Store Integrator User's Guide

Chapter 8. Problem determination
This section describes the troubleshooting and debugging resources provided by Store Integrator, and
explains how to use them.

Trace types
Several types of traces are available to aid you in troubleshooting program execution problems. Table 30
lists the trace types and describes the information they provide.
Table 30. Trace types
Type of trace Trace contents
SI GUI, AEF, and CSS trace Output from Java classes. Good for tracing the startup of the SI GUI
and AEF classes.
Session trace Session information such as state changes, input data, traction events,
application XML, and SI GUI XML diagnostics.
Java I/O processor (JIOP) Output from the Java I/O processor such as keyboard, scanner, states
and 2x20 information from the JIOP.
Device manager trace Output from the device manager.

Trace file location

To facilitate troubleshooting the configuration and program execution problems, Store Integrator produces
trace logs in the C:\SILOGS directory. For SI GUI, the level of logging is determined by the log properties
file specified in the response file that starts the terminal (see Table 31 on page 93). For CSS (virtual
sessions), the level of logging is determined by the value specified in the aef.logger property in the
AEFLOAD.PRO file (see Table 19 on page 62).

Note: Setting your logging levels to FINE, FINER, or FINEST will degrade the system performance. See
“Java logging properties” on page 93 for additional information about these options.

You can configure your logging so that SILOG entries on both the 4690 and client machines trigger event
notifications to RMA. To enable this capability:
1. Set the create.SI.RMA.LogMonitor property in the config.properties bundle to true.
2. Select which log messages trigger events to RMA.

You can specify a log level and class (or package) name using the properties
SI.RMA.LogMonitor.include.x and SI.RMA.LogMonitor.exclude.x in the config.properties bundle.

Note:
1. The x on the previous include and exclude properties is a unique number. The include numbers are
separate from the exclude numbers so they can be identical.
2. You can specify as many include or exclude values as required. However, after a break of more than
five numbers in the sequence, SI ignores the subsequent entries.

The following example illustrates how you can use property settings to configure event notification on
all:
v INFO messages that occur within the POSAutomationProviderImpl class
v WARNING messages that occur within the automation package

91
Problem determination

v SEVERE messages, except those that occur within the AEFSessionImpl class.
create.SI.RMA.LogMonitor=true
SI.RMA.LogMonitor.include.0=WARNING,com.ibm.retail.AEF.automation
SI.RMA.LogMonitor.include.1=SEVERE
SI.RMA.LogMonitor.include.2=INFO,com.ibm.retail.AEF.automation.POSAutomationProviderImpl
SI.RMA.LogMonitor.exclude.0=SEVERE,com.ibm.retail.AEF.session.AEFSessionImpl

SI GUI traces
SI GUI log files are written to the C:\SILOGS directory. For a stand-alone terminal with a DHCP assigned
IP address, the file name is Tssss###.n, where ssss is the store number, ### is the terminal number and n
is a unique number (with 0 being the most recent). For a stand-alone terminal with a static IP address the
file name is termip.n where termip is the resolved IP name of the terminal and n is the unique number
(with 0 being the most recent).

Depending upon the logging level that you selected (see Table 31 on page 93), the system might generate
a second trace file. This file uses the same naming convention as described previously, but with an m
following the unique number. This log contains additional tracing that might assist in resolving a severe
error.

Minimal logging
The response files (see Table 31 on page 93) are set to use the SVLOG.PRO log property file in the
C:\ADX_IPGM directory for systems with SI GUI. These property files are set to log severe errors, with
the resulting trace file placed in the C:\SILOGS directory.

Moderate logging
For moderate logging, use the response files that have MID in their names (see Table 31 on page 93).
These response files are set to use the SVLOGMID.PRO log property file in the C:\ADX_IPGM directory
for systems with the SI GUI. These property files are set to log startup information, with the resulting
trace file placed in the C:\SILOGS directory.

Maximum logging
For maximum logging, use the response files that contain DBG in the name (see Table 31 on page 93).
These response files are set to use the SVLOGDBG.PRO log property file in the C:\ADX_IPGM directory
for systems with the SI GUI. These property files are set to log startup information, with the resulting
trace file placed in the C:\SILOGS directory, just as is done with the moderate logging.

Maximum logging captures all startup information, as well as any errors that could keep the SI GUI or
AEF from starting. If the SI GUI or AEF does not start and maximum logging does not provide enough
information to determine what the problem is, see “Redirecting standard error” on page 94.

CSS (virtual session) trace

CSS (virtual session) log files are also written to the C:\SILOGS directory for CSS running in Java 1.4.2.
For CSS running in Java 6, the CSS (virtual session) log files are written to the f:\si\logs directory. The
file format is Sxx.n, where xx is the controller node ID and n is a unique number (with 0 being the most
recent). Each controller that you defined to support virtual sessions has a separate set of logs.

Depending on the logging level that you selected, a second trace file might be generated. This file uses
the same naming convention as described previously, but with an m following the unique number. This
log contains additional tracing that might assist in resolving a severe error.

See Table 19 on page 62 for instructions on selecting the AEF logging level. Minimal, moderate or
maximum logging levels are available.

92 User's Guide: Store Integrator User's Guide

 Problem determination

Remote GUI trace

Trace files for the Remote GUI are written to the %SI_APP_DATA% for SI V3R5 and above directory.
These filenames are log_termnum.n.txt where termnum is the remote terminal number, and n is the unique
number (with 0 being the most recent).

POSBC trace
POSBC trace files are on the Windows machine in the %SI_HOME%\silogs directory. The file name for
the POSBC logs is posbc_log.# where # is a unique number (with 0 being the most recent).
Table 31. Mapping SI GUI response files to logging levels
Response file Logging properties file Logging level
OPER.RSP
OPERCT.RSP
CUST.RSP
SVLOG.PRO Minimal
CUSCT.RSP
DUALDISP.RSP
DDCT.RSP
OPERMID.RSP
OPRCTMID.RSP
CUSTMID.RSP
SVLOGMID.PRO Moderate
CSTCTMID.RSP
DUALMID.RSP
DDCTMID.RSP
OPERDBG.RSP
OPRCTDBG.RSP
CUSTDBG.RSP
SVLOGDBG.PRO Maximum
CSTCTDBG.RSP
DUALDBG.RSP
DDCTDBG.RSP

The default types of logging for Store Integrator are minimal, moderate, and maximum. If you have
problems starting the SI GUI, examine the trace file generated by moderate logging. If that log does not
provide enough information, use maximum logging.

Java logging properties

The current Store Integrator implementation uses the logging capabilities built into Java's JDK 1.4. The
log properties files are all modified copies of the default Java logging.properties file. For detailed
information on how to modify this file, see the Java JDK 1.4 documentation. To change the amount of
information being logged, change the level in each line that contains .level = to one of the following
values:
SEVERE
Extremely important messages that indicate conditions from which the program might not
recover, requiring immediate attention. This level is likely to be included in all log files or
consoles. SEVERE conditions include:
v Java exceptions
v Missing EALAEFXF.DAT or EAMAEFXF.DAT files

Chapter 8. Problem determination 93

Problem determination

v Missing property files

WARNING
Serious problems that might not require immediate attention, but should definitely be noted.
WARNING conditions include:
v Missing bundle keys or values
v Factory cannot create object messages
v Invalid values
v Condition lock timeouts which will include condition states
INFO Informational messages resulting from normal operation. This level is the default for loggers and
handlers, so INFO messages are seen during normal runs. INFO events include:
v Error Helper creation
v Error Helper handleError() return values
v AEFBase configuration
v Dump of the bundles which includes all the values from the property files
v Java health pipe creation
CONFIG
Informational messages about configuration or setup information, usually displayed at startup.
This level indicates what the program intends to do and how it will do it, rather than what it is
actually doing.
FINE Messages that provide greater detail for debugging and diagnosing problems. FINE information
includes:
v Automation call summary (for example, Operator 999999 logon called)
v SalesTransaction call summary (for example, Add item 3 (itemid toString())called).
v XML statements received from base application.
FINER
Messages providing even more detail for debugging and diagnosing problems. These log records
are so numerous that they are typically not logged unless it is absolutely necessary.
FINEST
Messages providing the most detail for debugging and diagnosing problems. These log records
are so numerous that they are typically not logged unless it is absolutely necessary. FINEST
records are generated when entering and leaving methods.

Note: Logging at this level will impact system performance, especially on larger session loads.
Prudent application of this level of logging is required.
ALL Enables logging of all records.
OFF Disables logging.

Redirecting standard error

Store Integrator (SI) sample application definitions, found on the SI installation CD in the JAVAAPP.XML
files, redirect both STDOUT and STDERR. See the following example:
<AdvancedSettings guiStartable="1" guiStoppable="1" launchOnStartup="1"
maxInstances="1" useJavaTOF="0" useSecondaryDisplay="0" jvmID="1"
redirectStdErr="r::c:/silogs/stderr.txt" redirectStdOut="r::c:/silogs/stdout.txt"/>

For additional information, see “Using OS 4690 Advanced Java Configuration and Bundling Instead of
.RSP files for the SI GUI application” on page 42.

All of the logging response files included with the SI application contain the following line:

94 User's Guide: Store Integrator User's Guide

 Problem determination

STDERR=r::C:/SILOGS/STDERR.TXT

When the $ parameter is specified, additional Java application output is written to the file specified.

When not using RSP files, see the 4690 OS Programming Guide for instructions on redirecting stderr and
stdout.

Session trace
Session trace information, such as states and application data, along with XML processing, is logged to
the session trace. If you are using an SI GUI terminal, you can access this trace by clicking on the
operator ID at the bottom of the SI GUI screen. Doing so displays a dialog where you can select Terminal
Trace. The session trace information is displayed in a dialog. Clicking Save in the dialog saves the session
trace to the C:\SILOGS directory, with the name SAVExxx.yyy, where xxx is the terminal number and yyy
is a rotating number from 0 to 999.

The session trace is also saved to a file automatically when a severe error occurs. When a severe error
occurs, the error is written to the session trace and the session trace is written to the C:\SILOGS directory
with a file name of AUTOterm.n, where term is the terminal number, and n is a unique number (with 0
being the most recent).

When severe errors occur on virtual sessions, the system automatically saves the session trace to a file.
The session trace is written to the C:\SILOGS directory with a file name of session#.n where session# is
the virtual session number and n is the unique number (with 0 being the most recent).

For the SI GUI and the Remote GUI, configuration for the trace (file pattern name, level, size, and so on)
is defined in the SV.properties file and can be overridden in CustSV.properties. Available settings include
(where term is the terminal number and n is a unique number, with 0 being the most recent):
trace.buffer.size=1000
trace.file.count=5
trace.file.pattern=R::C:/SILOGS/AUTOterm.n
trace.level=COARSE

The default size is set to 1000 log entries and wraps around when more than 1000 entries have been
logged. The default file count is 5. This means that you have no more than 5 session trace files produced
by a terminal at a given time. The default level is COARSE. To have application XML data included in
the session trace, set this to MEDIUM.

If you are in an AEF environment without the SI GUI, the trace files are controlled by the following lines
in the session.properties file and can be overwritten in the usersession.properties file. The following
example shows what a typical usersession.properties file looks like:
##
# LoggerControl and SessionTrace properties.
#
logger.remote.access=true
default.encoding=UTF-8
trace.buffer.size=1000
trace.file.count=10
trace.file.pattern= C:/silogs/term.n
#
# Set the trace level: FINE, MEDIUM, COARSE or DUMP
trace.level=COARSE
###

To see the trace data without the SI GUI, see the contents of the file C:/SILOGS/TERM.N (where TERM
is the terminal number and N is a unique number, with 0 being the most recent).

Chapter 8. Problem determination 95

Problem determination

Audit tracing
Currently, session trace logs from the SI GUI are only captured through manual interaction with the
Terminal Trace menu option. SI GUI, Remote GUI and virtual sessions can also create a session trace log
if a severe error occurs. You might not obtain a timely session trace if a problem occurs that is not severe
in SI terms. However, you can maintain the session trace logs for extended time frames in an automated
manner.

To enable this automated trace, create a usersession.properties with audit.trace.enable=true for SI GUI
terminals or virtual sessions. Then, during terminal and virtual session operation, the system creates the
C:\SILOGS\AUDITxxx.0, which logs the date, time, and history of the information in the Terminal Trace.

You can modify other properties in session.properties as needed:

###
# SessionAuditor properties.
# These properties control automatically writing
# the session trace to file. If the
# audit.trace.enabled is set to false,
# the session trace is only dumped to disk
# when there is a severe error logged.
#
# Valid trace levels: FINE, MEDIUM, COARSE or DUMP
#
#
audit.trace.enabled=false
audit.trace.file.size=1000000
audit.trace.file.count=10
audit.trace.file.pattern=R::C:/silogs/audit%n.%g
audit.trace.level=COARSE
audit.trace.append=true

Response and property files

The SI GUI can use any of three property files. When you start SI GUI, your choice of response file
determines which property file will be used (see Table 32).
Table 32. Property file selection for SI GUI
Response file Property file
CUSTMID.RSP
C:\ADX_IPGM\JCST1.PRO
CSTCTMID.RSP
OPERMID.RSP
C:\ADX_IPGM\J.PRO
OPRCTMID.RSP
DUALMID.RSP
C:\ADX_IPGM\DD.PRO
DDCT.RSP

Note: Table 32 lists the response files for moderate logging. The corresponding minimal and maximum
logging response files use the same property files.

The name of the property file is passed to the SI GUI as a startup parameter by using the -D option to
start the SI GUI. For example, the OPERCT.RSP response file contains the following parameter:
-Dprops=ADX_IPGM:J.PRO

The property files contain keyword=value pairs that can be used to produce additional debug and
problem-analysis data, such as enabling the JIOP trace (see “Java IO Processor (JIOP) trace” on page 97).

96 User's Guide: Store Integrator User's Guide

 Problem determination

Java IO Processor (JIOP) trace

The Java IO Processor can trace the internal workings of the IO processor, such as state transitions, key
sequences, and interaction with the POS application.

JIOP tracing through JDKLogging

The Toshiba Global Commerce Solutions supplied property files (see “Response and property files” on
page 96) are defined to allow JIOP traces to be collected through JDKLogging. This mode allows traces to
be collected in JVM memory and are made available to Toshiba Global Commerce Solutions support
through a terminal dump or through controller dump (for Controller/Terminal or CSS sessions). The JIOP
commands included in the property files that provide this support are:
JIOP.debugJDKLoggingInMemory=true
JIOP.debugJDKLoggingMaxRecords=1000

To write JDKLogging trace records to disk, you must implement Java code to dump the records to disk.
These code changes require that you use the JMX MBean interface, or the JIOProcessor's
pushJDKLoggingToDisk() method. After making these code changes the trace records are written by
default to the m:\java2 directory.

JIOP tracing through non-JDKLogging

An alternative to writing JIOP trace records to disk is to use the non-JDKLogging method. This approach
writes each JIOP record to disk in an interactive mode and therefore affects the performance of the
session. It is not recommended that this logging be used for production purposes.

To enable the JIOP trace, edit the appropriate property file (see “Response and property files” on page
96), comment out the JDKLogging commands, and add the JIOP.debug command:
## JIOP.debugJDKLoggingInMemory=true
## JIOP.debugJDKLoggingMaxRecords=1000
JIOP.debug=byterminal

This command creates a Jnnn.out file (where nnn is the terminal number) in the C:\SILOGS directory of
the controller that manages that terminal or session. To create a single file for all the terminals, use this
line:
JIOP.debug=r::c:\xxx

where xxx is the user specified log file name.

For more information on generating a JIOP trace, see the 4690 OS Programming Guide, (SC30-4048).

SYSDEFS.TXT
The SYSDEFS.TXT file redirects System.err.println("xx") and session trace messages so that they can be
read. This debugging tool was developed as part of the SureVision product, and continues to be available
to users of SI GUI. It combines logging similar to that of the Session Trace with system error logging, and
places its output in a single file. This allows the log data to be directed to a remote machine.

If a SYSDEFS.TXT file exists in the root of the 4690 controller, any System.err.println message can be
placed in a file by placing the following line in SYSDEFS.TXT:
systemerr=r::c:\\svoutnnn.txt

where nnn is the terminal number. Each terminal writes to a separate file named SVOUTnnn.TXT.

Optionally, these messages can be sent to any network accessible machine that has the RemoteConsole
class running on it by placing the following lines in SYSDEFS.TXT:

Chapter 8. Problem determination 97

Problem determination

remotehost=myhost
remoteport=8001
Systemerr=remote

where myhost is the host name or IP of the machine used to display the debug. To run the
RemoteConsole, copy the SUREVIEW.JAR file from C:\ADX_IPGM to a directory on your PC. Then run
the following command from that directory:
java -classpath .;sureview.jar; com.ibm.sureview.util.RemoteConsole port

where port matches the remoteport property in the SYSDEFS.TXT file.

Note: You must have Java 2 installed on your PC, and the PC must be configured to be part of the same
network as the controller or terminal.

Device Manager trace

The Device Manager trace is used to get detailed information from the Device Manager about the POS
devices. The default configuration for this type of trace is stored in com/ibm/retail/DevMgr/logging/
logging.properties. This file is delivered in OS4690.ZIP, which is part of the 4690 operating system.
Because OS4690.ZIP is listed in the classpath for the Store Integrator applications, the Device Manager
code will find it and initialize itself based on its contents. All Device Manager logging is disabled by
default.

To change the default logging behavior, create a modified version of com/ibm/retail/DevMgr/logging/

logging.properties (using the original as a model) and include it in a ZIP or JAR file that is ahead of
OS4690.ZIP in the classpath. It is recommended that the new com/ibm/retail/DevMgr/logging/
logging.properties file be zipped into USER.JAR. This JAR file is already referenced in the response files
provided for the GUI (such as OPERMID.RSP) or in the file that is used to start CSS (AEFVIRT.TXT).

This properties file must contain the following properties:

terminals
Defines which terminals have tracing enabled. Valid values for this property are none (the
default), all, or a range of terminal numbers. A range is specified as either a single integer
(example: 45) or two integers separated by a hyphen (example: 37-42).
AllDevices
Enables or disables tracing for all devices. Valid values are true and false.

Tracing can be enabled and disabled on a per-device basis. Properties exist for each device. Each property
can be set to true or false. The device properties are:
v IOProcessor
v ANDisplay1
v ANDisplay2
v ANDisplay3
v CashReceipt
v MethodInvocation
v MSR
v CashDrawer
v DocumentInsert
v SummaryJournal
v ToneIndicator
v NVRAM
v SerialPort1

98 User's Guide: Store Integrator User's Guide

 Problem determination

v SerialPort2
v SerialPort3
v SerialPort4
v Scale
v Video
v ApplicationServices

System properties
Any property in the properties file can be overridden using a system property. To override a setting in
the properties file, define a system property with com.ibm.retail.DevMgr.logging followed by the
property name. For example, to turn on tracing for the scale without modifying a properties file, specify
the following line in the JVM invocation:
-Dcom.ibm.retail.DevMgr.logging.Scale=true

Trace output
The logging output is directed to C:\SILOGS by the log properties file. The handler configured for the
DeviceManager logging must be set to level FINE, FINER, or FINEST for the device trace to be seen. Use
the moderate-logging version of the response files during normal operations. This means that the default
logging level is INFO, so the DeviceManager trace is not active. To activate the DeviceManager trace, use
the maximum-logging version of the response files. The file naming conventions for trace output in
C:\SILOGS for the Device Manager are the same as for the AEF and GUI trace (see “Maximum logging”
on page 92).

VIRTOUT.nn and VIRTERR.nn

The C:\SILOGS\VIRTOUT.NN and C:\SILOGS\VIRTERR.NN files are controlled by the CSS
initialization driver. The naming scheme is hard-coded, and these files are always created to catch the
stdout and stderr for the CSS Virtual-Session JVM. To enable the user to access the most recent versions
of VIRTOUT.NN and VIRTERR.NN, the CSS init driver generates a new version of C:\ADX_SPGM\
TERR.BAT and C:\ADX_SPGM\TOUT.BAT before starting the session. These batch files point to the
current log files and can be used to view them.

Further logging from CSS virtual sessions using a standard JDK logger is directed in accordance with the
settings in the log properties file that is specified in the CSS command file. For example, the properties
file AEFLOAD.PRO references the property file SMIDLOGS.PRO, which directs the log output to
C:\SILOGS. Within this directory, the log file has the name Snn.x, where nn is the controller node and x is
a unique identifying number. This file contains logging information about the creation of virtual sessions,
including any errors that occurred during the creation of these sessions or the initialization of the CSS
server.

GSA XML strings

The GSA application can be configured to log all the messages sent to AEF into a log file. These files are
created in the ADX_UDT1: directory. The name of each log file is $$AEFxxx.Lnn, where xxx is the
terminal number and nn is an integer from 00 to 20. The files with the L00 extension contain the latest set
of logs.

To enable this feature, edit EALAEFC.BAS and change this line:

%define logForDebug 0

so that it reads as follows:

%define logForDebug 1

Chapter 8. Problem determination 99

Problem determination

This XML string logging capability is unique to GSA. No equivalent capability is available for ACE or SA.

Stop sign errors

When SI GUI has experienced an internal error, it displays a pop-up message containing a stop sign icon
along with the text A system error has occurred... If the panel contains a status bar, a flashing system
error alert warning is displayed in the lower right corner. When an internal error occurs, a session trace
file is written on the controller in the C:\SILOGS directory. For more information, see “Session trace” on
page 95.

Trace logs
If you previously used SureVision, note that the TRACExxx.yyy logging mechanism has been replaced
with the session trace logging mechanism described in “Session trace” on page 95.

RMA Data Capture for Virtual Sessions

Note: This section assumes a working knowledge of data capture using Toshiba’s Remote Management
Agent and IBM Director. For more information on configuring and executing data captures using RMA,
please see the Remote Management Agent Users’ Guide,.

Store Integrator provides a VirtualSessionDataCapture MBean that allows users to collect important
problem analysis information for virtual sessions using Toshiba's Remote Management Agent. When
initiated, the VirtualSessionDataCapture MBean will cause Store Integrator’s Client Session Server to output
the most current problem analysis information. The MBean then collects the information in a zip file and
transfers it to the Master Agent.

The VirtualSessionDataCapture MBean captures the following information:

v VIRTOUT.nn
v VIRTERR.nn
v Session Traces
– The MBean can only output new session traces from sessions that are currently active. However, any
session traces that exist in the SILOGS directory because of a prior failure will be collected during
the capture even if the session isn’t currently active.

Note: The MBean will collect every session trace that exists in the SILOGS directory, including any
that existed prior to the MBean's execution.
v All CSS Trace files

Note: The MBean will force CSS to write its most recent memory trace file (Sxx.nm) to disk before
collecting the problem analysis information.
v A JVM Javacore dump

Data Capture Parameters

The VirtualSessionDataCapture MBean allows users to input parameters to control which virtual sessions
will output new session trace information before the problem analysis information is collected. The
MBean can only output new session traces from sessions that are currently active. The parameters are:
v null
– All currently active sessions will write their session traces to disk
v nnn (where nnn is a 1-3 digit integer)
– A single session whose number matches the parameter will write its session trace to disk
v nnn-nnn (where nnn is a 1-3 digit integer)

100 User's Guide: Store Integrator User's Guide

 Problem determination

– A range of sessions between the two input numbers will write their session traces to disk
v nnn,nnn,...,nnn (where nnn is a 1-3 digit integer)
– Sessions whose numbers match each individual input integer will write their session traces to disk
– This comma delimited list can contain a combination of individual sessions and ranges of sessions

Troubleshooting common problems

Store Integrator components for 4690 OS controllers and Windows Client machines are delivered on a
single CD, which is used for all of the installation procedures in this guide. The AEF JAR files on the
4690 controller and on the client must always be at the same level (which occurs automatically if both
sets of files are obtained from the same CD). A mismatch in JAR files can cause RMI exceptions and other
unpredictable results. Therefore, when updates of the software become available, you must upgrade the
4690 OS and Windows Client software simultaneously so that the levels of each always match.
Table 33. Troubleshooting errors
Error (xxx is the session number) Action
SEVERE: xxx:SequencedOutputManager.run output error, This error can occur when the connection to the
PO/WO/N 0/2/1 controller is lost. No action required.
com.ibm.OS4690.POSPrinterHandlerException: Device is
This error can also occur when switching back to the
off line or not responding.
primary controller after a failover. No action required.
Your POS application has terminated. You will receive this message if your terminal has been
disconnected from the network for 60 seconds.
Investigate the reasons for the disconnected network.
SEVERE: Unsupported Java JRE in use. The Java Store Integrator will only run with IBM's version 1.6 of
Runtime Environment must be the IBM JRE Version 1.6 the Java Runtime Environment. Using any other version,
or Java Runtime Environment vendor, will yield this
message, to which the only solution is to use the
supported Java Runtime Environment version.

POSBC limitations
This section describes the following POSBC limitations.

Recovering transactions
Currently, a POSBC limitation exists when recovering transactions using full failover. Whenever the
POSBC is in the middle of an AEF method call and the connection to the AEF is lost, the POSBC will
change to INCONSISTENT_STATE. When in this state, the transaction can be queried using the
QueryStatus request, but transactional operations are not allowed, including adding and voiding items,
coupons, and tenders. To recover the POSBC from an INCONSISTENT_STATE, send an Initialize
request with the recovery flag set to false, which will clear out the current transaction. This means that
if a session has a pending AEF method call response when a controller is shut off, then the failed-over
transaction will be unavailable for continued use from within POSBC. For POSBC clients, which do not
store transaction information, the result will be a lost transaction.

Handling of requests
After the POSBC client receives the POS_SESSION_SWITCHBACK_IN_PROGRESS event, it ignores all
incomplete requests. Communication resumes after the 'POS_CONNECTION_RESTORED' event is
received.

Empty Log File

When migrating from a prior level of Store Integrator, the POSBC's sidbg.properties file is not modified.
This can cause the POSBC to exit immediately after execution without writing any log messages if the
POSBC is run on an unsupported version of the Java Runtime Environment. To fix the problem, run the
POSBC with the supported Java Runtime Environment.

Chapter 8. Problem determination 101

Problem determination

Outdated files on the RAM disk

If you configure:
v your virtual sessions to load from the controller RAM disk, and
v the ACE application to take advantage of the controller RAM disk,
beware of outdated files that might load by an user-defined overlay file. Virtual sessions can continue to
load from the controller RAM disk using a terminal-specific file (such as an options file), when that file
was deleted by the application.

It is your responsibility to remove any files from the controller RAM disk that no longer exist.

JavaPOS Device in Use

In the event that a JavaPOS device is in use when the SI GUI is launched (printer is flashing), you will
receive a notification dialog that prompts you: "A point of sale device is being used by another
application. Please wait..." You must wait until the other application finishes using the device so the SI
GUI can open the device.

102 User's Guide: Store Integrator User's Guide

Appendix A. Primary application parameters
Applications such as SA and ACE were originally given hooks to send events to a Java customer display.
The SureVision PRPQ used these hooks, as well as additional events. AEF uses all of those hooks plus
some additional ones, but sends the information in an XML format. As a result under AEF, up to three
sets of hooks can be active, depending on the POS application used. Table 34 indicates which hooks are
potentially active for each application.

Contact the integrator of other POS applications for information on parameters and specific hooks used
by the application.
Table 34. Potentially active hooks
Hook Application
ACE GSA SA
Value Pack (for customer U U
display)
SureVision PRPQ U U U
AEF U U U

To determine which hooks should be active, the Terminal Load Definition passes arguments to the base
application using the application parameter field in the Primary Application panel. If no parameters are
specified, then the default values of A1 G0 B1 T0 are used. The syntax of the command tail is:
An Gn Bn Tn i1

where n is a single digit. Table 35 lists the valid values for these parameters.
Table 35. Parameter values for hook activation
Parameter Value of n Result
(ACE/SA) Fn Valid 0 The terminal session is not running in failover.
for virtual sessions
1 The terminal session is running in failover.
only.
2 The terminal session is running in standby mode.
An 0 AEF data hooks are not called.
1 AEF data hooks are called.
Gn 0 Value Pak customer display hooks are not called. SureVision PRPQ
hooks are not called.
1 Value Pak customer display hooks are called. (Does not apply to
GSA.)
2 Value Pak customer display and SureVision PRPQ hooks are called.
Bn 0 Hook does not block if the JVM is not available. The Java call to pass
the data is skipped.
1 Hook blocks until the JVM is available to pass the data.
Tn 0 Application does not run under control of CSS.
1 Application runs under control of CSS (a virtual terminal session).
Note: Not valid for physical terminals.
(ACE only) in 1 Activates the full screen ACE display and the AEF hooks.

103
Primary application parameters

Note:
1. ACE looks only at the T and B and F values. To specify AEF and GUI values in ACE, use the
appropriate terminal sales application file.
2. In the case of virtual terminals, AEF passes the parameter information. The terminal load definition is
not required.

104 User's Guide: Store Integrator User's Guide

Appendix B. Optimizing Store Integrator performance
All of the Store Integration settings have default settings at installation time that provide good
performance in most situations. However, the default settings might have been changed during problem
debugging or previous tuning efforts. Other settings might no longer be appropriate for a store's
changing activity profile. In either case, the following settings should be checked and updated to ensure
good performance of Store Integrator.

Controller settings in AEFVIRT.TXT

Controller settings for the Store Integrator can be set optionally in various properties files, but can be
overridden by command line flags in C:\ADX_IPGM\AEFVIRT.TXT.

JIT Compiler
The performance of CSS can be improved for Store Integrator Version 3 Release 2 and later releases by
enabling the Java JIT compiler.
-Djava.compiler=jitc -DMIN_SPARE_PERCENT=12

Enabling these options will change both the performance and resource requirements of the system. For
more information about Store Integrator resource requirements, please refer to the Knowledgebase Search
at www.toshibagcs.com/support Web site and search on SI resource requirements.

JVM heap size

v Set Initial Java Heap Size to -Xms32m.
The minimum heap size can be tuned to the size required after initialization. For example, a 50-session
box should start out with a much higher size to speed up creation of sessions.
v Set Maximum Java Heap Size to -Xmx128m.
The maximum heap size on the 4690 is limited to 240 Mb

Terminal settings
Terminal settings are controlled in the response file used to specify the terminal application (for example,
OPER.RSP). The primary performance-related setting is the JVM heap size:
-Xmx48m –Xms32m

Device Manager tracing is not typically enabled, but might have been activated during problem
determination. If there is any doubt as to whether Device Manager tracing has been enabled, the setting
can be overridden in the terminal response file:
-Dcom.ibm.retail.DevMgr.logging.AllDevices=false

Optimizing OS 4690 performance

More detailed general guidelines and tuning considerations for OS 4690 are available at the Retail Store
Solutions Technical Software Support Web site at www.toshibacommerce.com/support. Click
Performance documents from the navigation list and then expand the index to view the list of 4690
performance white papers that are available.

105
Optimizing Store Integrator performance

Disk balancing
If you have more than one disk drive on your 4690 controller, you might be able to improve performance
by balancing the disk activity of the POS Checkout Support (Controller Sales) Program, the Data
Integration Facility (if present), and any other application programs running on your controller. Similar
benefits might be possible on an in-store processor.

Checkout Support and Data Integration Facility

On a controller that supports both Checkout Support and Data Integration Facility, it is important to
balance the disk activity across two physical disks: Both of these processes are disk-intensive tasks.
Detailed disk balancing guidelines for POS applications can be found in several Toshiba Global
Commerce Solutions publications (see Table 36).
Table 36. Resources for disk balancing
Application Publication Section
SurePOS Application Client/Server Environment Using a dual drive controller
for 4690 OS Planning and Installation Guide
ACE
Toshiba Global Commerce Solutions Web SurePOS ACE 2.0 performance expectations
site1
4680-4690 General Sales Application Planning Placing data files on a dual drive controller
GSA
and Installation Guide system
4680-4690 Supermarket Application Planning Using a dual drive controller
SA
and Installation Guide
1
www.toshibacommerce.com

Note: Other POS applications may have similar guidelines. Contact the application integrator.

In-store processor
If the applications running on your in-store processor cause intensive disk activity, you might be able to
improve performance by analyzing the activity and redistributing your files to better balance the load. At
a minimum, you should install Java, WebSphere Application Server (if installed) on a second disk
(separate from the OS, paging, tmp, and filesystems that are used heavily by other background in-store
applications).

Logo printing on Remote GUI (ACE)

Logo images higher than 216 pixels print at reduced speed. For best logo printing performance on a
Remote GUI (ACE) system, ensure that logo images are no larger than 576 pixels wide and 216 pixels
high.

106 User's Guide: Store Integrator User's Guide

Appendix C. Store Integrator SSL certificate update
instructions
SI can use SSL sockets for communication, so that data is encrypted when transmitted. The default
sample certificates are used for the POS Controller and the Remote GUI clients that communicate with
the POS via AEF and for POSBC clients that communicate with the JIF server (e.g. Windows CHEC
Lanes). To maximize security, the certificates should be changed so that the default set of certificates are
not used. When updating the certificates, all certificates at the endpoints must be updated or else
communication errors will occur.

Here are the steps to create a new key store and trust store with a new certificate. In the instructions
below, replace "CustomKeys_PW" and "CustomStore_PW" with values of your choosing. The validity period
of "365" can be changed if desired; the example below uses "365" to create a certificate that is valid for a
year. The filenames of ”custkeys” and ”custstor” can also be changed but this is not necessary. If
”custkeys” or ”custstor” is changed, the filename is limited to only eight characters because of filename
limitations of the operating system on the Toshiba 4690 POS. Note that the aliases "rss" and "rsscert"
must not be changed and the procedure must be carried out on a 4690 controller.

Generating a new certificate

1. On the 4690 controller, go to Command Mode (option 7).
2. Generate a new keystore with a single key by running:
keytool -genkey -alias rss -keyalg RSA -validity 365 -keystore custkeys -storepass CustomKeys_PW
The program will prompt for information to put in the certificate, such as the organization name.
Answer these prompts appropriately. When prompted to "Enter key password for <rss>: " only hit
<Enter>; do not enter a new password.
3. (Optional) You can view the contents of the key store by running:
keytool -list -v -keystore custkeys -storepass CustomKeys_PW
4. Export the certificate to a temporary file by running:
keytool -export -alias rss -keystore custkeys -rfc -file custkeys.cer -storepass CustomKeys_PW
5. Generate a new trust store based on the previously-created key by running:
keytool -import -alias rsscert -file custkeys.cer -keystore custstor -storepass CustomStore_PW
When prompted to "Trust this certificate? [no]: " type "yes" and hit <Enter>.
6. Copy the custkeys and custstor files to the following locations:

Toshiba 4690 POS: C:\adx_idt1

SI V3R4 and earlier
Windows Remote GUI and JIF server: %SI_HOME%/security
SI V3R5 and later
Windows Remote GUI and JIF server: %SI_APP_DATA%/security

Using the new certificate

On the Toshiba 4690 POS, do the following :

Note: If the store has more than one controller, the files should be edited on the Master File Server and
then distributed to the other controllers using the 4690 file distribution utility.

107
 1. Locate a sistoressl.properties file, if it exists. To do this, first go to the Command Prompt and
create a temporary working directory (for example: temp) on the M drive:
M:
mkdir temp
cd temp
2. Attempt to extract sistoressl.properties from one of its likely locations:
jar –xf C:\adx_ipgm\siuser.jar sistoressl.properties or
jar –xf C:\adx_ipgm\sistore.jar sistoressl.properties

Note: "jar" (Java ARchive tool) is an archiving and compression tool based on ZIP along with the
ZLIB compression format used to combine several files into a single archive. It is part of Java2 in the
4690 OS. It may be necessary to type "java2sdk:jar" rather than "jar" as shown above.)
3. Create the sistoressl.properties file if it was not extracted in the previous step.
4. Modify or add the following properties as shown:
AEF.ServerKeyFileName=c:\\adx_idt1\\custkeys
AEF.ServerTrustFileName=c:\\adx_idt1\\custstor
AEF.ServerKeyPassword=CustomKeys_PW
AEF.ServerTrustPassword=CustomStore_PW
5. Secure the passwords in this file by running the following command:
C:\adx_ipgm\SiSecure sistoressl.properties -regex .*Password

After encryption, the password entries in the file will appear like:
AEF.ServerKeyPassword_encrypted=E5006D6E6E84898F80828D7C8F8A8D3B3B3B
6. If sistoressl.properties was not extracted from an existing jar file in Step 2, skip to Step 9.
Otherwise, to update the jar file, first create a temporary working directory (for example: jartemp)
and change to that directory:
mkdir jartemp
cd jartemp
7. Extract the contents of the jar file to this directory. Choose the appropriate command:
jar –xf C:\adx_ipgm\siuser.jar or
jar –xf C:\adx_ipgm\sistore.jar
8. Overwrite the extracted sistoressl.properties with the updated sistoressl.properties from Step
4:
copy M:\temp\sistoressl.properties sistoressl.properties
9. Stop CSS so that the necessary jar file can be updated. Do this by running:
ADXCSS1L STOP
10. If sistoressl.properties was extracted from an existing jar file in Step 2, overwrite the jar file using
the appropriate one of the following steps:
jar –cf C:\adx_ipgm\siuser.jar *.* or
jar –cf C:\adx_ipgm\sistore.jar *.*
11. If an existing jar file was not updated in the previous step, then create it:
jar –cf C:\adx_ipgm\sistore.jar sistoressl.properties
12. Restart CSS by entering the following in a command window:
ADXCSS1L START

108 User's Guide: Store Integrator User's Guide

On the Windows Remote GUI system and JIF server systems, do the following:
1. SI V3R4 and earlier, edit the following file:
%SI_HOME%\security\siterminalssl.properties

SI V3R5 and later, edit the following file:

%SI_APP_DATA%\security\siterminalssl.properties
2. Modify or add the following properties as shown:

Note: The path to the KeyFileName and TrustFileName may be C:\\Program Files\\IBM\\
StoreIntegrator\\security on systems migrated to newer versions.)
AEF.KeyFileName=C:\\Program Files\\Toshiba\\StoreIntegrator\\security\\custkeys
AEF.TrustFileName=C:\\Program Files\\Toshiba\\StoreIntegrator\\security\\custstor
AEF.KeyPassword=CustomKeys_PW
AEF.TrustPassword=CustomStore_PW
3. Secure the passwords in this file by running the following command:
On SI V3R4 and earlier,
"%COMMON_HOME%"\SiSecure "%SI_HOME%"\security\siterminalssl.properties -regex .*Password

On SI V3R5 and later,

"%COMMON_HOME%"\SiSecure "%SI_AP_DATA%"\security\siterminalssl.properties -regex .*Password

After encryption, the password entries in the file will appear like:
AEF.KeyPassword_encrypted=E5006D6E6E84898F80828D7C8F8A8D3B3B3B
4. Restart the Remote GUI or JIF server using the appropriate batch file.

Appendix C. Store Integrator SSL certificate update instructions 109

110 User's Guide: Store Integrator User's Guide
Notices
This information was developed for products and services offered in the U.S.A.

Toshiba Global Commerce Solutions may not offer the products, services, or features discussed in this
document in other countries. Consult your local Toshiba Global Commerce Solutions representative for
information on the products and services currently available in your area. Any reference to a Toshiba
Global Commerce Solutions product, program, or service is not intended to state or imply that only that
Toshiba Global Commerce Solutions product, program, or service may be used. Any functionally
equivalent product, program, or service that does not infringe any Toshiba Global Commerce Solutions
intellectual property right may be used instead. However, it is the user's responsibility to evaluate and
verify the operation of any non-Toshiba Global Commerce Solutions product, program, or service.

Toshiba Global Commerce Solutions may have patents or pending patent applications covering the
subject matter in this document. The furnishing of this document does not give you any license to these
patents. You can send license inquiries, in writing, to:

Toshiba Global Commerce Solutions

Attn: General Counsel
3039 E. Cornwallis Rd.
RTP, NC 27709
U.S.A.

The following paragraph does not apply to the United Kingdom or any other country where such
provisions are inconsistent with local law: TOSHIBA GLOBAL COMMERCE SOLUTIONS PROVIDES
THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer
of express or implied warranties in certain transactions, therefore, this statement may not apply to you.

This information could include technical inaccuracies or typographical errors. Changes are periodically
made to the information herein; these changes will be incorporated in new editions of the publication.
Toshiba Global Commerce Solutions may make improvements and/or changes in the product(s) and/or
program(s) described in this publication at any time without notice.

Toshiba Global Commerce Solutions may use or distribute any of the information you supply in any way
it believes appropriate without incurring any obligation to you.

Any references in this information to non-Toshiba Global Commerce Solutions Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at
those Web sites are not part of the materials for this Toshiba Global Commerce Solutions product and use
of those Web sites is at your own risk.

Information concerning non-Toshiba Global Commerce Solutions products was obtained from the
suppliers of those products, their published announcements or other publicly available sources. Toshiba
Global Commerce Solutions has not tested those products and cannot confirm the accuracy of
performance, compatibility or any other claims related to non-Toshiba Global Commerce Solutions
products. Questions on the capabilities of non-Toshiba Global Commerce Solutions products should be
addressed to the suppliers of those products.

This information is for planning purposes only. The information herein is subject to change before the
products described become available.

111
Telecommunication regulatory statement
This product is not intended to be connected directly or indirectly by any means whatsoever to interfaces
of public telecommunications networks, nor is it intended to be used in a public services network.

Electronic emission notices

When you attach a monitor to the equipment, you must use the designated monitor cable and any
interference suppression devices that are supplied with the monitor.

Federal Communications Commission statement

This equipment has been tested and found to comply with the limits for a Class A digital device,
pursuant to Part 15 of the FCC Rules. These limits are designed to provide reasonable protection against
harmful interference when the equipment is operated in a commercial environment. This equipment
generates, uses, and can radiate radio frequency energy and, if not installed and used in accordance with
the instruction manual, may cause harmful interference to radio communications. Operation of this
equipment in a residential area is likely to cause harmful interference, in which case the user will be
required to correct the interference at his own expense.

Properly shielded and grounded cables and connectors must be used in order to meet FCC emission
limits. Toshiba Global Commerce Solutions is not responsible for any radio or television interference
caused by using other than recommended cables and connectors or by unauthorized changes or
modifications to this equipment. Unauthorized changes or modifications could void the user's authority
to operate the equipment.

This device complies with part 15 of the FCC Rules. Operation is subject to the following two conditions:
1. This device may not cause harmful interference, and
2. This device must accept any interference received, including interference that may cause undesired
operation.

Industry Canada Class A Emission Compliance statement

This Class A digital apparatus complies with Canadian ICES-003.

Avis de conformité à la réglementation d'Industrie Canada

Cet appareil numérique de la classe A est conforme à la norme NMB-003 du Canada.

European Union Electromagnetic Compatibility (EMC) Directive

Conformance Statement
This product is in conformity with the protection requirements of EU Council Directive 2004/108/EC on
the approximation of the laws of the Member States relating to electromagnetic compatibility. Toshiba
Global Commerce Solutions cannot accept responsibility for any failure to satisfy the protection
requirements resulting from a non-recommended modification of the product, including the fitting of
non-Toshiba Global Commerce Solutions option cards.

This product has been tested and found to comply with the limits for Class A Information Technology
Equipment according to CISPR 22/European Standard EN 55022. The limits for Class A equipment were
derived for commercial and industrial environments to provide reasonable protection against interference
with licensed communication equipment.

Attention: This is a Class A product. In a domestic environment this product may cause radio
interference, in which case the user may be required to take adequate measures.

Responsible manufacturer:

112 User's Guide: Store Integrator User's Guide

Toshiba Global Commerce Solutions
3039 Cornwallis Road
Building 307
Research Triangle Park, North Carolina 27709
United States of America

European Community contact:

Toshiba Global Commerce Solutions

Brand Manager - Europe, Middle East & Africa
3 NEW SQUARE, FELTHAM, TW14 8HB Great Britain
Building: | Floor: NA | Office: MOBILE
Tel: 44-7967-275819
e-mail: [email protected]

European Community (EC) Mark of Conformity Statement

This product is in conformity with the protection requirements of EC Council Directive 89/336/EEC on
the approximation of the laws of the Member States relating to electromagnetic compatibility. Toshiba
Global Commerce Solutions cannot accept responsibility for any failure to satisfy the protection
requirements resulting from a non-recommended modification of the product, including the fitting of
non-Toshiba Global Commerce Solutions option cards.

This product has been tested and found to comply with the limits for Class A Information Technology
Equipment according to CISPR 22/European Standard EN 55022. The limits for Class A equipment were
derived for commercial and industrial environments to provide reasonable protection against interference
with licensed communication equipment.

Warning: This is a Class A product. In a domestic environment this product may cause radio interference,
in which case the user may be required to take adequate measures.

Germany Class A statement

Deutschsprachiger EU Hinweis: Hinweis für Geräte der Klasse A EU-Richtlinie zur
Elektromagnetischen Verträglichkeit

Dieses Produkt entspricht den Schutzanforderungen der EU-Richtlinie 2004/108/EG zur Angleichung der
Rechtsvorschriften über die elektromagnetische Verträglichkeit in den EU-Mitgliedsstaaten und hält die
Grenzwerte der EN 55022 Klasse A ein.

Um dieses sicherzustellen, sind die Geräte wie in den Handbüchern beschrieben zu installieren und zu
betreiben. Des Weiteren dürfen auch nur von der Toshiba Global Commerce Solutions empfohlene Kabel
angeschlossen werden. Toshiba Global Commerce Solutions übernimmt keine Verantwortung für die
Einhaltung der Schutzanforderungen, wenn das Produkt ohne Zustimmung der Toshiba Global
Commerce Solutions verändert bzw. wenn Erweiterungskomponenten von Fremdherstellern ohne
Empfehlung der Toshiba Global Commerce Solutions gesteckt/eingebaut werden.

EN 55022 Klasse A Geräte müssen mit folgendem Warnhinweis versehen werden: “Warnung: Dieses ist
eine Einrichtung der Klasse A. Diese Einrichtung kann im Wohnbereich Funk-Störungen verursachen; in
diesem Fall kann vom Betreiber verlangt werden, angemessene Maβnahmen zu ergreifen und dafür
aufzukommen.”

Deutschland: Einhaltung des Gesetzes über die elektromagnetische Verträglichkeit von Geräten

Dieses Produkt entspricht dem “Gesetz über die elektromagnetische Verträglichkeit von Geräten
(EMVG)”. Dies ist die Umsetzung der EU-Richtlinie 2004/108/EG in der Bundesrepublik Deutschland.

Notices 113
Zulassungsbescheinigung laut dem Deutschen Gesetz über die elektromagnetische Verträglichkeit von
Geräten (EMVG) (bzw. der EMC EG Richtlinie 2004/108/EG) für Geräte der Klasse A

Dieses Gerät ist berechtigt, in Übereinstimmung mit dem Deutschen EMVG das EG-Konformitätszeichen
- CE - zu führen.

Verantwortlich für die Einhaltung der EMV Vorschriften ist der Hersteller:

Toshiba Global Commerce Solutions

3039 Cornwallis Road
Building 307
Research Triangle Park, North Carolina 27709
United States of America

Der verantwortliche Ansprechpartner des Herstellers in der EU ist:

Toshiba Global Commerce Solutions

Brand Manager - Europe, Middle East & Africa
3 NEW SQUARE, FELTHAM, TW14 8HB Great Britain
Building: | Floor: NA | Office: MOBILE
Tel: 44-7967-275819
e-mail: [email protected]

Generelle Informationen:

Das Gerät erfüllt die Schutzanforderungen nach EN 55024 und EN 55022 Klasse A.

Australia and New Zealand Class A statement

Attention: This is a Class A product. In a domestic environment this product may cause radio
interference, in which case the user may be required to take adequate measures.

People's Republic of China Class A electronic emission statement

Attention: This is a Class A product. In a domestic environment this product may cause radio
interference, in which case the user may be required to take adequate measures.

Russian Electromagnetic Interference (EMI) Class A statement

Japanese Electrical Appliance and Material Safety Law statement

114 User's Guide: Store Integrator User's Guide

Japanese power line harmonics compliance statement

Japan Voluntary Control Council for Interference Class A statement

Attention: This is a Class A product based on the standard of the Voluntary Control Council for
Interference (VCCI). If this equipment is used in a domestic environment, radio interference may occur, in
which case, the user may be required to take corrective actions.

Japan Electronics and Information Technology Industries Association

(JEITA) statement

Japan Electronics and Information Technology Industries Association (JEITA) Confirmed Harmonics
Guidelines with Modifications (products greater than 20 A per phase).

Korean communications statement

Please note that this device has been approved for business purposes with regard to electromagnetic
interference (Type A). If you find this is not suitable for your use, you may exchange it for a non-business
purpose one.

Taiwanese Class A compliance statement

Notices 115
Cable ferrite requirement
All cable ferrites are required to suppress radiated EMI emissions and must not be removed.

Electrostatic discharge (ESD)

Attention: Electrostatic discharge (ESD) damage can occur when there is a difference in charge between
the part, the product, and the service person. No damage will occur if the service person and the part
being installed are at the same charge level.

ESD damage prevention

Anytime a service action involves physical contact with logic cards, modules, back-panel pins, or other
ESD sensitive (ESDS) parts, the service person must be connected to an ESD common ground point on
the product through the ESD wrist strap and cord.

The ESD ground clip can be attached to any frame ground, ground braid, green wire ground, or the
round ground prong on the AC power plug. Coax or connector outside shells can also be used.

Handling removed cards

Logic cards removed from a product should be placed in ESD protective containers. No other object
should be allowed inside the ESD container with the logic card. Attach tags or reports that must
accompany the card to the outside of the container.

Product recycling and disposal

This unit must be recycled or discarded according to applicable local and national regulations. Toshiba
Global Commerce Solutions encourages owners of information technology (IT) equipment to responsibly
recycle their equipment when it is no longer needed. Toshiba Global Commerce Solutions offers a variety
of product return programs and services in several countries to assist equipment owners in recycling their
IT products. Information on Toshiba Global Commerce Solutions product recycling offerings can be found
on the Toshiba Global Commerce Solutions product recycling programs website.

Español: Esta unidad debe reciclarse o desecharse de acuerdo con lo establecido en la normativa nacional
o local aplicable. Toshiba Global Commerce Solutions recomienda a los propietarios de equipos de
tecnología de la información (TI) que reciclen responsablemente sus equipos cuando éstos ya no les sean
útiles. Toshiba Global Commerce Solutions dispone de una serie de programas y servicios de devolución
de productos en varios países, a fín de ayudar a los propietarios de equipos a reciclar sus productos de
TI. Se puede encontrar información sobre las ofertas de reciclado de productos de Toshiba Global
Commerce Solutions en el sitio web Toshiba Global Commerce Solutions product recycling programs.

Notice: This mark applies only to countries within the European Union (EU) and Norway.

Appliances are labeled in accordance with European Directive 2002/96/EC concerning waste electrical
and electronic equipment (WEEE). The Directive determines the framework for the return and recycling
of used appliances as applicable throughout the European Union. This label is applied to various
products to indicate that the product is not to be thrown away, but rather reclaimed upon end of life per
this Directive.

116 User's Guide: Store Integrator User's Guide

Remarque : Cette marque s’applique uniquement aux pays de l’Union Européenne et à la Norvège.
L’etiquette du système respecte la Directive européenne 2002/96/EC en matière de Déchets des
Equipements Electriques et Electroniques (DEEE), qui détermine les dispositions de retour et de recyclage
applicables aux systèmes utilisés à travers l’Union européenne. Conformément à la directive, ladite
étiquette précise que le produit sur lequel elle est apposée ne doit pas être jeté mais être récupéré en fin
de vie.

In accordance with the European WEEE Directive, electrical and electronic equipment (EEE) is to be
collected separately and to be reused, recycled, or recovered at end of life. Users of EEE with the WEEE
marking per Annex IV of the WEEE Directive, as shown above, must not dispose of end of life EEE as
unsorted municipal waste, but use the collection framework available to customers for the return,
recycling, and recovery of WEEE. Customer participation is important to minimize any potential effects of
EEE on the environment and human health due to the potential presence of hazardous substances in EEE.
For proper collection and treatment, contact your local Toshiba Global Commerce Solutions
representative.

Disposal of IT products should be in accordance with local ordinances and regulations.

Battery return program

This product may contain sealed lead acid, nickel cadmium, nickel metal hydride, lithium, or lithium ion
battery. Consult your user manual or service manual for specific battery information. The battery must be
recycled or disposed of properly. Recycling facilities may not be available in your area. For information
on disposal of batteries outside the United States, go to the Battery disposal website or contact your local
waste disposal facility.

For Taiwan:

Please recycle batteries.

For the European Union:

Notice: This mark applies only to countries within the European Union (EU)

Notices 117
Batteries or packaging for batteries are labeled in accordance with European Directive 2006/66/EC
concerning batteries and accumulators and waste batteries and accumulators. The Directive determines
the framework for the return and recycling of used batteries and accumulators as applicable throughout
the European Union. This label is applied to various batteries to indicate that the battery is not to be
thrown away, but rather reclaimed upon end of life per this Directive.

Les batteries ou emballages pour batteries sont étiquetés conformément aux directives européennes
2006/66/EC, norme relative aux batteries et accumulateurs en usage et aux batteries et accumulateurs
usés. Les directives déterminent la marche à suivre en vigueur dans l'Union Européenne pour le retour et
le recyclage des batteries et accumulateurs usés. Cette étiquette est appliquée sur diverses batteries pour
indiquer que la batterie ne doit pas être mise au rebut mais plutôt récupérée en fin de cycle de vie selon
cette norme.

In accordance with the European Directive 2006/66/EC, batteries and accumulators are labeled to
indicate that they are to be collected separately and recycled at end of life. The label on the battery may
also include a chemical symbol for the metal concerned in the battery (Pb for lead, Hg for mercury and
Cd for cadmium). Users of batteries and accumulators must not dispose of batteries and accumulators as
unsorted municipal waste, but use the collection framework available to customers for the return,
recycling and treatment of batteries and accumulators. Customer participation is important to minimize
any potential effects of batteries and accumulators on the environment and human health due to the
potential presence of hazardous substances. For proper collection and treatment, contact your local
Toshiba Global Commerce Solutions representative.

This notice is provided in accordance with Royal Decree 106/2008 of Spain: The retail price of batteries,
accumulators and power cells includes the cost of the environmental management of their waste.

For California:
Perchlorate material – special handling may apply

Refer to www.dtsc.ca.gov/hazardouswaste/perchlorate.

The foregoing notice is provided in accordance with California Code of Regulations Title 22, Division 4.5,
Chapter 33: Best Management Practices for Perchlorate Materials. This product/part includes a lithium
manganese dioxide battery which contains a perchlorate substance.

Flat panel displays

The fluorescent lamp in the liquid crystal display contains mercury. Dispose of it as required by local
ordinances and regulations.

Monitors and workstations

Connecticut: Visit the website of the Department of Environmental Protection at www.st.gov/dev for
information about recycling covered electronic devices in the State of Connecticut, or telephone the
Connecticut Department of Environmental Protection at 1-860-424-3000.

Oregon: For information regarding recycling covered electronic devices in the state of Oregon, go to the
Oregon Department of Environmental Quality site at www.deq.state.or.us/kj/electronics.htm.

118 User's Guide: Store Integrator User's Guide

Washington: For information about recycling covered electronic devices in the State of Washington, go to
the Department of Ecology Website at fortress.wa.gov/ecy/recycle/ or telephone the Washington
Department of Ecology at 1-800-Recycle.

Trademarks
The following are trademarks or registered trademarks of Toshiba, Inc. in the United States or other
countries, or both:

Toshiba
The Toshiba logo

The following are trademarks of Toshiba Global Commerce Solutions in the United States or other
countries, or both:

AnyPlace
SureMark
SurePoint
SurePOS
TCxWave
TCxFlight

The following are trademarks of International Business Machines Corporation in the United States or
other countries, or both:

DB2
DB2 Universal Database
IBM and the IBM logo
PS/2
Wake on LAN
WebSphere

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Magellan is a registered trademark of Datalogic Scanning, Inc.

SYMBOL a registered trademark of Symbol Technologies, Inc.

Microsoft, Windows, Windows NT, and the Windows 95 logo are trademarks of Microsoft Corporation in
the United States, other countries, or both.

Celeron and Intel are trademarks of Intel corporation in the United States, or other countries.

Java and all Java-based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United
States, or other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

Notices 119
120 User's Guide: Store Integrator User's Guide
Index
Special characters completed load definitions 42
configuration 39
document printing 68

(CSS) client session server 2 AEF 39

(SA) supermarket application 3 controller 51
controller/terminal 49
E
electromagnetic Interference statement
CSS 61
Numerics DHCP server option 51
Russia 114
electronic emissions notices 112
4610 POS printer support 15 failover 64
Australia and New Zealand 114
4690 OS requirements 14 initial full-failover 66
China 114
4690 performance optimization 105 JavaPOS 53
European Union 112, 113
4690 trace 92 logging 54
FCC (USA) 112
SI GUI 39
Germany 113
SSL 53
Industry Canada 112
A stand-alone terminals 39
system 50
Japan 115
ACE Korea 115
terminal offline 53
logo printing on Remote GUI 106 electrostatic discharge (ESD) 116
video on the controller 51
ACE requirements 14, 38 enabling CSS 61
Windows Client, remote device
ACE Toolkit 38 enabling PIN pads 69
support 82
ACE usage 59 end of life disposal 116
configuration hierarchy, SI 76
activate configuration 53 EPS tenders, tender verification for 69
configuration on Windows Client,
adding an MSR 87 equipment disposal 116
POSBC 81
AEF properties files 72 error messages, installation 34
configuring adxaennf.dat for failover 65
AEF to GSA interface 36 European Union battery recycling
Configuring AEF 39
AEF to SA interface 36 statement 117
Configuring SI GUI 39
AEF trace 91 export file 53
Configuring the Service Provider 69
an MSR, adding 87 Configuring the Service Provider and
applications, POS 14 Deploying Services 69
apply software manager (ASM) 29 controller configuration 51 F
ASM (apply software Manger) 29 controller installation and configuration, failover
Auto Sign Off, configuring virtual remote device support 85 backup session initialization 66
sessions 67 adding a device 89 configuring adxaennf.dat for 65
automatic terminal lockup 68 adding a new group 86 initial full-failover configuration 66
adding a PIN pad 87 scalability 66
adding a printer 86 failover configuration 64
B adding a scanner 86 failover.properties file 64
background applications 51 adding an MSR 87 ferrite requirement 116
battery return program 117 saving your configuration 89 file, failover.properties 64
bundles 72 controller settings in AEFVIRT.TXT 105 file, SSL properties 75
controller/terminal configuration 49 files
controller/terminal response files 49 using OS 4690 Advanced Java
C CSD 14
CSS configuration 61
Configuration and Bundling for
AEF-only 46
cable ferrite requirement 116 CSS, enabling 61 Using OS 4690 Advanced Java
cancelling installation 58 customer screen browser 40 Configuration and Bundling Instead
CD, Store Integrator 59 of .RSP files for the SI GUI
checkout support and Data Integration application 42
Facility 106
Class A compliance statement D flat panel displays 118
full-failover configuration, initial 66
Australia and New Zealand 114 damage from electrostatic discharge 116
China 114 Data Integration Facility 106
European Union 112, 113 data integration facility (DIF) 13
FCC (USA) 112 deleting a device, remote device G
Germany 113 support 89 general settings 41
Industry Canada 112 device characteristics, terminal graphics 41
Japan 115 configuration 39 group, adding new, remote device
Russia 114 Device Manager trace 98 support 86
client installation and configuration, DHCP server 51 GSA requirements 14
Windows 81 DIF (data integration facility) 13 GSA to AEF interface 36
client session server (CSS) 2 Digital receipts 71 GSA usage 60
client software requirements 16 disk balancing 106 GSA XML strings 99
codes, price override reason 69 disposal of equipment 116 GUI, running remote 89

121
H logging (continued)
moderate 92
POS guidelines (continued)
managers key required 68
hardware requirements 13 logging configuration 54 tender franking and endorsement 68
heap size, JVM 105 logical file names for controllers 52 tender limit pickup 68
hierarchy, SI configuration 76 logical file names for terminals 42 terminal monitor 68
hooks 103 logo printing on Remote GUI (ACE) 106 terminal transfer 67
price override reason codes 69
primary application 41
I M printer, adding, remote device
ICEbrowser 58 support 86
magnetic strip reader (MSR) 17
ICEbrowser requirement 15 printing on Remote GUI (ACE),
managers key required 68
iKeyman url 17 logo 106
mechanism, understanding the
in-store processor 106 problem determination 91
throttling 27
initial full-failover configuration 66 properties, system 99
mercury-added statement 118
installation 29 property files 96
migrating from SureVision 54
cancelling 58 publications, related xiii
migrating to SI V2 and above 54
CD 29 migrating to SI V3R2 and above 56
ICEbrowser 58 migration and reinstallation 54
messages 34 MSR (magnetic strip reader) 17 R
on 4690 29 MSR, adding an 87 reason codes, price override 69
Windows 31 redirecting standard output 94
Windows Client, remote device related publications xiii
support 82
installation and configuration, Windows N Remote GUI (ACE), logo printing
on 106
Client 81 notices 111
remote GUI trace 93
installing components 29 battery recycling 117
remote GUI, running 89
installing on 4690 29 cable ferrites 116
requirements 13, 14
interactive uninstall for Windows 33 electronic emissions 112
4610 POS printer support 15
electrostatic discharge (ESD) 116
4690 OS 14
end of life disposal 116
ACE 14, 38
J Toshiba 111
client software 16
Japan Electronics and Information GSA 14
Technology Industries Association hardware 13
statement 115 O ICEbrowser 15
Japanese Electrical Appliance and optional files for SI GUI 59 Java 2 15
Material Safety Law statement 114 OS 4690 Advanced Java Configuration Java 6 15
Japanese power line harmonics and Bundling for AEF-only, using 46 SA 15
compliance statement 115 OS 4690 Advanced Java Configuration software 13
Japanese VCCI Council Class A and Bundling Instead of .RSP files for response files 96
statement 115 the SI GUI application, using 42 response files for controller/
Java 2 requirements 15 other documents xiii terminals 49
Java 6 requirements 15 output, redirecting 94 RSP files, using OS 4690 Advanced Java
Java classpath 50 override reason codes, price 69 Configuration and Bundling Instead
Java redirection 39 overview of 42
Java terminal offline 53 Application Extension Facility 2
JavaPOS configuration 53 POS Business Component
JavaTOF 53 (POSBC) 11
POS Provider 12
S
JavaTOF configuration 53 SA requirements 15
JIOP trace 97 Store Integrator GUI 3
SA to AEF interface 36
JVM heap size 105 SA usage 60
safety information xi
P saving your configuration 89
K parameters, primary application 103 scalability limitations 25
keyboard 39 perchlorate 118 scanner, adding, remote device
Korean communications statement 115 performance optimization 105 support 86
performance optimization, 4690 105 screen elements, overriding, SI GUI 59
PIN pad, adding, remote device screen resolutions, recommended 41
L support 87
point of sale (POS) 1
secures socket layer (SSL) 17
Service Provider, configuring 69
LAN terminal definition 50 POS (point of sale 1 session trace 95
load definitions 41 POS application usage for SI GUI 59 severe errors on virtual sessions 95
general settings 41 POS applications 14 virtual sessions 95
primary application 41 POS displays 39 SI configuration hierarchy 76
lockup, automatic terminal 68 POS guidelines 67 SI configurations
logging 92 document printing 68 recommended 25
maximum 92 error conditions 68 SI GUI 59
minimal 92

122 User's Guide: Store Integrator User's Guide

si gui screensaver 41
SI GUI trace 91
V
SI GUI, optional files 59 V2 and above, migrating to SI 54
SI V2 and above, migrating to 54 verification for EPS tenders, tender 69
silent uninstall for Windows 34 video configuration on controller 51
software requirements 13 video displays 40
SSL (secure socket layer) 17 VIRTERR.nn 99
SSL certificate update instructions 107 VIRTOUT.nn 99
SSL concepts 18 Virtual file system setup 14
SSL configuration 53 virtual sessions, severe error trace 95
SSL properties file 75
stop sign errors 100
Store Integrator CD 59 W
supermarket application (SA) 3 Windows Client installation and
SureVision migration 37, 54 configuration 81, 82
SYSDEFS.TXT 97 POSBC configuration on Windows
system configuration 50 Client 81
system properties 99 Windows Client, POSBC configuration
on 81
Windows installation 31
T
Taiwanese battery recycling
statement 117 X
TCP/IP 42, 52 XML strings, GSA 99
TCP/IP configuration 52
Telecommunications regulatory
statement 112
tender franking and endorsement 68
tender limit pickup 68
tender verification for EPS tenders 69
terminal configuration 49
terminal configuration, stand-alone
terminals 39
Terminal Load Definition 103
terminal lockup, automatic 68
terminal monitor 68
terminal offline configuration 53
terminal settings 105
terminal transfer 67
throttling mechanism, understanding
the 27
time zone 50
trace logs 100
trace output 99
trace types 91
trace, Device Manager 98
trace, JIOP 97
trace, session 95
trademarks 119
troubleshooting 91
troubleshooting common problems 101

U
understanding SI security 17
understanding the throttling
mechanism 27
uninstalling components 33
user logical file names for controllers 52
user logical file names for terminals 42
using OS 4690 Advanced Java
Configuration and Bundling for
AEF-only 46
Using OS 4690 Advanced Java
Configuration and Bundling Instead of
.RSP files for the SI GUI application 42

Index 123
124 User's Guide: Store Integrator User's Guide
Printed in USA

G362-0561-05