fiscal print1

SAP®

© 2010 SAP AG

Dietmar-Hopp-Allee 16 D-69190 Walldorf

of 63

SAP Enterprise POS Fiscal Printer User Exit Technical Reference

Version 1.0

SAP®

© 2010 SAP AG

Dietmar-Hopp-Allee 16

D-69190 Walldorf

Title: SAP Enterprise POS Fiscal Printer User Exit Technical Refer-ence

Version: 1.0 Date: 11/24/2010

of 63

Copyright

© Copyright 2010 SAP AG. All rights reserved

SAP Library document classification: PUBLIC

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice.

Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors.

Microsoft, Windows, Excel, Outlook, and Po-werPoint are registered trademarks of Micro-soft Corporation.

IBM, DB2, DB2 Universal Database, System i, System i5, System p, System p5, System x, System z, System z10, System z9, z10, z9, iSeries, pSeries, xSeries, zSeries, eServer, z/VM, z/OS, i5/OS, S/390, OS/390, OS/400, AS/400, S/390 Parallel Enterprise Server, Po-werVM, Power Architecture, POWER6+, POWER6, POWER5+, POWER5, POWER, OpenPower, PowerPC, BatchPipes, Blade-Center, System Storage, GPFS, HACMP, RETAIN, DB2 Connect, RACF, Redbooks, OS/2, Parallel Sysplex, MVS/ESA, AIX, Intelli-gent Miner, WebSphere, Netfinity, Tivoli and Informix are trademarks or registered trade-marks of IBM Corporation.

Linux is the registered trademark of Linus Tor-valds in the U.S. and other countries.

Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or regis-tered trademarks of Adobe Systems Incorpo-rated in the United States and/or other coun-tries.

Oracle is a registered trademark of Oracle Corporation.

UNIX, X/Open, OSF/1, and Motif are regis-tered trademarks of the Open Group.

Citrix, ICA, Program Neighborhood, Meta-Frame, WinFrame, VideoFrame, and MultiWin

are trademarks or registered trademarks of Ci-trix Systems, Inc.

HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Insti-tute of Technology.

Java is a registered trademark of Sun Micro-systems, Inc.

JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape.

SAP, R/3, SAP NetWeaver, Duet, Partne-rEdge, ByDesign, Clear Enterprise, SAP Busi-nessObjects Explorer, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and other countries.

Business Objects and the Business Objects logo, BusinessObjects, Crystal Reports, Crys-tal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP France in the United States and in oth-er countries.

All other product and service names men-tioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary.

These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without repre-sentation or warranty of any kind, and SAP Group shall not be liable for errors or omis-sions with respect to the materials.

The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Icons

Icon Meaning

Caution

Example

Note

Recommendation

Syntax

Tip

History

Version Date Status (Comments)

1.0 11/24/2010 Initial

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Contents

1 Introduction .......................................................................................... 5

1.1 Business Context ............................................................................................ 5

1.2 General Guidelines .......................................................................................... 6

2 Development Environment Setup ....................................................... 7

3 Fiscal Printer User Exit API ................................................................. 7

3.1 Overview ......................................................................................................... 7

3.2 IFiscalPrinterService ....................................................................................... 9

3.3 IPosPrinterServiceV2 .................................................................................... 13

3.4 IPosPrinterService ......................................................................................... 14

4 Requirements For Fiscal Printers In Synchronous Mode ............... 25

4.1 Configuring the Client .................................................................................... 25

4.2 Error Handling ............................................................................................... 27

5 Configuration ...................................................................................... 28

5.1 Fiscal Printer User Exit Classname ............................................................... 28

5.2 Setting The Classpath ................................................................................... 29

6 Using The Fiscal Printer .................................................................... 29

6.1 Configurator Settings ..................................................................................... 29

6.2 ~FISCAL Function ......................................................................................... 30

6.3 Saving the Fiscal Document Number into TLog ............................................. 30

6.4 Paragraph Class............................................................................................ 31

6.5 ReceiptDescriptors ........................................................................................ 33

6.6 LineBuffer ...................................................................................................... 35

7 Java BAdI Implementation For Fiscal Printer .................................. 39

7.1 Introduction ................................................................................................... 39

7.2 Main Building Blocks and Entities .................................................................. 39

7.3 How to implement a BAdI for an Enhancement Spot ..................................... 42

7.4 Implementation of the Java BAdI for Barcode Printing ................................... 43

7.5 Implementation of the Java BAdI for the Bitmap Printing ............................... 61

7.6 Distribution and Deployment ......................................................................... 63

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

1 Introduction

This document describes the interface that a Java programmer has to develop to establish communication be-tween the SAP Enterprise POS and a fiscal printer to produce fiscal receipts and comply with the regulations of countries where fiscal audits are performed.

The key advantages of using the Fiscal Printer User Exit are:

Provides options to develop/implement specific fiscal printer requirements outside the CORE code.

Fiscal printer integration can be done by SAP, SAP customer, or SAP partner.

SAP provides two default Fiscal Printer User Exit implementations, which you can modify as necessary to create a customized fiscal printer user exit.

1.1 Business Context

Fiscal printers are used by retailers in countries where the government performs audits of financial transactions and therefore requires that fiscal information is logged and monitored at each Point-Of-Sale (POS). Fiscal infor-mation includes, but is not be limited to, transaction totals, discounts, tax table information and number of can-celled receipts. The totals are stored in fiscal printer memory and are not accessible for modification.

SAP Enterprise POS uses specialized functions to send commands to fiscal printers for the purposes of printing both fiscal and non-fiscal information. These two types of information may be combined within a single receipt. For example, for a sales transaction with multiple items, the printer prints (and stores) the price and tax amount for each item (fiscal information) as well as the store’s return policy (non-fiscal information) on a single receipt.

Fiscal rules vary depending on country/region. This Fiscal Printer User Exit interface described in this guide ad-dressed the following general fiscal printer requirements:

Fiscal receipts must be printed and given to the customer.

Fiscal printers are equipped with memory to store daily totals. Each receipt line item will increment to-tals such as sales, taxation (for multiple taxation levels, as applicable), discounts/surcharges and can-celled receipts and store these items with a correct date and time stamp.

Each fiscal receipt line item is printed both on the receipt and in the SAP Enterprise POS electronic journal.

After a power loss, the fiscal printer must return to the same state it was in before the power loss. Upon application restart, SAP Enterprise POS must ensure that the fiscal printer is in the correct state prior to restarting the printing of a fiscal document.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

1.2 General Guidelines

To connect a fiscal printer to a cash register running the SAP Enterprise POS application and to print using this printer, you need to do the following:

1. Set up your development environment. See the Development Environment Setup section for more in-formation.

2. Implement the Fiscal Printer User Exit class as described in this guide. For a list of methods that must be included in the class, see Fiscal Printer User Exit API.

The SAP Enterprise POS application includes two sample implementations of the Fiscal Printer User Ex-it:

StandardFiscalPrinterService.java – default implementation.

StandardSyncFiscalPrinterService.java – default implementation for landscapes

equipped with fiscal printers that only support the synchronous mode of operation.

You can adapt either of these default implementations to your particular requirements. For general information on implementing user exits for SAP Enterprise POS, see the Technical Product Reference section of the SAP Library documentation under User Exits.

3. Optionally, use BAdIs to enable printing of barcodes and bitmaps on the fiscal printer. See the Java BAdI Implementation For Fiscal Printer section for more information.

4. Make adjustments for fiscal printers working in synchronous mode. For more information, see the Re-quirements For Fiscal Printers In Synchronous Mode section.

5. Modify the POS Client configuration to include the new Fiscal Printer User Exit. For more information, see the Fiscal Printer User Exit Classname section.

6. Modify the POS Client startup file to include the new Fiscal Printer User Exit. For more information, see the Setting The Classpath section.

7. Make changes to the required SAP Enterprise POS Configurator settings. For more information, see the Configurator Settings section.

8. Create documents (using the Document Editor) that use the ~FISCAL() function to print fiscal receipts

and reports on the fiscal printer. See the ~FISCAL Function section for more information.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

2 Development Environment Setup

Prior to beginning the implementation of your Fiscal Printer User Exit, verify that you are using the most recent version of Java. At the time of the publishing of this guide, this was Java 1.5.

The development environment can be set up with a reference to the following JAR files:

File Name Description

dsl.jar This is the main JAR file that contains all the Fiscal Printer User Exit related classes and the only JAR file that is required for Fiscal Printer User Exit development. All oth-ers are optional.

te_clientsrvr.jar This JAR file contains all POS related files. If you are using any SAP Enterprise POS constants classes, they are available in this JAR file.

tef.jar This JAR file contains all core TEF framework-related classes.

tef_logging.jar This JAR file is used for SAP Enterprise POS logging.

3 Fiscal Printer User Exit API

3.1 Overview

The Fiscal Printer User Exit API is a collection of classes and interfaces that can be implemented to develop a Fiscal Printer User Exit. Use the sample implementations of the Fiscal Printer User Exit provided with the SAP Enterprise POS application source code as a reference when developing your custom Fiscal Printer User Exit.

com.triversity.transactionware.framework.deviceservices

This package contains the classes and interfaces that are used to implement the Fiscal Printer User Exit.

FiscalPrinterStatusUpdateEvent

IDslFiscalPrinterConst

IPosPrinterService

IPosPrinterServiceV2

IFiscalPrinterService

com.triversity.transactionware.framework.deviceservices.jpos

This package contains the standard implementation of the Fiscal Printer User Exit as well as other classes and interfaces used by the user exit.

AbstractFiscalPrinterControl16Monitor

FiscalPrinterErrorMessage

PosFiscalPrinterPendingRequest

StandardFiscalPrinterService

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Operations

void initialize(Map<String,Object>)

Object getProperty(String)

void reset()

boolean isDayOpened()

boolean isFiscalReceipt()

void printPeriodicTotalsReport(String, String)

void printPowerLossReport()

void printPeriodicTotalsReport(int, int, int)

void printXReport()

void printZReport()

«interface»


Operations

void print(int, List<Paragragh>, ReceiptDescriptors)

boolean isCoverOpen()

«interface»

IPosPrinterServiceV2Operations

void addErrorListener(IError Listener)

void removeErrorListener(IErrorListener)

void addStatusUpdateListener(IStatusUpdateListener)

void beginRemoval(int)

int checkHealth()

void cutPaper(int)

void endInsertion()

void endRemoval()

boolean getCapability(int, String)

int getJournalWidth()

void removeStatusUpdateListener(IStatusUpdateListener)

