(installing opos, javapos, pos for .net, udm, loadutil ... · the udm default runtime installer...

_____________________________________________________________________________________________________ Copying of this document, and giving it to others and the use or communication of the contents there of, are forbidden without express authority. Offenders are liable to the payment of damages. All rights are reserved in the event of the grant of a patent or the registration of a utility model or design. Date: 19/11/2014 © Wincor Nixdorf International GmbH /22 File: ProBaseUPOS_Installation_Guide.docx

Manual for the ProBase POS Product Installer

(Installing OPOS, JavaPOS, POS for .NET, UDM, LoadUtil) Table of Contents 1 Introduction .......................................................................................................... 2

2 Installation ........................................................................................................... 3

2.1 Pre-Requisites .............................................................................................. 3 2.2 Interactive Installation ................................................................................... 4 2.3 Silent Installation .......................................................................................... 8 2.4 Unattended Installation ................................................................................. 8 2.5 Installation Failures and Rollback ................................................................. 9 2.6 Installing Additional Features ....................................................................... 9 2.7 Upgrading from JavaPOS 1.7C Installation .................................................. 9 2.8 Installing Parallel to ProBase Retail ............................................................. 9 2.9 Installation Profiles ..................................................................................... 10

3 Uninstallation ..................................................................................................... 12

3.1 Interactive Uninstallation ............................................................................ 12 3.2 Silent Uninstallation .................................................................................... 12

4 Logging .............................................................................................................. 13

4.1 Installation Log ........................................................................................... 13 4.2 Uninstallation Log ....................................................................................... 13

5 Exit Codes ......................................................................................................... 14

6 Command Line Parameters ............................................................................... 15

6.1 Parameters Provided by InnoSetup Runtime ............................................. 15 6.2 Product Installer Specific Parameters ........................................................ 16

7 Validating the Installed Configuration ................................................................ 17

7.1 Validating Installation at OPOS .................................................................. 17 7.2 Validating Installation at JavaPOS ............................................................. 19 7.3 Validating Installation at POS for .NET ....................................................... 21

8 Frequently Asked Questions (FAQs) ................................................................. 22

ProBase POS Installer

_____________________________________________________________________________________________________ Copying of this document, and giving it to others and the use or communication of the contents thereof, are forbidden without express authority. Offenders are liable to the payment of damages. All rights are reserved in the event of the grant of a patent or the registration of a utility model or design. Date:19/11/2014 © Wincor Nixdorf International GmbH /22 File: ProBaseUPOS_Installation_Guide.docx

1 Introduction The software product splits into more than 30 packages. Each of these packages may be installed separately but may have dependencies to others of these packages. It is not easy for the users to figure out which packages must be installed in which order. For this reason, the Product Installer contains all these packages and installs them in a given well known order. The current Product Installer is based on InnoSetup. InnoSetup provides the concept of profiles. A profile contains a subset of packages and is linked to a typical usage scenario of supported peripheral devices. This concept offers the user to choose – driven by scenario names – which subset of packages he would like to install. The Product Installer will ensure that the selected packages are installed in the right order. If the user would like to make some adjustments to the subset of packages selected trough a profile, he also has the possibility to customize it by selecting/deselecting packages. However, the customized subset of packages is not checked for consistency before the installer continues. So, dependency errors for lacking packages must be avoided by user if he had customized a profile. Otherwise the installation may fail later on.



2 Installation The Product Installer may run in interactive mode as well as in silent mode. It also provides the possibility performing a so called unattended installation based on an initial master installation.

2.1 Pre-Requisites The following software must be installed on the target machine in order to successfully run ProBase POS:

A Java Virtual Machine (at least version 1.4; UDM Default Runtime – a Wincor Nixdorf distribution package of a JRE coming with OpenJDK 6 – is recommended, see NOTES below)

Registration files for JavaPOS and OPOS must be present (see NOTES below, second section)

However, only the OPOS registration file is needed as installation pre-requisite if OPOS affected profiles (see chapter 2.9 Installation Profiles) have been selected. The following software must already be installed on the target machine in case a POS for .NET affected profile (e.g. “POS for .Net Installation for POS Systems (JavaPOS over UDM)”) has been selected:

Microsoft .Net Framework (at least version 2.0) Microsoft POS for .Net (at least version 1.12)

Additional packages might be required to support certain device (see chapter 2.6 Installing Additional Features). NOTES: Wincor Nixdorf provides a JRE installer based on OpenJDK 6, called “UDM Default Runtime”. To install the UDM Default Runtime, simply call the executable file with the command line option /SILENT (e.g. WN_Ref_UDM_Default_Runtime_Engine-1.1-2-setup.exe /SILENT), and the UDM Default Runtime will be installed to ProBase POS’ installation directory at sub directory “jre”. The UDM Default Runtime installer needs an installed ProBase POS as installation pre-requisite. The UDM Default Runtime installer does not install a public available JRE and takes some other security measures (see document “UDM Security Considerations”). Therefore the application user must be added to the group “wndev” for being able to execute the UDM Default Runtime. If your system is a Wincor Nixdorf pre-installation, you will not need an OPOS license file. Both the JavaPOS and the OPOS license files must be located at “C:\Windows\” (or equivalent, depending on operating system version and installation location, this can be figured out by typing “%SystemRoot%” into an explorer window).



2.2 Interactive Installation An interactive installation is supplied, where the end-user can select interactively:

the installation directory(ies) the installation type / profile or a custom installation by selecting/deselecting each component the start menu shortcut group

Example: After launching the “JavaPOS_OPOS_UDM_113_ProBaseUPOS-<version>-setup.exe”, the following welcome-screen will appear:

If you click “Cancel”, the setup will abort and nothing will have changed on your PC. If you click “Next” though, you will be prompted to choose installation directories for the multiple components of this program. The prompts will all look like this:



After all directories are chosen, you can specify the details of the installation; e.g., which features are going to be installed:



In this dialog, you can either select an installation profile from the drop-down-menu (see 2.9 “Installation Profiles” which profiles are currently defined) or create your own by ticking the boxes next to the features you want to. Now you will need to specify a start menu folder:

After that, the program is ready to install and lets you check all your previously made choices:



The installation process is started by clicking “Install”, and the following window appears:



If no errors appear and everything finishes successfully, you are going to see one last Dialog, informing you that the installation is complete:

2.3 Silent Installation Naturally, a silent installation is possible via the command line argument /SILENT. When Setup is silent the wizard and the background window are not displayed but the installation progress window is. The profile “JavaPOS Installation for POS Systems (without UDM)” is installed on silent mode. IMPORTANT NOTE: Please note, even if InnoSetup offers the possibility to use the command line argument /VERYSILENT (where the installation progress window is not displayed) it is strongly advised to not use this argument. The Product Installer has a rollback mechanism which will be activated if one of the packages cannot be installed. Unfortunately, this rollback mechanism does not work if the installer is called with the argument "/VERYSILENT".

2.4 Unattended Installation With the use of two command line parameters, an unattended Installation is possible. In order to do so, an attended installation on a PC has to be started using the parameter “SAVEINF="pathToFile"” (see 6 “Command Line Parameters”). You now



complete the installation with your desired specifications and settings (see the sections above), and those settings will be stored to the specified file. Then you can simply copy that file and the installer to another machine, start the installer via the command line with the options “LOADINF=”filename”” and “/SILENT” and the installation will run automatically, applying your previously saved settings. Needless to say, this process can be repeated as often as necessary, to mirror an installation on as many computers as desired.

2.5 Installation Failures and Rollback If for any reason the installation of one package fails, the Product Installer will activate its Rollback mechanism and abort with the exit code 5 (see 5 "Exit Codes"). When that happens:

all successfully installed packages will be uninstalled registry entries/shortcuts/files of the Product Installer will be removed

2.6 Installing Additional Features If you need support for USB-Printers, the WNPOSUSB package has to be installed separately. Please note that if you run Windows 7, only version 2.5.0 of the WNPOSUSB driver may be installed (do not install version 2.0.0 in Windows 7!). Also if you need support for cash drawers, the WNPORT-package has to be installed separately.

2.7 Upgrading from JavaPOS 1.7C Installation The Product Installer checks before the Setup initialization if a previous version of JavaPOS 1.7C is installed. If JavaPOS 1.7C is detected on the target system while in interactive mode, a message box will be displayed, asking the user if he would like to remove all the components of the previous version of JavaPOS (1.7C). On silent mode, it would be assumed that the user would like to keep JavaPOS 1.7C: the installer will abort with the exit code 1 (see 5 "Exit Codes"). The removal of JavaPOS 1.7C on silent mode may be forced by calling the installer with the option "/FORCE" (see 6 “Command Line Parameters”).

2.8 Installing Parallel to ProBase Retail Both products share a subset of software packages. Depending on the version of ProBase Retail and ProBase POS the version of contained software packages may differ. Installing the packages of ProBase Retail and ProBase POS to the same directories may therefore lead to an out of order situation or limited functionality provided to applications.



Therefore it is recommended to install ProBase Retail and ProBase POS in different directories on systems running both in parallel servicing two independent applications, the one using ProBase Retail, the other using ProBase POS. Both products are not prepared, from integration point of view, to be used by one application in parallel. Using both products at the same runtime by one application needs additional integration effort.

2.9 Installation Profiles The installer comes with a set of selectable profiles (see 2.2 ”Interactive Installation”) providing sets of components for particular usage scenarios. It is recommended to use these profiles and to perform custom installation only upon consultation with the Wincor-Nixdorf platform support team ([email protected]). Currently the following profiles are defined:

Profile Name Profile Meaning JavaPOS Installation for POS Systems

Installation for JavaPOS based applications operating on ordinary POS peripherals like cash drawer, scanner, line display, and POS printers. Default profile.

OPOS Installation for POS Systems

Installation for OPOS based applications operating on ordinary POS peripherals like cash drawer, scanner, line display, and POS printers. Forwards OPOS calls to WN’s JavaPOS implementation using the UDM technology.

POS For .NET Installation for POS Systems

Installation for POS for .NET based applications operating on ordinary POS peripherals like cash drawer, scanner, line display, and POS printers. Forwards POS for .NET calls to WN’s JavaPOS implementation using the UDM technology.

POS For .NET Installation for Petrol Stations

Installation for POS for .NET based applications operating on petrol station POS peripherals. E.g., additionally to the ordinary peripherals the TP07 support is installed. Forwards POS for .NET calls to WN’s JavaPOS implementation using the UDM technology.

JavaPOS Installation for SCO Tower Line 100

Installation for JavaPOS based applications operating on self-checkout specific peripherals like TP07, cash changers and TPiScan supported devices as well as on ordinary POS peripherals.

OPOS Installation for SCO Tower Line 100 Systems

Installation for JavaPOS based applications operating on self-checkout specific peripherals like TP07, cash changers and TPiScan supported devices as well as on ordinary POS peripherals. Forwards OPOS calls to WN’s JavaPOS implementation using the UDM technology.

Compact installation

Smallest possible JavaPOS installation operating ordinary POS peripherals only. May be used as base for setting up a custom installation as all remaining components are



Profile Name Profile Meaning depending on this set of components.

Full installation All packages are going to be installed. This is not recommended as some of the components do not make sense to be operated in parallel as they are targeting different implementation platforms. However, if installed no one of the components should prevent others from working well.



3 Uninstallation The Product Uninstaller will remove all packages which were installed by the Product Installer, even if these packages have been afterwards updated or downgraded. Furthermore, before starting the uninstallation process, it will check if additional components not part of the Product Installer but depending on one of the component installed by the Product Installer have been installed. On interactive uninstallation, a message box will be displayed asking the user if he would like to remove these components also. On silent uninstallation, it will be assumed that the user would not like to remove these components: the Product Uninstaller will abort with the exit code 1 (see 5 "Exit Codes"). On silent mode, to force the uninstallation (including these additional components), the Product Uninstaller must be called with the option "/FORCE" (see 6 “Command Line Parameters”).

3.1 Interactive Uninstallation Three possibilities are offered for the interactive uninstallation of the Product:

direct call of the uninstaller (located under the directory "Uninstall-<MyProgramName>"/unins000.exe (NOT RECOMMENDED)

shortcut under the start menu --> all programs --> <MyProgramName> --> Uninstall <MyProgramName>

settings --> Control Panel --> Add or Remove Programs It is not recommended to directly call the uninstaller, as the uninstallation log won't be created (see "4 Logging" for more details).

3.2 Silent Uninstallation Like for the installation, it is also possible to execute the uninstaller silently via the command line argument /SILENT. Example:

"C:\Retail\Software\javapos\Uninstall-ProBase-Retail\unins000.exe" /LOG="C:\Retail\Software\uninstall_PBR.log" /SILENT

IMPORTANT NOTE: Unlike the installation, the uninstallation log is not activated by default, and therefore, it is STRONGLY RECOMMENDED to call the uninstaller with the "/LOG" switch (see 4 "Logging" for more details).



4 Logging

4.1 Installation Log Logging for the installation is always activated. If the installer is not called with the argument /LOG="filename", the setup log will be stored in the TEMP directory with a unique filename based on the current date:

Setup Log yyyy-mm-dd #<number>.txt

4.2 Uninstallation Log Logging for the uninstallation cannot be always activated. In order to activate uninstallation logging, the following parameter has to be appended to the call to the uninstaller: "/LOG=%TMP%/Uninstall_<MyProgramName>-<Version>.<Build>.log" The uninstallation logging has the following limitations:

Only one uninstallation log per version-build is possible! If the Product Installer (with the same version and build number) has been installed / uninstalled multiple times, and even at different times and days, the uninstallation log will always be re-written.

If the uninstaller is called directly (and without giving the /LOG option), then no uninstallation log is created.



5 Exit Codes

0 Setup was successfully run to completion.

1

Setup/Uninstaller failed to initialize. This can happen for example, if the user decides not to uninstall JavaPOS 1.7C (or if silent install is activated without calling the /FORCE option). For uninstallation, this can happen if the user decides not to uninstall additional components which were not installed by the Product Installer (or if silent uninstall is activated without calling the /FORCE option).

2 The user clicked Cancel in the wizard before the actual installation started, or chose "No" on the opening "This will install..." message box.

3

A fatal error occurred while preparing to move to the next installation phase (for example, from displaying the pre-installation wizard pages to the actual installation process). This should never happen except under the most unusual of circumstances, such as running out of memory or Windows resources.

4

A fatal error occurred during the actual installation process. Note: Errors that cause an Abort-Retry-Ignore box to be displayed are not fatal errors. If the user chooses Abort at such a message box, exit code 5 will be returned.

5

The user clicked Cancel during the actual installation process, or chose Abort at an Abort-Retry-Ignore box. Or an error occurred during the installation of one of the components (= sub-installers). The rollback mechanism has been activated (all installed sub-installer are uninstalled) and the partially installed Product Installer is uninstalled (if not called with the parameter /VERYSILENT).

6 The Setup process was forcefully terminated by the debugger (Run | Terminate was used in the IDE).



6 Command Line Parameters

6.1 Parameters Provided by InnoSetup Runtime Below you will find a short list of the most important command line parameters supported by the Product Installer derived from InnoSetup installer runtime. This list is non exhaustive, and shows only the important command switches. For a complete list, please refer to the InnoSetup official help:

http://unattended.sourceforge.net/InnoSetup_Switches_ExitCodes.html

/SILENT The installer runs silently. When installer runs silently the wizard and the background window are not displayed but the installation progress window is. Everything else is normal so for example error messages during installation are displayed and the start-up prompt is (if you haven't disabled it with another parameter).

/LOADINF="filename"

The installer loads the settings from the specified file after having checked the command line. This file can be prepared using the '/SAVEINF=' command as explained below.

/SAVEINF="pathToFile"

The installer saves installation settings to the specified file. Don't forget to use quotes if the filename contains spaces and always use the absolute path to the file.

/LOG

The installer creates a log file in the user's TEMP directory detailing file installation and [Run] actions taken during the installation process. This can be a helpful debugging aid. For example, if you suspect a file isn't being replaced when you believe it should be (or vice versa), the log file will tell you if the file was really skipped, and why. The log file is created with a unique name based on the current date. (It will not overwrite or append to existing files.) The information contained in the log file is technical in nature and therefore not intended to be understandable by end users. Nor is it designed to be machine-parseable; the format of the file is subject to change without notice.

/LOG="filename"

Same as /LOG, except it allows specifying a fixed path/filename to be used as log file. If a file with the specified name already exists it will be overwritten. If the file cannot be created, the installer will abort with an error message.



6.2 Product Installer Specific Parameters These parameters are provided additionally to the parameters derived from the InnoSetup installer runtime.

/FORCE For the installation: The installer checks before the install initialization whether a previous version of JavaPOS 1.7C is installed. If called with the option "/FORCE", the installer will assume that the previous version must be removed. For the uninstallation: If called with the option "/FORCE", the uninstaller will assume that all components depending on ProBase POS components installed with the origin run of the installer (e.g., ProBase POS sub components which may be installed by the user afterwards using single installer packages, but also additional Wincor Nixdorf packages depending on installed ProBase POS components) should be removed.



7 Validating the Installed Configuration

7.1 Validating Installation at OPOS The sub package “OPOS Common” comes with an OPOS configuration tool which provides structural editing support for the OPOS configuration at the Windows registry. This tool also provides some testing facilities for validating configurations and a proper connection to the hardware peripheral configured. The tool can be started over the Windows Start menu:

This will start the OPOS configuration program which looks like follows:



After having adapted the configuration using at the category specific tabulator and selecting the requested open name at the drop down box below “Variants of Peripheral”, the configuration may be tested using the button “Test” on the right side of the window. This will start a test dialog:

After selecting an short cut or open name at the list box a click on the “Run the test “ button below will start a simple connection test. If the test fails on OPOS DeviceEnabled property access something is wrong with the configuration or, the peripheral is not well



connected over the cable. If the test fails on OPOS Claim method almost the port is wrong configured or already used by another device. If the OPOS Open method fails almost the UDM server is not running. Check the UDM server Windows Start Menu entries for an UDM server status check. If the error still remains the trace for the particular open name under test has to be enabled and the trace file from the erroneous situation may be sent to the Wincor Nixdorf support team (see FAQ) for investigation. The trace can be enabled over the OPOS configuration tool at the edit group “Service Object Trace Information” by setting the Level to a value greater 0. The trace file is written to the location configured there at “FileName”.

7.2 Validating Installation at JavaPOS The JavaPOS installation comes with a set of tools bunched by graphical wrapper for user convenience. The JavaPOS Tool Center can be started via the Windows start menu:

This will start the JavaPOS Tool Center likes follows:



A click to the button SwingSamples will start an interactive Java program for testing the access to perihperals. It allows to selcect a category and a open name configured and exposes the JavaPOS API as graphical interface:



7.3 Validating Installation at POS for .NET At this time there is no tool for validating the POS for .NET installation. However, the application example coming with the Microsoft POS for .NET SDK may be utilized for this.



8 Frequently Asked Questions (FAQs) Q: The installation finished successfully, but when trying to communicate with a

device, I always get errors like “ERROR: cannot open XXX (device) – ResultCode = NO EXIST”. What can I do?

A: Most probably, there had not been a Java Virtual Machine present while the Product Installer was being run. Please install a Java Virtual Machine (see 2.1 “Pre-Requisites” for details), uninstall the Product Installer and then install it again.

Q: The installation aborts, and the rollback mechanism is activated. Why? A: There are several possible reasons for that behaviour. Your first step should

be to check “2a Prerequisites”, and make sure every prerequisite is actually met. If the Product Installer aborts while trying to install the P4DNUDMAdapter for example, the most probable reason is a missing “.Net Framework” or “POS for .Net Framework” installation.

Q: I have a problem that I cannot solve by myself. Where can I get help? A: Contact [email protected] and append all of the created log

files, see 4 “Logging” for details if you’re not sure where to find them. In addition to the standard installation and deinstallation log files, there are also log files named “WNJavaPOS_XXX_yyyymmdd.log”, where XXX is the name of an executable file, please send them too. Sending all the log files is extremely important in order for your problem to get solved as quickly and as precisely as possible.

Q: Why I need JavaPOS and Java to run an OPOS or POS for .NET application? A: Wincor Nixdorf provides UPOS peripheral device implementations only for as

a JavaPOS implementation. However, there are generic mappers implemented which exposes the functionality provided by the JavaPOS implementation to the OPOS and POS for .NET platform such that applications can utilize JavaPOS transparently. These mappers forward OPOS and POS for .NET calls to the appropriate JavaPOS calls.

(installing opos, javapos, pos for .net, udm, loadutil ... · the udm default runtime installer...

Documents