void print(int, String)

void printBitmap(int, String, int, int)

int getJournalWidthDots()

int getReceiptWidth()

int getReceiptWidthDots()

int getSlipWidth()

int getSlipWidthDots()

boolean getSlpEmpty()

boolean isReceiptEmpty()

boolean isReceiptNearEnd()

void setFlagWhenIdle(boolean)

void setAsyncMode(boolean)

void deleteTransactionBitmaps()

void printBarCode(int, String, int, int, int, int, int)

void beginInsertion(int)

void setBitmap(int, int, String, int, int)

void printStoredBitmap(int, int)

«interface»

IPosPrinterService

StandardFiscalPrinterService

Fiscal Printer User Exit

Fiscal Printer User Exit

Implementation

JPosFiscalPrinterListener

OutputCompleteListener

ErrorListener

StatusUpdateListener

DirectIOListener

JPOS

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.2 IFiscalPrinterService

This interface is the basis for the Fiscal Printer User Exit. IFiscalPrinterService must be implemented for

the POS Client to load the fiscal printer implementation. IFiscalPrinterService extends IPosPrinter-

ServiceV2 which in turn extends IPosPrinterService, therefore the methods of both these interfaces must

also be implemented even if they do not necessarily relate to the fiscal printer.

The POS Client can make calls to the following methods of IFiscalPrinterService:

initialize

isDayOpened

isFiscalReceipt

printPeriodicTotalsReport

printReport

printPowerLossReport

printXReport

printZReport

getProperty

reset

3.2.1 Initialize

Method Name initialize

Event class/Event None Visibility Public

Description

Method to initialize the fiscal printer with data from SAP Enterprise POS. Fiscal printer initialization is dependent on the particular printer model. The fiscal printer is initialized by the data passed by the Map parameter.

Preconditions

Result The fiscal printer is initialized with data from SAP Enterprise POS.

Exceptions DeviceServiceException

Parameter Name Parameter Type Description

parameters Map<String, Ob-ject>

The SAP Enterprise POS parameter used to initialize the internal settings of the fiscal printer.

The Map parameter can possibly contain the following data:

Key Value

IDslFiscalPrinter-

Const.INIT_CURRENCY

The primary currency configured in SAP En-terprise POS

IDslFiscalPrinter-

Const.INIT_DATE_TIME

The current system time

IDslFiscalPrinter-

Const.INIT_STORE_FISCAL_ID

The Store ID to which the register, and sub-sequently the fiscal printer, are connected

IDslFiscalPrinter-

Const.INIT_TAX_INFO

The accumulated tax group rates

IDslFiscalPrinter-

Const.INIT_TENDER_INFO

The tenders configured in SAP Enterprise POS

IDslFiscalPrinter-

Const.INIT_POS_ID

The client ID and cashier ID, which are con-

tained in an instance of FiscalPrinter-TillAccountability

The store information parameters are also possibly contained in the parameters map in order to have access to the header and trailer lines. The key for header lines will have a prefix of

IDslFiscalPrinterConst.INIT_HEADER_LINE followed by a number. The trailer lines

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

will have a prefix of IDslFiscalPrinterConst.INIT_TRAILER_LINE followed by a

number.

3.2.2 Is Day Opened

Method Name isDayOpened


Description

Method to determine whether the fiscal day is open on the fiscal printer. A fiscal day is open when at least one transaction has been completed but the Z-report has not been printed.

Preconditions

Result True if the fiscal day is open on the printer, false otherwise.


3.2.3 Is Fiscal Receipt

Method Name isFiscalReceipt


Description

Method to determine whether the current receipt is a fiscal receipt or not.

Preconditions

Result True if the current receipt is a fiscal receipt, false otherwise.

Exceptions

3.2.4 Print Periodic Totals Report

Method Name printPeriodicTotalsReport


Description

Method to print the Periodic Totals Report on the fiscal printer. The parameters passed to this method are two

dates in String format, which set the time period for the report. (Ref: jPOS printPeriodicTotalsReport)

Preconditions

Result Periodic Totals Report is printed.


Parameter Name Parameter Type

Description

aStartDate String The initial date for the report.

anEndDate String The ending date for the report.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.2.5 Print Report

Method Name printReport


Description

Method to print a fiscal report. (Ref: jPOS printRecord)

Preconditions

Result Selected fiscal report is printed.



Description

aReportType int The type of report to print:

Value Description

IDslFiscalPrinterConst.DSL_FPTR_RT_ORDINAL Prints report between two record numbers selected from fiscal memory

IDslFiscalPrinterConst.DSL_FPTR_RT_DATE Prints report between two se-lected dates

aStartNum String String indicating the starting transaction record or the initial date.

anEndNum String String indicating the final transaction record or the ending date.

3.2.6 Print Power Loss Report

Method Name printPowerLossReport


Description

Method to print the power loss report. (Ref: jPOS printPowerLossReport)

Preconditions

Result The power loss report is printed.



3.2.7 Print X Report

Method Name printXReport


Description

Method to print the X report. (Ref: jPOS printXReport)

Preconditions

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Result The X report is printed.



Description

3.2.8 Print Z Report

Method Name printZReport


Description

Method to print the Z report. (Ref: jPOS printZReport)

Preconditions

Result The Z report is printed and the fiscal day is closed.



Description

3.2.9 Get Property

Method Name getProperty


Description

Method to return the requested property based on the String parameter.

Preconditions

Result An object containing the requested property is returned.



Description

property String The name of the property to retrieve.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.2.10 Reset

Method Name reset


Description

Method to reset or clear the fiscal printer and other related tasks.

Preconditions

Result All tasks are cleared.



3.3 IPosPrinterServiceV2

As IFiscalPrinterService extends IPosPrinterServiceV2, any Fiscal Printer User Exit implementation

will must also include the IPosPrinterServiceV2 interface. This interface consists of two methods relating

to printing:

print

isCoverOpen

3.3.1 Print

Method Name print


Description

Method to print one or more paragraphs of formatted text on the selected printer.

Preconditions

Result



aStationId int The ID for the station to which the printer is connected.

aReceipt List<Paragraph> The receipt information as a list of Paragraphs, where each paragraph is a list of LineBuffers.

Paragraph class details are described in the Paragraph Class section.

aDescriptor ReceiptDescriptors The receipt descriptor which, if applicable, describes the page layout. May be null, so im-

plementing classes must take note of this. ReceiptDescriptors class details are de-

scribed in the ReceiptDescriptors section.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.3.2 Is Cover Open

Method Name isCoverOpen


Description

Method to determine whether the cover of the printer is open or not. (Ref: jPOS isCoverOpen)

Preconditions

Result True if the printer cover is opened, false otherwise.



3.4 IPosPrinterService

The interface IPosPrinterServiceV2 extends IPosPrinterService, therefore any implementation of the

Fiscal Printer User Exit should implement the methods of IPosPrinterService.

Note:

Although most methods defined in this interface are not used by the fiscal printer, nevertheless, these methods need to be included in the Fiscal Printer User Exit implementation.

3.4.1 Add Error Listener

Method Name addErrorListener


Description

Method to add an error listener.

Preconditions

Result The error listener is passed as a parameter to the list of error listeners.



anErrorListener IErrorListener The error listener to add to the list.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.2 Add Status Update Listener

Method Name addStatusUpdateListener


Description

Method to add a status update listener.

Preconditions

Result The status update listener is passed as a parameter to the list of status update listeners.



statusListener IStatusUpdateListener The status update listener to be added to the list.

3.4.3 Begin Insertion

Method Name beginInsertion


Description

Method to set the printer into insertion mode. (Ref: jPOS beginInsertion).

Preconditions

Result The printer mode is set to insertion.



aTimeout int The length of time in milliseconds that the method should be tried before issuing a time-out.

3.4.4 Begin Removal

Method Name beginRemoval


Description

Method to start the form removal process on the printer. (Ref: jPOS beginRemoval)

Preconditions

Result The form removal process is started.

Exceptions


Description

aTimeout int The length of time in milliseconds that the method should be tried before issuing a timeout.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.5 Check Health

Method Name checkHealth


Description

Method to check the health of the printer. (Ref: jPOS checkHealth)

Preconditions

Result If a problem is found, the appropriate error code is returned, otherwise a success code is returned.

Exceptions


Description

3.4.6 Cut Paper

Method Name cutPaper


Description

Method to issue the command to cut the paper in the receipt printer. Not applicable for fiscal printer as cutting of receipts is done implicitly through other commands.

Preconditions

Result

Exceptions


Description

stationId int The ID for the station to which the printer is connected.

3.4.7 Delete Transaction Bitmaps

Method Name deleteTransactionBitmaps


Description

Method to delete all stored transaction bitmaps. Not applicable for fiscal printer.

Preconditions

Result

Exceptions


Description

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.8 End Insertion

Method Name endInsertion


Description

Method to take the printer out of form insertion mode. (Ref: jPOS endInsertion)

Preconditions

Result The printer exits form insertion mode.



Description

3.4.9 End Removal

Method Name endRemoval


Description

Method to take the printer out of form removal mode. (Ref: jPOS endRemoval)

Preconditions

Result The printer exits form removal mode.



Description

3.4.10 Get Capability

Method Name getCapability


Description

Method to retrieve whether the selected printer has the requested capability.

Preconditions

Result True if the printer has the requested capability, false otherwise.

Exceptions


Description

aStationId Int The ID for the station to which the printer is connected.

aCapabilityId String The ID of the capability to verify.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.11 Get Journal Width

Method Name getJournalWidth


Description

Method to retrieve the defined journal width. Not applicable for fiscal printer.

Preconditions

Result



Description

3.4.12 Get Journal Width Dots

Method Name getJournalWidthDots


Description

Method to retrieve the defined journal dot width. Not applicable for fiscal printer.

Preconditions

Result



Description

3.4.13 Get Receipt Width

Method Name getReceiptWidth


Description

Method to retrieve the maximum possible width for a line on a receipt.

Preconditions

Result The maximum width of a receipt line is returned.



Description

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.14 Get Receipt Width Dots

Method Name getReceiptWidthDots


Description

Method to return receipt dot width. Not applicable for fiscal printer.

Preconditions

Result



Description

3.4.15 Get Slip Width

Method Name getSlipWidth


Description

Method to return the slip receipt width. Not applicable for fiscal printer.

Preconditions

Result



Description

3.4.16 Get Slip Width Dots

Method Name getSlipWidthDots


Description

Method to return the slip receipt dot width. Not applicable for fiscal printer.

Preconditions

Result



Description

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.17 Get Slip Empty

Method Name getSlpEmpty


Description

Method to return whether the slip printer is out of paper. Not applicable for fiscal printer.

Preconditions

Result True if the slip printer is empty, false otherwise.



Description

3.4.18 Is Receipt Empty

Method Name getReceiptEmpty


Description

Method to return whether the receipt printer is out of paper.

Preconditions

Result True if the receipt printer is empty, false otherwise.

Exceptions


Description

3.4.19 Is Receipt Near End

Method Name isReceiptNearEnd


Description

Method to determine whether the receipt printer is nearly out of paper.

Preconditions

Result True if the receipt is nearly out of paper, false otherwise.

Exceptions


Description

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.20 Print

Method Name print


Description

Method to print one or more lines of formatted text on one or more print stations. Typically, you would not use this method with a fiscal printer; this method is used with standard receipt printers.

Preconditions

Result The specified strings are printed on the selected printer.

Exceptions


Description

aStationId int Identifies the print station or stations where the text is to be printed. Set this parameter to one

of the DSL_PTR_S_xxx found in IDslPosPrinterConst.

aStringToPrint String Sets the lines of text to be printed. If the string contains multiple lines, each line should be ter-minated with a combination of a carriage return and a line feed character.

3.4.21 Print Bar Code

Method Name printBarCode


Description

Method to print the barcode on the receipt as per the specified parameters.

Preconditions

Result The barcode is printed.



Description

aStationId int Identifies the print station or stations (one of IDeviceSet.DEVICE_RECEIPT, DEVICE_SLIP, DEVICE_JOURNAL).

aData String The actual barcode data.

aSymbology int The index of the entry in the ConfigPOSConstants.symbologies table.

aHeight int Height of barcode.

aWidth int Width of barcode.

anAlignment int Alignment of the barcode.

aTextPosition int Text position of the barcode.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.22 Print Bitmap

Method Name printBitmap


Description

Method to print the bitmap as per the specified parameters.

Preconditions

Result The bitmap is printed.



aStationId int Identifies the print station or stations (one of IDeviceSet.DEVICE_RECEIPT,

DEVICE_SLIP, DEVICE_JOURNAL)

aFileName String Filename of the bitmap to be printed.

aWidth int The width of the bitmap.

anAlignment int Alignment of the bitmap.

3.4.23 Print Stored Bitmap

Method Name printStoredBitmap


Description

Method to print a stored bitmap. Not applicable for fiscal printer.

Preconditions

Result



aStationId int Identifies the print station or stations (one of IDeviceSet.DEVICE_RECEIPT,

DEVICE_SLIP, DEVICE_JOURNAL)

aStoredBitmap int Index of the stored bitmap.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.24 Remove Error Listener

Method Name removeErrorListener


Description

Method to remove an error listener.

Preconditions

Result The specified error listener is removed from the list of Error Listeners.

Exceptions


anErrorListener IErrorListener The error listener to remove from the list.

3.4.25 Remove Status Update Listener

Method Name removeStatusUpdateListener


Description

Method to remove a status update listener.

Preconditions

Result The specified status update listener is removed from the list of Status Update Listeners.

Exceptions


aStatusListener IStatusUpdateListener The status update listener to remove from the list.

3.4.26 Set Async Mode

Method Name setAsyncMode


Description

Method to set the printer in asynchronous mode of operation.

Preconditions

Result The printer is set to the selected mode of operation.



aFlag boolean Set flag to true to operate the printer in asynchronous mode, or false to operate in syn-chronous mode.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

3.4.27 Set Bitmap

Method Name setBitmap


Description

Method to configure a bitmap. Not applicable for fiscal printer.

Preconditions

Result



aBitmapNumber int The index of the stored bitmap.

aStationId int The ID for the station to which the printer is connected.

aFileName String Filename of the bitmap.

aWidth int Width of the bitmap.

anAlignment int Alignment of the bitmap.

3.4.28 Set Flag When Idle

Method Name setFlagWhenIdle


Description

Method to set flag when idle; relevant for slip printing. Not applicable for fiscal printer.

Preconditions

Result



flag boolean True or false.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

4 Requirements For Fiscal Printers In Synchronous Mode

The JavaPOS interface allows devices to communicate with applications in two modes: asynchronous and syn-chronous. However, whether a fiscal printer can operate in asynchronous, synchronous or both modes depends on the capabilities of a particular printer.

SAP Enterprise POS was originally designed to support asynchronous communication with connected devices. To support communication with fiscal printers that only operate in synchronous mode, the SAP Enterprise POS communication capabilities have been enhanced.

The StandardSyncFiscalPrinterService class provided by SAP is the default synchronous implementa-

tion of IFiscalPrinterService. This class will be referred to as the default or standard implementation in

this section.

The following diagram is a high level representation of the enhancements to support both modes of communica-tion between SAP Enterprise POS and the fiscal printer:

JavaPOS DeviceJavaPOSUser ExitePOS Standard Code

JavaPOS/

UPOS

Default Async

Implmentation of


Fiscal Printer

(Sync/Async)

Default Sync

Implmentation of


Custom Async

Implmentation of


Custom Sync

Implmentation of


4.1 Configuring the Client

The SAP Enterprise POS SP06, which includes the new fiscal printer support, is configurable so that fiscal prin-ters operating in either the asynchronous or the synchronous mode are supported. To achieve this, two new

properties have been introduced to the device.properties file. Both properties are commented out in the

device.properties file and only need to be set if you are connecting a fiscal printer that only supports the

synchronous mode of communication.

Property Description Settings

FiscalPrinter1.asyncMode Specifies whether the fiscal printer connected to the particular POS Client can communi-cate in asynchronous mode.

true

false (default)

FiscalPrinterUserExit Specifies the user exit service class that will be used by SAP Enterprise POS to commu-nicate to the fiscal printer.

Name of the class. By default, rEx-

it=com.triversity.transacti

onware.framework.

deviceservices.jpos.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

StandardSyncFiscalPrinter-

Service

In SAP Enterprise POS, the printer mode setting (synchronous or asynchronous) found in PrintManager is not

modifiable through a user exit. Therefore, prior to sending the print call to the implementation of IFiscalPrin-

terService, the PrintManager must determine the printer’s mode of operation by checking the configuration

in device.properties.

The FiscalPrinter1.asyncMode and the FiscalPrinterUserExit settings are used by SAP Enterprise

POS to determine the user exit implementation class as follows:

Determine Fiscal

Printer Service

Class

Value of FiscalPrinter1.asyncMode in devices.propertiesDefault Service Class:

StandardFiscalPrinterService.java

FiscalPrinterUserExit defined in devices.properties

true

false

Service Class = Default

Service Class

Default Service Class:

StandardSyncFiscalPrinterService.java

No

Yes

Class Exists?

No Yes

Service Class = value

in FiscalPrinterUserExit

in device.properties

In summary, to implement a Fiscal Printer User Exit for fiscal printers that only operate in synchronous mode:

1. Use the standard default implementation, StandardSyncFiscalPrinterService, as a reference to

create a custom implementation.

2. Make the necessary changes in the device.properties file to activate the custom implementation.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

4.2 Error Handling

For fiscal printers that operate in synchronous mode, all fiscal commands are sent in synchronous manner, which dictates that the error events are sent back to the user exit implementation immediately after each fiscal command is executed.

With the standard implementation provided by SAP in StandardSyncFiscalPrinterService, no subse-

quent commands are sent down to the printer once an error event is produced by the device. As the registering of listeners to the fiscal printer is only needed for asynchronous communications, common error events, such as printer lid open or printer out of paper, do not get sent to the implementation until a fiscal command is sent to the printer. As a result, error handling had to be enhanced to support the synchronous printing mode.

Error handling is specific to each particular fiscal printer model. For instance, some fiscal printers are able to re-cuperate from errors without application intervention to rectify the issue. This could include the canceling of the current document being printed and placing the printer in a monitoring state. Other fiscal printers may require the application to intervene, which results in a reset of the printer and the actual cancelling of the transaction. With the introduction of the synchronous printing mode for fiscal printers, the Fiscal Printer User Exit determines the state in which the client should be upon the receipt of an error issued by a connected device. The following diagram summarizes the flow:

Start Printing of Document

Execute Next

available line

Error Event?

More Lines available to print?

No

Yes

Yes

Map Error

Event to

ePOS event

End of Document Printing

Reprint can be prompted for

Operational

issue (i.e.

printer out of

paper)

Invalid fiscal

command.

Critical error;

cancelled

printout

Notify

FiscalPrinter

Listener of

error event

YesNo

ePOS event is:

IDslConst.DSL_FISCAL

_PROMPT_FOR_REP

RINT

ePOS event is:

IDslConst.DSL_FISCAL

_ABORT_TRX

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Currently, two specific error scenarios have been determined for the Hungarian fiscal printer:

An incorrect configuration of documents or master data, which cannot be resolved by the user exit. The fiscal printer automatically cancels the document and sets the printer in a monitoring state. The SAP Enterprise POS application displays a notification message of a cancelled transaction and aborts the

transaction appropriately. This is mapped to an IDslConstant.DSL_FISCAL_ABORT_TRX event in

SAP Enterprise POS.

An ErrorEvent issued by the fiscal printer due to an operational issue, which can be corrected by the op-erator. The fiscal printer re-attempts to print the document. This is mapped to an

IDslConst.DSL_FICAL_PROMPT_FOR_REPRINT event in SAP Enterprise POS.

Note:

As all fiscal printer errors are mapped/generalized in the user exit to one of the two SAP Enterprise POS ErrorE-vents listed above, other ErrorEvents may need to be introduced. Consequently, for each identified fiscal printer error, it must be determined if the error falls into one the two SAP Enterprise POS ErrorEvents or if a new Erro-rEvent needs to be created/requested.

5 Configuration

5.1 Fiscal Printer User Exit Classname

To use your Fiscal Printer User Exit you must set the FiscalPrinterUserExit property in the de-

vice.properties file to the fully qualified class name of the Fiscal Printer User Exit implementation class.

The device.properties file is located in the EPOS_HOME/custom/client/ folder.

The FiscalPrinterUserExit property name is suffixed with a number, starting with one (1). Incrementing

this number allows you to load multiple Fiscal Printer User Exits in the POS Clients.

Example:

device.controls.1=com.triversity.transactionware.framework.deviceservices.triversity

device.controls.2=com.triversity.transactionware.framework.deviceservices.ingenico

device.controls.3=com.triversity.transactionware.framework.deviceservices.eftuserexit

FiscalPrinterUserExit1=com.saptrv.te.userexit.fiscalprinter.FPDevice

In the above example, com.saptrv.te.userexit.fiscalprinter.FPDevice class should be replaced

with the fully qualified class name of the Fiscal Printer User Exit implementation class.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

5.2 Setting The Classpath

The startpos.cmd and startpos.sh must be updated to include the location of the Fiscal Printer User Exit

implementation JAR file in the POS Client classpath. The example below highlights where the FiscPrin-

ter.jar file is added to the POS Client path. The FiscPrinter.jar file provides an implementation of Fiscal

Printer User Exit. The default sample implementation of the user exit (StandardFiscalPrinterService) is

included in the dsllocal.jar file.

:

REM Add Triversity Jars to classpath

SET CP=%CP%;.\security

SET CP=%CP%;.\lib\tw-security.jar

SET CP=%CP%;.\lib\was-stubs.jar

SET CP=%CP%;.\lib\client-updates.jar

SET CP=%CP%;.\lib\client.jar

SET CP=%CP%;.\lib\editor.jar

SET CP=%CP%;.\lib\te_clientsrvr.jar

SET CP=%CP%;.\lib\loaderutil.jar

SET CP=%CP%;.\lib\EFTUserExit.jar

SET CP=%CP%;.\lib\FiscPrinter.jar

SET CP=%CP%;.\lib\dsl.jar

SET CP=%CP%;.\lib\dsllocal.jar

SET CP=%CP%;.\lib\tef_logging.jar

SET CP=%CP%;.\lib\tef.jar

SET CP=%CP%;.\lib\ext\j2ee.jar

SET CP=%CP%;.\lib\ext\jpos17.jar

SET CP=%CP%;.\lib\ext\ib6core.jar

:

Ensure that all of the classes required for your implementation are present in the classpath by either adding a JAR file name or a fully qualified directory name containing all of your required classes to the POS Client class-path.

6 Using The Fiscal Printer

6.1 Configurator Settings

Once the SAP Enterprise POS application, which includes your Fiscal Printer User Exit, has been installed, ad-just the following SAP Enterprise POS Configurator settings:

Tax Group: Select the Send Tax Data to Fiscal Printer checkbox for each tax group whose accumu-

lated tax rates should be used on the fiscal printer.

Tenders: Some fiscal printers have predefined indices for the different types of tenders. If the fiscal

printer being used has these indices, they should be entered in the Tenders configuration. When such

indices exist, they are supplied by the fiscal printer provider, and should be entered in the Fiscal Pre-

defined Payment Index text box.

For more information on SAP Enterprise POS Configurator settings, refer to the SAP Enterprise POS Application Help.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

6.2 ~FISCAL Function

A new function has been introduced into the Document language: ~FISCAL(command, param1, param2,

…, paramN). This function allows commands to be sent to the fiscal printer and it can be used anywhere

throughout the SAP Enterprise POS documents. Using the fiscal commands requires additional implementation in the Fiscal Printer User Exit.

The most common use of the fiscal function is to send and execute jPOS commands on the fiscal printer. The

first parameter of the ~FISCAL() function is the jPOS method name, for example, printRecItem. The rest of

the parameters of the ~FISCAL() function are the parameters used by the selected jPOS method. For example,

if printRecItem is used as the first parameter in the ~FISCAL() function, the five parameters used by the

printRecItem jPOS method should be used as the last five parameters of the ~FISCAL() function.

6.3 Saving the Fiscal Document Number into TLog

It is possible to fetch the fiscal document number generated by the fiscal printer and store it in the TLog. You can then use the document number during the return scenario.

The functionality can be broken down as follows:

Fetch and store the fiscal document number.

o When the fiscal receipt is generated, get the fiscal document number.

o Put the fiscal document number into the TLog.

Implement the return scenario.

o During a return, prompt the register operator for the fiscal document number.

o Check that the entered fiscal document number matches the one stored in the retrieved transac-

tion. Allow the return to proceed if the document numbers match.

6.3.1 Saving the Fiscal Document Number

The fiscal document number can be retrieved from the class used to implement the IFiscalPrinterService

interface. The way to obtain the fiscal document number varies depending on your particular fiscal printer model and implementation of JavaPOS.

In the default StandardFiscalPrinterService implementation, the retrieval of the fiscal document number

is simulated by calling the getFiscalDocumentNumber() method of the outputCompleteOccurred() me-

thod of the JposFiscalPrinterListener private class.

In your implementation of the Fiscal Printer User Exit, the fiscal document number is communicated to the Fis-

calPrinterListener via a statusUpdateEvent(IdslConst.DSL_SUE_SEND_QUEUE_EMPTY). The ob-

ject array that is sent with the status update event is used for this purpose. The example below illustrates this communication:

Synchronized (statusUpdateListeners) {

Object[] info = new Object[2];

=> info[1] = getFiscalDocumentNumber(anEvent);

printerStatusUpdateEvent.recycle(IdslConst.DSL_SUE_SEND_QUEUE_EMPTY, info);

~FISCAL(setPostLine, ||%code% - %department%)

~FISCAL(printRecItem, %description%, ~value(%price%), %quantity%, %taxcode%,

~value(%unitprice%), %unitOfMeasure%)

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

// deliver the event to all registered listeners

int statusUpdateListenersSize = statusUpdateListeners.size();

for (int nListener = 0; nListener < statusUpdateListenersSize; nListener++) {

statusUpdateListeners.get(nListener).

statusUpdateOccurred(printerStatusUpdateEvent);

}

}

SAP Enterprise POS application then uses the FiscalPrinterListener class to access the current electron-

ic journal of the POS Client and stores the fiscal document number in that object. In turn, the journal object is

sent to the server; the JournalACO has a new property (TlogProperty. FISCAL_DOC_ID.getName(),

journal.getFiscalDocId()) in the supplemental data property to store the fiscal document number. This

also propagates the fiscal document number and saves it in the TLog.

6.3.2 Return Scenario

During a return, the POS Client can prompt the register operator for the fiscal document number. Once the regis-ter operator enters the number (which they obtain from the printed receipt), the application attempts to match it to the fiscal document number saved when the transaction was recorded before allowing the return. The POS Client configuration required for the return scenario is:

Create a new IDataType: FISCAL_DOC_ID.

In the UDF that executes the ‘return with receipt’ functionality, update the data form to include the new

IDataType, FISCAL_DOC_ID, as a piece of required data.

On invocation, the register operator enters the fiscal document number.

The register operator enters the transaction number.

SAP Enterprise POS application uses the transaction number to recall the transaction in the Prior-

TransactionSRQ. If the request data includes the FISCAL_DOC_ID value, the application ensures

that the recalled transaction has a matching fiscal document number.

6.4 Paragraph Class

The Paragraph class is used to wrap the lines of the configuration documents. It must be used in the Fiscal

Printer User Exit implementation of the Print method. A paragraph contains a list of line buffers for each line of

the document to be processed.

Paragraph()

Paragraph(List<LineBuffer>)

Paragraph(String)

Paragraph(String, List<LineBuffer>)

void add(LineBuffer)

void addAll(Paragraph)

void clear()

List<LineBuffer> getLines()

String getName()

int size()

String formName

List<LineBuffer> paragraph

Paragraph

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

The following example from the StandardSyncFiscalPrinterService implementation illustrates the usage

of the Paragraph class. The code loops through all the LineBuffers contained in the paragraph and determines

the type of line that should be printed.

Paragraph firstForm = receipt.get(0);

for (LineBuffer lb: firstForm.getLines()) {

if (lb.getType() == LineBuffer.FISCAL) {

if (lb.getText().startsWith("beginFiscal") ||

lb.getText().startsWith("setFiscalReceiptType")){

// New fiscal receipt

isFiscalReceipt = true;

}

else if (lb.getText().equals("printXReport") ||

lb.getText().equals("printZReport") ||

lb.getText().equals("printPowerLossReport") ||

lb.getText().equals("printPeriodicTotalsReport") ||

lb.getText().equals("printReport")) {


endingEvent = IDslFiscalPrinterConst.DSL_FPTR_SUE_IDLE;

}

else if (lb.getText().equals("beginTraining") ||

lb.getText().equals("endTraining")) {

// Need to generate IDLE event at the end because beginTraining/

// endTraining triggers receipt printing but without output com-

plete

// event.


endingEvent = IDslFiscalPrinterConst.DSL_FPTR_SUE_IDLE;

}

break;

}

}

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

6.5 ReceiptDescriptors

The ReceiptDescriptors class is used to contain the receipt formatting information. It must be used in the

Fiscal Printer User Exit implementation of the Print method. It can include receipt margins, lines per page,

whether or not there should be a paper cut, and whether or not the receipt contains sensitive data.

ReceiptDescriptors()

int getLeftMargin()

int getLeftMargin()

int getTopMargin()

boolean isNoPaperCut()

boolean isSensitiveData()

void setLeftMargin(int)

void setLinesPerPage(int)

void setNoPaperCut(boolean)

void setSensitiveData(boolean)

void setTopMargin(int)

String toString()

int topMargin

int leftMargin

int linesPerPage

boolean noPaperCut

boolean sensitiveData

ReceiptDescriptors

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63


of the ReceiptDescriptors class. In this example, the value returned by the getLeftMargin method is

passed as a parameter to the adjustAlignments method of the DocumentUtil method. The DocumentU-

til method adjusts the alignments of the receipt to be printed.

..

..

ReceiptDescriptors descriptor = aDescriptor;

..

..

case LineBuffer.TEXT:

if (isFiscalReceipt) {

// we have fiscal lines, so ignore this.

continue;

}

line.setLength(0);

line.append(lb.getText());

DocumentUtil.adjustAlignments(line, descriptor.getLeftMargin(), receipt-

Width);

DocumentUtil.replaceAttributes(line, substitutionsPrinter);

DocumentUtil.expandCaretCharacter(line, receiptWidth);

normalText.append(line.toString()).append("\n");

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

6.6 LineBuffer

The LineBuffer class is used to send a line to the printer. The line is based on the line definitions in the Con-

figuration documents. A List of LineBuffers is an attribute of the Paragraph class that stores all the lines to

be printed.

One of the attributes of LineBuffer is Type, which sets the type of line to send to the printer. The following

line types are permitted:

TEXT

BARCODE

BITMAP

MARKER

REMOTE_FORM

IMAGE

PAUSE

REPEAT

TEXTAT

FISCAL

All lines sent to the fiscal printer should be of type FISCAL.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Operations

decrementRepeatCount()

getColumnt()

getFormat()

getHeight()

getParameters()

getPause()

getRepeatCount()

getRepeatOutputForm()

getRow()

getSymbology()

getText()

getTextPosition()

getType()

getVariables()

getWidth()

isNoAttributeSubstitution()

isStoredOnly()

isTemporary()

readExternal(ObjectInput)

setAlignment(int)

setColumn(int)

setFormat(String)

setHeight(double)

setNoAttributeSubstitution(boolean)

setParameters(String[])

setPause(double)

setRepeatCount(int)

setPause(double)

setRepeatOutputFrom(int)

setRow(int)

setStore(string)

setSymbology(int)

setText(String)

setTextPosition(int)

setType(int)

setVariables(Map<String,Object)>)

setWidth(double)

toString()

toXML(()

writeExternal(ObjectOutput)

getAlignment()

Attributes

ABOVE

AS_IS_WIDTH

BARCODE

BELOW

BITMAP

CENTER

FISCAL

IMAGE

LEFT

MARKER

NO_ATTRIBUTE_SUBSTITUTION

NONE

PAUSE

POSITION_TAG

REMOTE_FORM

REPEAT

RIGHT

ALIGNMENT_TAG

TEXT

TEXTAT

TYPE_TAG_TEXT

SERIAL_VERSION

serialVersionUID

STORE

TEMPORARY

alignment

height

multiUseVar1

multiUseVar2

multiUseVar3

multiUseVar4

parameters

text

type

variables

LineBuffer

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63


of the LineBuffer class. The code loops through all the LineBuffers contained in the paragraph and deter-

mines how the lines should be processed.

for (LineBuffer lb: form.getLines()) {

switch (lb.getType()) {

case LineBuffer.FISCAL:


List<String> toParams = new ArrayList<String>();

String[] fromParams = lb.getParameters();

if (fromParams != null && fromParams.length > 0) {

for (int i = 0; i < fromParams.length; i++) {

toParams.add(fromParams[i]);

}

}

boolean executed = executeFiscalFunction(lb.getText(), toPa-

rams);

if (!executed) {

errorOccurred = true;

break;

}

}

break;

case LineBuffer.BARCODE:

if (!isFiscalReceipt) {

// Non-fiscal receipt: Delay barcode printing to the end

endRequestList.add(lb);

} else {

printBarCode(aStationId, lb.getText(),

getSymbology(lb.getSymbology()), 0 ,0 ,0);

}

break;

case LineBuffer.TEXT:


// we have fiscal lines, so ignore this.

continue;

}

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

line.setLength(0);

line.append(lb.getText());

DocumentUtil.adjustAlignments(line, descriptor.getLeftMargin(),

receiptWidth);

DocumentUtil.replaceAttributes(line, substitutionsPrinter);

DocumentUtil.expandCaretCharacter(line, receiptWidth);\

normalText.append(line.toString()).append("\n");

} // switch (lb.getType()) {

} // for (LineBuffer lb: form) {

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

7 Java BAdI Implementation For Fiscal Printer

7.1 Introduction

Enhancement Spots and BAdIs (Business Add-Ins) are well-known and proven concepts in the ABAP framework to alter, to decorate or to extend existing SAP functionality with customer enhancements without modifying the original source code. Enhancement Spots are defined and provided by SAP development within the SAP appli-cations. BAdIs are customer implementations for the Enhancement Spots. A detailed description of the ABAP based Enhancement Spots and BAdIs can be found in the NetWeaver online documentation.

The Enhancement Concept (EHC) for SAP Enterprise POS realizes a similar1 concept; Java Enhancement

Spots and Java BAdIs allow modification-free enhancements of the SAP Enterprise POS core application.

7.2 Main Building Blocks and Entities

7.2.1 Enhancement Concept Framework

The EHC Framework is embedded in the SAP Enterprise POS core application and allows SAP development to define and provide Enhancement Spots within the SAP Enterprise POS core application. Non-SAP development, for example customers or SAP Custom Development Projects (CDP), can then provide implementations for the developed Enhancement Spots, which are executed at runtime.

7.2.2 Enhancement Spots

Enhancement Spots are dedicated locations within the core application, where existing (business) functionality can be enriched, altered or decorated. SAP core development may provide an Enhancement Spot by defining and publishing a Java Interface. Aside from providing the Java Interface, developers must configure the En-hancement Spot, so that the EHC Framework will execute the custom implementation at runtime.

There are two types of Enhancement Spots:

Enhancement Spots that allow a single implementation, that is, only a single BAdI implementation may be provided for the Enhancement Spot.

Enhancement Spots that allow multiple implementations, where multiple BAdI implementations may be provided for the Enhancement Spot.

7.2.3 BAdI Interfaces

SAP core development provides a default Java interface for each Enhancement Spot. The implementation of a BAdI interface is referred to as a (Java) BAdI interface implementation, or simply, the BAdI. The BAdI is the con-tract between the SAP Enterprise POS core application and the implementer of the enhancement. The BAdI de-scribes the semantics (the expected behavior as well as the boundary conditions for the implementation) and de-fines the signature (the input and the output parameters). All BAdI interfaces are located in a separate Develop-ment Component (DC), which belongs to the SAP Enterprise POS core application.

The BAdI interface defines the following:

The execute method, which must be implemented and which is invoked by the EHC Framework at run-

time.

The type of the input parameter, which is passed to the implementation.

The type of the output parameter, which may be returned as a result.

Additionally, the signature of the execute method specifies, which exceptions may be thrown at runtime.

1 The Enhancement Concept for SAP Enterprise POS is not a one-to-one re-implementation of the ABAP BAdI

concept, it is an adaptation of core BAdI concepts for a Java framework.

http://help.sap.com/saphelp_nw70ehp1/helpdata/en/c2/eab541c5b63031e10000000a155106/frameset.htm

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

If a BAdI interface extends the interface IBAdIMulti, multiple BAdI interface implementations may be provided

for the Enhancement Spot.

7.2.4 BAdI Interface Implementations

A BAdI does not belong to the SAP Enterprise POS core application and has its own software lifecycle. Future upgrades of the original business function can be applied without losing the customer-specific enhancements or the need to merge the changes.

BAdI implementations are provided by customers and SAP non-core development (like CDP). If no BAdIs have been provided by customers or SAP non-core development, the default BAdI implementations provided by SAP core development are executed by the framework.

7.2.5 Enhancement Spot Configuration

In order for the EHC Framework to execute the BAdI, the BAdI provider has to configure the Enhancement Spot. The EHC Framework determines the Enhancement Spot Configuration at runtime.

The creation of Enhancement Spot Configuration is currently a manual process. The configuration contains the name(s) of the BAdI for the particular Enhancement Spot. For Enhancement Spots that allow a single implemen-tation, the configuration contains the name of the class that implements the BAdI interface. For Enhancement Spots that allow multiple implementations, the configuration contains a list of class names, which implement the BAdI interface in execution sequence.

The Enhancement Spot Configuration is owned by the customer (or SAP non-core development) exclusively. Except for the default BAdI implementations, all BAdI implementations to be executed at runtime have to be ex-plicitly configured by the customer.

7.2.6 Enhancement Concept Runtime

The Enhancement Concept Runtime is part of the EHC Framework, which is part of the SAP Enterprise POS core application. The runtime is responsible for:

Passing the input parameters (as defined and provided by SAP Enterprise Core Development) to the BAdI interface implementation

Executing the configured BAdI interface implementations

Retrieving the result from the BAdI interface implementation

The Enhancement Concept Runtime executes the BAdI interface implementations synchronously and in se-quence (in case of an Enhancement Spot with multiple implementations).

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

The following diagram shows the behavior of the EHC Framework at runtime:

Enhancement Spot FrameworkSAP Core Development

(SAP Enterprise POS)

Start of

core application

Execute core

application

EnhancementSpot

callBAdI()

Retrieve

Configuration

Enhancement

Spot

Configuration

Configuration

available

no Configuration

available

Execute

configured BAdI

Implementation

Execute

default BAdI

Implementation

default BAdI

Implementation

available

more configured

BAdIs available

no Error

occured

Error

occured

Error

occured

Throw

Exceptionall configured

BAdIs processed

Continue execution

of core application

no Error

occured

no default BAdI

Implementation

available

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

7.3 How to implement a BAdI for an Enhancement Spot

This chapter describes the process of creating an implementation for an Enhancement Spot in SAP Enterprise POS 3.1 SP06.

7.3.1 Prerequisites

The following table lists the requirements.

Requirement Type Requirement

Hardware Requirement Developer PC

Software Requirements

Java SE Development Kit JDK 5

Java IDE

For example, SAP NetWeaver Development Studio, Eclipse or IDEs with comparable functionality

SAP Enterprise POS 3.1 BAdI interfaces

7.3.2 Procedure

The following steps have to be performed:

1. Download and install the Java JDK.

The JDK can be downloaded at http://www.oracle.com/technetwork/java/index.html.

2. Download and install the JAVA IDE.

NWDS is part of the SAP NetWeaver delivery. Eclipse can be downloaded at http://www.eclipse.org.

3. Provide the JAR file containing the BAdI interfaces.

The interfaces are bundled in the jar file sap.com~is~isr~epos~badi_interfaces~assembly.jar. The jar file is part of the SAP Enter-

prise POS 3.1. Software Component Archive (SCA) file. The SCA file is part of the SAP Enterprise POS 3.1 software delivery.

4. Provide the optional logging JAR files.

The SAP EPOS proprietary logging API is contained in the jar file sap.com~is~isr~epos~tef_logging~assembly.jar. This file is also part of the SAP Enterprise

POS 3.1. Software Component Archive (SCA) file.

Note:

The appropriate version of a j2ee.jar is also required if using the SAP logging API.

http://www.oracle.com/technetwork/java/index.html

http://www.eclipse.org/

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Tip:

Software Component Archives (SCA) files and Software Deployment Archives (SDA) files are zip files, which contain development artifacts such as resources, descriptors, and possibly a directory hierarchy with further JAR and SDA files. In order to extract the required resources from an SCA file or an SDA file, you may need to re-

name the source file from MySoftwareArchive.sca to MySoftwareArchive.zip.

All jar files mentioned above can be found in:

SAP Enterprise POS 3.1. Software Component Archive (SCA) file DEPLOYARCHIVES

is~isr~epos~te_deliver.sda build lib or in one of the subdirectories.

7.4 Implementation of the Java BAdI for Barcode Printing

The following sections describe the process of implementing a Java BAdI for Barcode printing on the Epson FP90 fiscal printer model by providing a sample implementation for the POS Client Print Barcode Enhance-ment Spot. Further information can be found in the Javadoc of the corresponding BAdI interface.

Caution:

The sample implementation described in this and the following subsections has been implemented in an Eclipse-based development environment (for example, SAP NetWeaver Development Studio or Eclipse Ganymede). Some steps may have to be adjusted for other IDEs.

The sample implementation of the barcode printing BAdI interface is: package com.sap.epos.badi.interfaces.deviceservices;

import com.sap.epos.badi.interfaces.IBAdI;

import com.sap.epos.badi.interfaces.IBAdIContext;

import com.sap.epos.badi.interfaces.IBAdIMulti;

public interface IBAdIPackageBarcode extends IBAdI<IBAdIPackageBarcodeInput,

IBAdIPackageBarcodeOutput>{

/**

* Enhancement Spot executed while performing a POS Client Print barcode.

* The Enhancement Spot is invoked when calling the print barcode method for a

* fiscal printer.

* The implementation has the ability to build the barcode format for the

* target fiscal printer

* @param IBAdILogOnInput input object available to the Enhancement Spot

* implementation

* @param IBAdILogOnOutput output object implementation uses to relay

* information back to the core application

*/

public void execute(IBAdIContext<IBAdIPackageBarcodeInput, IBAdIPackageBarco-

deOutput> context);

public static final String BADI_DESCRIPTION = "Enhancement spot invoked when

attempting to print a barcode on a Fiscal Printer.";

}

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Additionally, two interfaces are provided: one for the input and one for the output parameter.

The interface for the input parameter is:

package com.sap.epos.badi.interfaces.deviceservices;

/**

* The input object interface to the BAdI Enhancement spot invoked when a POS

* Client print barcode is performed.

* The implementation can perform further processing for the barcode printing

*/

public interface IBAdIPackageBarcodeInput {

/**

* Data to convert to a bar code.

* @return some Text

*/

public String getBarcodeData();

/**

* Retrieve the bar code symbology. See <code>ScanDataType</code> for

* possible values.

* @return a symbology type.

*/

public int getSymbology();

/**

* The height of the barcode in printer dots. This value may be ignored by

* the implementor.

* @return the expected height of the barcode.

*/

public int getHeight();

/**

* The width of the barcode in printer dots. This value may be ignored by the

* implementor.

* @return the expected width of the barcode.

*/

public int getWidth();

/**

* The positioning of the barcode relative to the paper.

* 0 - left aligned

* 1 - centered

* 2 - right aligned

* The implementation may ignore this value.

* @return the expected alignment of the barcode.

*/

public int getAlignment();

/**

* The positioning of the text of the barcode, relative to the barcode.

* 0 - none - don't display the text

* 1 - below<

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

* 2 - above

* @return

*/

public int getTextPosition();

The interface for the output parameter is:


/**

* The output object interface from the BAdI Enhancement spot invoked when a

* POS Client print barcode is performed. The implementation can perform

* further processing to build the barcode pertaining to the target fiscal

* printer

*/

public interface IBAdIPackageBarcodeOutput {

/**

* Get the command to send as the first parameter of the directIO call.

* @return an integer command.

*/

public int getCommand();

/**

* Get the data to send as the second parameter of the directIO call.

* @return the integer command array data.

*/

public int[] getCommandArray();

/**

* Get the packaged Object that could be sent to the printer via a

* directIO call to print a barcode of the given data.

* @return a packaged Object suitable to send via a directIO call, or null if

* it can't convert to a barcode.

*/

public Object getObject();

}

7.4.1 Create a new Java Project

You must first create a new Java Project, which will be used for the creation of a new implementation for a BAdI interface.

1. Start the IDE. 2. Go to File New Java Project to create a new Java Project, enter the project name and press Next. 3. Add the BAdI interfaces to the build path of the Java Project:

a. In the Package Explorer, right-click on the Java project and select Properties Java Build Path Libraries Add External Jars.

b. Browse to select sap.com~is~isr~epos~badi_interfaces~assembly.jar.

c. Browse to select sap.com~is~isr~epos~badi_interfaces~assembly.jar.

d. Browse to select sap.com~is~isr~epos~te_framework~assembly.jar.

e. Click OK.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

4. Optionally, add the SAP EPOS logging API JAR to the build path of the Java Project. a. In the Package Explorer, right-click on the Java project and select Properties Java Build Path Libraries Add External Jars.

b. Browse to select sap.com~is~isr~epos~tef_logging~assembly.jar.

c. Browse to select j2ee.jar as the SAP logging API has dependencies on j2ee.jar classes.

d. Click OK.

7.4.2 Create the BAdI Interface Implementation Class

Once you have created a Java project, you need to create the Java class for the BAdI interface implementation of the Enhancement Spot:

1. In the Project Explorer, select File New Class. 2. Provide the package name. 3. Provide the class name for your BAdI interface implementation. 4. Add the BAdI interface to be implemented. 5. Optionally, add further interfaces. 6. Click Finish.

Recommendation:

To avoid name clashes with existing or future SAP development objects, do not use com.sap (or any other pre-fixes used by SAP core Java objects) as a prefix for the package name of your BAdI implementation. Instead, you may want to use a prefix that reflects the purpose of the BAdI or that reflects your organization. It is also recommended to use the prefix BAdI for the class name of the BAdI implementation.

Example:

If you want to implement a BAdI for the POS Client Print Barcode Enhancement Spot:

The sample BAdI interface name is com.sap.epos.framework.deviceservices.jpos.IBAdIPackageBarcode

Chose com.yourcompanyname.epos.framework.deviceservices.jpos.yourprinter.packageBar

code as package name

Chose BarcodeSampleImpl as class name for the BAdI implementation

Having performed the above steps, the following result will be available:

A new class: com.yourcompanyname.epos.framework.deviceservices.jpos.yourprinter.packageBar

code.BarcodeSampleImpl has been created in your Java project.

The class implements the BAdI interface: com.sap.epos.badi.interfaces.deviceservices.IBAdIPackageBarcode

The result should look like this:

package

com.yourcompanyname.epos.framework.deviceservices.jpos.yourprinter.packageBarcode;

import jpos.FiscalPrinter;

import jpos.FiscalPrinterControl17;

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63


import com.sap.epos.badi.interfaces.deviceservices.IBAdIPackageBarcode;

import com.sap.epos.badi.interfaces.deviceservices.IBAdIPackageBarcodeInput;

import com.sap.epos.badi.interfaces.deviceservices.IBAdIPackageBarcodeOutput;

public class BarcodeSampleImpl implements IBAdIPackageBarcode {

public void execute(IBAdIContext<IBAdILogOnInput, IBAdILogOnOutput> context){

// TODO Auto-generated method stub

}

}

7.4.3 Implement the Output interface

If the output object of your BAdI consists of an interface, implement a concrete output object interface. The BAdI business logic populates the output object interface to relay information back to the core SAP Enterprise POS application.

The interface IBAdIPackageBarcodeOutput defines the data type of the output parameter of the BAdI inter-

face IBAdILogon. The interface for the import parameter is provided by SAP and the import parameter is

passed to the EHC Framework.

In the sample implementation, IBAdIPackageBarcodeOutput can be implemented as follows: package


/**

* An example implementation of the IBAdIPackageBarcodeOutput interface

*/


public class PackageBarcodeBitmapOutput implements IBAdIPackageBarcodeOutput {

/**


*


*/

public StringBuffer buf;

public int[] commArray = { 1075 };// Apply for the EPSON FP90 Fiscal Printer Model

// public int[] commArray = 0 // Apply for the IBM 4610 Fiscal printer model

public int command;

public PackageBarcodeBitmapOutput() {

this.buf = new StringBuffer();

this.command = 0;

}

public int getCommand() {

return this.command;

}

/**

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63


*


*/

public int[] getCommandArray() {

return this.commArray;

}

/**

* Get the packaged Object that could be sent to the printer via a directIO

* call to print a barcode of the given data.

*

* @return a packaged Object suitable to send via a directIO call, or null

* if it can't convert to a barcode.

*/

public Object getObject() {

return this.buf;

}

public int setCommand() {

return 1;

}

public int setCommandArray(int[] aCommand) {

if (aCommand != null) {

this.commArray = aCommand;

}

return 1;

}

public StringBuffer setBuffer(StringBuffer aBuf) {

return this.buf = aBuf;

}

}

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

7.4.4 Implement the Business Logic of the BAdI implementation

You must provide the business logic for your BAdI implementation within the execute method of your BAdI.

At runtime, an instance of an IBAdIContext object is passed to the execute method by the EHC framework.

This context object allows you to access the input parameter and to set an output parameter as a result.

The IBAdIContext interface provides the following methods: package com.sap.epos.badi.interfaces;

/**

* Interface definition representing the context of the BAdI execution.

* This type shall be the only parameter of any BAdI interface method.

* The BAdI implementer classes access the context functionality by the

* methods of this interface.

* @param <BAdIInput> data type of the input parameter of the BAdI

* @param <BAdIOutput> data type of the output parameter of the BAdI

*/

public interface IBAdIContext<BAdIInput, BAdIOutput> {

/**

* Retrieves the input of the BAdI. It contains the current input value of

* the BAdI execution, that can be the original value given by the standard

* code, or the modified one if there were any preceding BAdI implementer

* which modified it.

* @return input

*/

public BAdIInput getInput();

/**

* Stores the input of the BAdI into the context. It can be used when one

* implementor wishes to modify the input.

* @param input

*/

public void setInput(BAdIInput input);

/**

* Retrieves the output of the BAdI. This is null when no implementer have

* set it yet, or contains the current value of the output.

* @return output

*/

public BAdIOutput getOutput();

/**

* Stores the output of the BAdI in the context.

* @param output

*/

public void setOutput(BAdIOutput output);

/**

* Makes a proposal to terminate the BAdI execution.

* @param terminationProposal

*/

public void setTerminationProposal(boolean terminationProposal);

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

/**

* Retrieves proposal to terminate the BAdI execution

* @return termination proposal

*/

public boolean getTerminationProposal();

/**

* Retrieves the BAdI Interface class

* @return BAdI Interface class

*/

public Class<? extends IBAdI<BAdIInput, BAdIOutput>> getBAdIInterface();

}

The following boxes show the sample BAdI implementation of the IBAdIBarcode interface for the Epson FP90

fiscal printer.

The BarcodeSampleImpl implementation returns a barcode string which is built for the target fiscal printer.

package








import com.triversity.tef.util.logging.Log;

import

com.triversity.transactionware.framework.deviceservices.DeviceServiceException;

import com.triversity.transactionware.framework.deviceservices.ScanDataType;

import

com.triversity.transactionware.framework.deviceservices.jpos.StandardFiscalPrinterS

ervice;

/**

* Sample BAdI Implementation for the IBAdIBarcode interface, This

* implementation will provide a sample implementation for the Fiscal Printer

* Barcode printing.

*

*/


protected static FiscalPrinterControl17 printer = new FiscalPrinter();

protected static StandardFiscalPrinterService printerService = new StandardFiscal-

PrinterService();

package com.saptest.epos.framework.deviceservices.jpos.epsonFP90.packageBarcode;


SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63






/**



* Barcode printing.

*

*/



/**

* Method will provide access to the default implementation for the

* IBAdIBarcode as a result of the BAdIOutput.

*/

public void execute(

IBAdIContext<IBAdIPackageBarcodeInput, IBAdIPackageBarcodeOutput> context) {

IBAdIPackageBarcodeOutput output = new PackageBarcodeBitmapOutput();

IBAdIPackageBarcodeInput input = context.getInput();

output = buildBarcode(input);

context.setOutput(output);

} // end execute

/**

* @param ignoredStationId

* one of IDeviceSet.DEVICE_RECEIPT, DEVICE_SLIP, DEVICE_JOURNAL

* @param aSymbology

* an index into the ConfigPOSConstants.symbologies table

*/

public static PackageBarcodeBitmapOutput buildBarcode(String data,

int aSymbology, int ignoredHeight, int ignoredWidth,

int ignoredAlignment, int ignoredTextPosition) throws Exception {

PackageBarcodeBitmapOutput out = new PackageBarcodeBitmapOutput();

int[] command = { 1075 };

int code = -1;

int wmax = 0;

switch (aSymbology) {

case 104: // ScanDataType.DSL_BCS_EAN13:

code = 67; // 2

wmax = 5;

break;


code = 68; // 3

wmax = 8;

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

break;

case 101: // ScanDataType.DSL_BCS_UPCA:

code = 65; // 0

wmax = 5;

break;

case 102: // ScanDataType.DSL_BCS_UPCE:

code = 66; // 1

wmax = 8;

break;

case 108: // ScanDataType.DSL_BCS_CODE39:

code = 69; // 4

// Max length is 30

data = data.substring(0, Math.min(data.length(), 30));

if (data.length() >= 16)

wmax = 1;

else if (data.length() >= 10)

wmax = 2;


wmax = 3;


wmax = 4;

else

wmax = 8;

break;

case 106: // ScanDataType.DSL_BCS_ITF: // Interleaved 2 of 5

code = 70; // 5

// Max length is 54



wmax = 1;


wmax = 2;


wmax = 3;


wmax = 4;

else

wmax = 8;

break;

case 107: // ScanDataType.DSL_BCS_CODABAR:

code = 71; // 6

// Max length is 43



wmax = 1;


wmax = 2;


wmax = 3;


wmax = 4;


wmax = 5;

else

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

wmax = 8;

break;


code = 72;

// Max length is 52



wmax = 1;


wmax = 2;


wmax = 3;


wmax = 4;


wmax = 5;

else

wmax = 8;

break;


code = 73;

// Max length is 45



wmax = 1;


wmax = 2;


wmax = 3;


wmax = 4;


wmax = 5;

else

wmax = 8;

break;

case 105: // ScanDataType.DSL_BCS_TF:

case 120: // case ScanDataType.DSL_BCS_EAN128:

default:

// Not supported

// log.warn("Barcode symbology " + aSymbology + " not sup-

ported");

break;

}

if (code != -1) {

StringBuffer buf = new StringBuffer();

buf.append("01"); // Operator

buf.append("068"); // Horizontal position in points

buf.append(wmax); // Barcode Width

buf.append("064"); // Barcode height in points

buf.append("2"); // enabling printing HRI characters: 0=no

// 1=sopra 2=sotto 3=sopra e sotto

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

buf.append("1"); // font for characters HRI (0-3)

buf.append("00"); // Unused

buf.append(code); // Barcode type

buf.append(data); // Data

out.setBuffer(buf);

out.setCommandArray(command);

}

return out;

}

public static IBAdIPackageBarcodeOutput buildBarcode(

IBAdIPackageBarcodeInput input) {

/**

*

* The list of JavaPOS symbology DSL_BCS_UPCA = 101; //

* ScannerConst.SCAN_SDT_UPCA; // Digits DSL_BCS_UPCE = 102; //

* ScannerConst.SCAN_SDT_UPCE; // Digits DSL_BCS_JAN8 = 103; //

* ScannerConst.SCAN_SDT_JAN8; // = EAN 8 DSL_BCS_EAN8 = 103; //

* ScannerConst.SCAN_SDT_EAN8; // = JAN 8 DSL_BCS_JAN13 = 104; //


* ScannerConst.SCAN_SDT_EAN13; // = JAN 13 DSL_BCS_TF = 105; //

* ScannerConst.SCAN_SDT_TF; // (Discrete 2 of 5) // Digits DSL_BCS_ITF =

* 106; // ScannerConst.SCAN_SDT_ITF; // (Interleaved 2 of 5) // Digits

* DSL_BCS_CODABAR = 107; // ScannerConst.SCAN_SDT_Codabar; // Digits, -, $,

:, /, ., // +;

* 4 start/stop // characters (a, b, c, // d) DSL_BCS_CODE39 = 108; //

* ScannerConst.SCAN_SDT_Code39; // Alpha, Digits, Space, // -, ., $, /, +, %;

//

* start/stop (*) // Also has Full Ascii // feature DSL_BCS_CODE93 =

* 109; // ScannerConst.SCAN_SDT_Code93; // Same characters as // Code

* 39 DSL_BCS_CODE128 = 110; // ScannerConst.SCAN_SDT_Code128; // 128

* data characters DSL_BCS_UPCA_S = 111; //

* ScannerConst.SCAN_SDT_UPCA_S; // UPC-A with // supplemental barcode

* DSL_BCS_UPCE_S = 112; // ScannerConst.SCAN_SDT_UPCE_S; // UPC-E with //

* supplemental barcode DSL_BCS_UPCD1 = 113; //

* ScannerConst.SCAN_SDT_UPCD1; // UPC-D1 DSL_BCS_UPCD2 = 114; //




* ScannerConst.SCAN_SDT_UPCD5; // UPC-D5 DSL_BCS_EAN8_S = 118; //

* ScannerConst.SCAN_SDT_EAN8_S; // EAN 8 with // supplemental barcode

* DSL_BCS_EAN13_S = 119; // ScannerConst.SCAN_SDT_EAN13_S; // EAN 13

* with // supplemental barcode DSL_BCS_EAN128 = 120; //

* ScannerConst.SCAN_SDT_EAN128; // EAN 128 DSL_BCS_OCRA = 121; //

* ScannerConst.SCAN_SDT_OCRA; // OCR "A" DSL_BCS_OCRB = 122; //

* ScannerConst.SCAN_SDT_OCRB; // OCR "B"

* // Two dimensional symbologies DSL_BCS_PDF417 = 201; //

* ScannerConst.SCAN_SDT_PDF417; DSL_BCS_MAXICODE = 202; //

* ScannerConst.SCAN_SDT_MAXICODE;

* // Special cases DSL_BCS_VENDOR = 501; //

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

* ScannerConst.SCAN_SDT_OTHER; // Start of vendor- // specific bar code //

* symbologies DSL_BCS_UNKNOWN = 0; // ScannerConst.SCAN_SDT_UNKNOWN; //

* Cannot determine the // barcode symbology.

*

**/

IBAdIPackageBarcodeOutput output = null;


String aData = input.getBarcodeData();

int aSymbology = input.getSymbology();

int aIgnoredHeight = input.getHeight();

int aIgnoredWidth = input.getWidth();

int aIgnoredAlignment = input.getAlignment();

int aIgnoredTextPosition = input.getTextPosition();

try {

out = buildBarcode(aData, aSymbology, aIgnoredHeight,

aIgnoredWidth, aIgnoredAlignment, aIgnoredTextPosi-

tion);

output = out;

} catch (Exception e) {

}

return output;

}

}

The following boxes show the sample BAdI implementation of the IBAdIBarcode interface for the IBM 4610 fis-cal printer.

package com.saptest.epos.framework.deviceservices.jpos.epsonFP90.packageBarcode;







/**



* Barcode printing.

*

*/

public class BBoxBarcodeSampleImpl implements IBAdIPackageBarcode {

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63


/**

* Method will provide access to the default implementation for the

* IBAdIBarcode as a result of the BAdIOutput.

*/

public void execute(

IBAdIContext<IBAdIPackageBarcodeInput, IBAdIPackageBarcodeOutput> context) {

IBAdIPackageBarcodeOutput output = new PackageBarcodeBitmapOutput();

IBAdIPackageBarcodeInput input = context.getInput();

output = buildBarcode(input);

context.setOutput(output);

} // end execute

public static IBAdIPackageBarcodeOutput buildBarcode(

IBAdIPackageBarcodeInput input) {

IBAdIPackageBarcodeOutput output = null;


String aData = input.getBarcodeData();

int aSymbology = input.getSymbology();

int aIgnoredHeight = input.getHeight();

int aIgnoredWidth = input.getWidth();

int aIgnoredAlignment = input.getAlignment();

int aIgnoredTextPosition = input.getTextPosition();

try {

out = buildBarcode(aData, aSymbology, aIgnoredHeight,

aIgnoredWidth, aIgnoredAlignment, aIgnoredTextPosition);

output = out;

} catch (Exception e) {

}

return output;

}

/**

* @param ignoredStationId

* one of IDeviceSet.DEVICE_RECEIPT, DEVICE_SLIP, DEVICE_JOURNAL

* @param aSymbology

* an index into the ConfigPOSConstants.symbologies table

*/

public static PackageBarcodeBitmapOutput buildBarcode(String data,

int aSymbology, int ignoredHeight, int ignoredWidth,

int ignoredAlignment, int ignoredTextPosition) throws Exception {

/*

* --------------------------------------------------------------------

-----------------------

* The list of JavaPOS symbology DSL_BCS_UPCA = 101; //

* ScannerConst.SCAN_SDT_UPCA; // Digits DSL_BCS_UPCE = 102; //

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

* ScannerConst.SCAN_SDT_UPCE; // Digits DSL_BCS_JAN8 = 103; //


* ScannerConst.SCAN_SDT_EAN8; // = JAN 8 DSL_BCS_JAN13 = 104; //


* ScannerConst.SCAN_SDT_EAN13; // = JAN 13 DSL_BCS_TF = 105; //

* ScannerConst.SCAN_SDT_TF; // (Discrete 2 of 5) // Digits DSL_BCS_ITF

=

* 106; // ScannerConst.SCAN_SDT_ITF; // (Interleaved 2 of 5) // Digits

*

* DSL_BCS_CODABAR = 107; // ScannerConst.SCAN_SDT_Codabar; // Digits,

-, $, :, /, ., // +;

* 4 start/stop // characters (a, b, c, // d) DSL_BCS_CODE39 = 108; //

*

* ScannerConst.SCAN_SDT_Code39; // Alpha, Digits, Space, // -, ., $,

/, +, %; //

* start/stop (*) // Also has Full Ascii // feature DSL_BCS_CODE93 =

* 109; // ScannerConst.SCAN_SDT_Code93; // Same characters as // Code

* 39 DSL_BCS_CODE128 = 110; // ScannerConst.SCAN_SDT_Code128; // 128

* data characters DSL_BCS_UPCA_S = 111; //

*

* ScannerConst.SCAN_SDT_UPCA_S; // UPC-A with // supplemental barcode

* DSL_BCS_UPCE_S = 112; // ScannerConst.SCAN_SDT_UPCE_S; // UPC-E with

//

* supplemental barcode DSL_BCS_UPCD1 = 113; //

*





* ScannerConst.SCAN_SDT_UPCD5; // UPC-D5 DSL_BCS_EAN8_S = 118; //

* ScannerConst.SCAN_SDT_EAN8_S; // EAN 8 with // supplemental barcode

* DSL_BCS_EAN13_S = 119; // ScannerConst.SCAN_SDT_EAN13_S; // EAN 13

* with // supplemental barcode DSL_BCS_EAN128 = 120; //

*

* ScannerConst.SCAN_SDT_EAN128; // EAN 128 DSL_BCS_OCRA = 121; //

* ScannerConst.SCAN_SDT_OCRA; // OCR "A" DSL_BCS_OCRB = 122; //

* ScannerConst.SCAN_SDT_OCRB; // OCR "B"

* // Two dimensional symbologies DSL_BCS_PDF417 = 201; //

* ScannerConst.SCAN_SDT_PDF417; DSL_BCS_MAXICODE = 202; //

* ScannerConst.SCAN_SDT_MAXICODE;

* // Special cases DSL_BCS_VENDOR = 501; //

* ScannerConst.SCAN_SDT_OTHER; // Start of vendor- // specific bar

code //

* symbologies DSL_BCS_UNKNOWN = 0; // ScannerConst.SCAN_SDT_UNKNOWN;

//

* Cannot determine the // barcode symbology.

*

*/


int[] command = { 0 };

int code = -1;

switch (aSymbology) {


SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

code = 2; // 2

break;


code = 3; // 3

break;

case 101: // ScanDataType.DSL_BCS_UPCA:

code = 0; // 0

break;

case 102: // ScanDataType.DSL_BCS_UPCE:

code = 1; // 1

break;


code = -1; // 4

// Max length is 30

break;

case 106: // ScanDataType.DSL_BCS_ITF: // Interleaved 2 of 5

code = 5; // 5

break;

case 107: // ScanDataType.DSL_BCS_CODABAR:

code = 6; // 6

break;


code = 8;

break;


code = 7;

break;

case 105: // ScanDataType.DSL_BCS_TF:

case 120: // case ScanDataType.DSL_BCS_EAN128:

default:

// Not supported

break;

}

if (code != -1) {

StringBuffer buf = new StringBuffer();

buf.append("PBC=");

buf.append(code);

buf.append(";");

buf.append(data);

buf.append(";");

buf.append(";");

buf.append(";");

buf.append(";");

out.setBuffer(buf);

out.setCommandArray(command);

}

return out;

}

}

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Note:

BAdI implementations may only throw exceptions that have been explicitly specified in the signature of the ex-

ecute method of the BAdI interface. Throwing exceptions other than the specified ones will result in an unde-

fined state of the application. If the BAdI interface does not specify an exception, a BAdI implementation must not throw an exception.

Note:

BAdI implementations must invoke the context.setOutput() method with the output from the implementa-

tion to make this output available to the relevant Enhancement Spots. Additionally, for IBAdIMulti BAdIs it may be appropriate to inspect the output of previous implementations (as shown in the IBAdILogOn examples).

Tip:

The context object provides the following setter and getter methods for a termination proposal:

public void setTerminationProposal(boolean terminationProposal)

public boolean getTerminationProposal()

If an Enhancement Spot allows multiple implementations of the BAdI interface, these implementations are ex-ecuted in sequence. An implementation may indicate that further processing is not necessary by setting a termi-nation proposal. Other implementations can check the termination proposal and optionally decide to either:

Accept the proposal and return without further processing of the request, or

Continue executing

7.4.5 Create a jar file with the BAdI Implementations

Once you have completed BAdI interface implementation(s) as described in the previous sections, you can pre-pare the implementation(s) for deployment.

BAdI implementations are provided bundled as JAR files, with all BAdI implementations provided in a single JAR file whenever possible. If you are providing multiple JAR files, ensure that each BAdI implementation occurs only once, that is, that the different JAR files are disjunctive.

To export the BAdI implementation in a JAR file:

1. In the Package Explorer, right-click on the Java project. 2. Optionally, add all required resources to the Java project. This is for BAdI implementations that need

additional resources (for example, style sheets or images). 3. Select Export Jar Next. 4. Complete the steps of the Wizard and click Finish.

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

7.4.6 Configure the Enhancement Spot

There is a one-to-one relationship between an Enhancement Spot and the corresponding BAdI interface. The

property file badi.properties is used to describe which BAdI implementation (or which BAdI implementa-

tions, in case of an Enhancement Spot that supports multiple implementations) to execute at runtime.

Caution:

A single badi.properties file must be used to configure all Enhancement Spots.

In the badi.properties file, the fully qualified class name of the BAdI interface is used as the property name

and represents the Enhancement Spot. The fully qualified class name of the implementing class of the BAdI in-terface represents the value.

Caution:

If an Enhancement Spot which supports a single BAdI implementation is configured with multiple implementa-tions, the EHC framework will throw an exception and no implementation will be executed.

In case of an Enhancement Spot which supports multiple implementations, the property value is a comma sepa-rated list of the fully qualified class names of the implementing classes. The sequence of the class names de-termines the sequence of the execution at runtime.

To configure the EHC Framework to execute the right implementations for a BAdI interface:

1. Using the text editor of your choice, create the badi.properties file.

2. Add an entry for each Enhancement Spot you want to configure.

For an Enhancement Spot that supports single BAdI implementations only, the format of the entry is:

BAdIInterfaceName = ImplClass1

For an Enhancement Spot that supports multiple BAdI implementations, the format of the entry is:

BAdIInterfaceName = ImplClass1, ImplClass2, …

3. Save the badi.properties file to the <TE_HOME>/custom/lib/badi directory.

Example:

Configuration for the POS Client Print Barcode Enhancement Spot.

com.sap.epos.badi.interfaces.deviceservices.IBAdIPackageBarcode=

com.saptest.epos.framework.deviceservices.jpos.

epsonFP90.packageBarcode.BarcodeSampleImpl

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

Caution:

In the above example, the POS Client Print Barcode Enhancement Spot is configured to execute the Barcode-

SampleImpl implementation of the IBAdIPackageBarcode interface. Note that the above configuration

must be provided in a single line in the property file.

7.5 Implementation of the Java BAdI for the Bitmap Printing

The second sample Java BAdI implementation provided is the POS Client Print Bitmap Enhancement Spot. This section describes how to implement the BAdI interface for Bitmap printing on the Epson FP90 printer model.

The POS Client Print Bitmap Enhancement Spot allows implementations to qualify a POS Client Print Bitmap request. The implementation builds the bitmap format base on the target fiscal printer. The Epson FP90 fiscal printer does not support bitmap printing, therefore no sample implementation is provided here. Further informa-tion can be found in the Javadoc of the corresponding BAdI interface.

The sample POS Client Print Bitmap Enhancement Spot BAdI interface is as follows: package com.sap.epos.badi.interfaces.deviceservices;

import com.sap.epos.badi.interfaces.IBAdI;


public interface IBAdIPackageBitmap extends IBAdI<IBAdIPackageBitmapInput,

IBAdIPackageBitmapOutput>{

/**

* Method execution provides functionality of the nhancement Spot.

*/

public void execute(IBAdIContext<IBAdIPackageBitmapInput, IBAdIPackageBitma-

pOutput> context);

public static final String BADI_DESCRIPTION = "Enhancement spot invoked when

attempting to print a bitmap on a Fiscal Printer.";

}

The interface for the input parameter is:


public interface IBAdIPackageBitmapInput {

/**

* File path to the bitmap.

* @return a filename

*/

public String getFilename();

/**

* The width of the barcode in printer dots, or -1 to print it ‘as is’.

* This value may be ignored by the implementation.

* @return the expected width of the bitmap, in dots, or -1.

*/

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

public int getWidth();

/**

* The positioning of the bitmap relative to the paper.

* 0 - left aligned

* 1 - centered

* 2 - right aligned

* The implementation may ignore this value.

* @return the expected alignment of the barcode.

*/

public int getAlignment();

}

The interface for the output parameter is: package com.sap.epos.badi.interfaces.deviceservices;

public interface IBAdIPackageBitmapOutput {

/**



*/

public int getCommand();

/**



*/

public int[] getCommandArray();

/**

* Get the packaged Object that could be sent to the printer via a

* directIO call to print a bitmap of the given data.

* @return a packaged Object suitable to send via a directIO call, or null if

* it can't print the bitmap.

*/

public Object getObject();

}

SAP®

© 2010 SAP AG


D-69190 Walldorf


Version: 1.0 Date: 11/24/2010

of 63

7.6 Distribution and Deployment

This guide describes the process of manually distributing and deploying the BAdI implementations.

The BAdI implementations and the corresponding configuration must be distributed to all servers and clients. EHC Framework must be configured to be able to execute the right implementations for a BAdI interface.

To manually distribute and deploy the BAdI implementations:

1. Stop the application.

2. Copy the JAR files with the BAdI implementations and the badi.properties file to the

<TE_HOME>/custom/lib/badi directory.

3. Restart the application.

fiscal print1

Documents

isr epos badi interfaces assembly

isr epos tef logging assembly

printnone visibility public

software component archive

status update listener

jar cp cp

status update listeners

fully qualified class