Share via


FiscalPrinter Class

Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)

Usage

'Usage
Dim fiscalPrinter1 As New FiscalPrinter()

Syntax

'Declaration
MustInherit Public Class FiscalPrinter
    Inherits PosCommon
public abstract class FiscalPrinter : PosCommon
public abstract ref class FiscalPrinter : public PosCommon
public abstract class FiscalPrinter extends PosCommon
public abstract class FiscalPrinter extends PosCommon

Remarks

The fiscal printer service object does not attempt to encapsulate the generic Windows graphics printer. Rather, for performance and ease of use considerations, the interfaces are defined to directly control a printer.

Because fiscal rules differ from country to country, this interface tries to generalize the common requirements at the maximum extent specifications. This interface is based upon the fiscal requirements of the following countries, but it may fit the needs of other countries as well.

  • Brazil

  • Bulgaria

  • Europe (Euro)

  • Greece

  • Hungary

  • Italy

  • Poland

  • Romania

  • Russia

  • Turkey

The printer model defines three stations with the following general uses:

  • Journal, which logs transaction information, and must be kept by the store for audit.

  • Receipt, which prints transaction information. It is mandatory to give a printed fiscal receipt to the customer. Contains either a knife to cut the paper between transactions, or a tear bar to manually cut the paper.

  • Slip, which prints information on a form, and is usually given to the customer.

    Slip is also used to print “validation” information on a form, typically a check or credit card slip.

Configuration and initialization of the fiscal memory of the printer are not covered in this SDK. These low level operations must be performed by technical assistance personnel.

Device Sharing

The fiscal printer is an exclusive-use device, as follows:

  • The application must claim the device before enabling it.

  • The application must claim and enable the device before accessing many printer-specific properties.

  • The application must claim and enable the device before calling methods that manipulate the device.

General Requirements

Fiscal printers do not simply print text as standard printers do, they are used to monitor and memorize all fiscal information about a sale transaction. A fiscal printer has to accumulate totals, discounts, number of canceled receipts, taxes, etc. It is not sufficient to send unformatted strings of text to the printer: each individual field must be kept separate in a receipt line item, thus differentiating between descriptions, prices, and discounts. Moreover, it is necessary to define different print commands for each different sale function (such as refund, item, or void).

Fiscal rules differ among countries. This interface tries to generalize these requirements by summarizing the common requirements. Fiscal law requires that:

  • Fiscal receipts must be printed and given to the customer.

  • Fiscal printers must be equipped with memory to store daily totals. Each receipt line item must increment totals registers and, in most countries (Greece, Poland, Brazil, Hungary and Turkey) tax registers as well.

  • Discounts, canceled items, and canceled receipts must increment their associated registers on the printer.

  • Fiscal printers must include a clock to store date and time information for each receipt.

  • Each fiscal receipt line item is printed both on the receipt and on the journal. (Italy, Greece, Poland)

  • After a power failure (or a turn-off) the fiscal printer must be in the same state as it was before this event occurred. This implies that care must be taken in managing the fiscal printer status and that power failure events must be managed by the application. In some countries a power failure must be logged and a report must be printed.

Printer Modes

According to fiscal rules, it is possible for a fiscal printer to also offer functionality beyond the required fiscal printing mode. These additional modes are optional and may or may not be present on any particular fiscal printer.

There are three possible printer modes:

  • Fiscal, which is the only required mode for a fiscal printer. In this mode, the application has access to all the methods needed to manage a sale transaction and to print a fiscal receipt. It is assumed that any lines printed to the receipt station while in fiscal mode are also printed on the journal station.

  • Training, which is used for training purposes (such as cashier training). In this mode, the printer accepts fiscal commands but indicates on each receipt or document that the transaction is not an actual fiscal transaction. The printer does not update any of its internal fiscal registers while in training mode. Printed receipts are usually marked as “training” receipts by fiscal printers while in this mode.The CapTrainingMode property is set to TRUE if the printer supports training mode; otherwise it is FALSE.

  • Non-Fiscal, which can be used to print simple text on the receipt station (echoed on the journal station) or the slip station. Additional lines are usually printed along with the application-requested output to indicate that this output is not of a fiscal nature. Such printed receipts are usually marked as “non-fiscal” receipts by fiscal printers. The CapNonFiscalMode property is set to TRUE if the printer supports non-fiscal printing; otherwise it is FALSE.

Model

The fiscal printer follows the general output model, with some enhancements:

Most methods are always performed synchronously. Synchronous methods will fail if asynchronous output is outstanding.

The following methods are performed either synchronously or asynchronously, depending on the value of the AsyncMode property:

  • PrintFiscalDocumentLine

  • PrintFixedOutput

  • PrintNormal

  • PrintRecItem

  • PrintRecItemAdjustment

  • PrintRecMessage

  • PrintRecNotPaid

  • PrintRecRefund

  • PrintRecSubtotal

  • PrintRecSubtotalAdjustment

  • PrintRecTotal

  • PrintRecVoid

  • PrintRecVoidItem

    When AsyncMode is FALSE, these methods print synchronously and return their completion status to the application.

    When AsyncMode is TRUE, these methods operate as follows:

    • The service object buffers the request, sets the OutputId property to an identifier for this request, and returns as soon as possible. When the device completes the request successfully, the service object fires an OutputCompleteEvent. A parameter of this event contains the OutputId of the completed request.

    • Asynchronous printer methods do not return an error status due to a printing problem, such as out of paper or printer fault. These errors are only reported by an ErrorEvent. An error status is returned only if the printer is not claimed and enabled, a parameter is invalid, or the request cannot be queued. The first two error cases are due to an application error, while the last is a serious system resource exception.

    • If an error occurs while performing an asynchronous request, an ErrorEvent is queued and delivered. The ErrorStation property is set to the station or stations that were printing when the error occurred. The ErrorLevel, ErrorString and ErrorState and ErrorOutID properties are also set.

    • The event handler can call synchronous print methods (but not asynchronous methods), then either retry the outstanding output or clear it.

    • The service object guarantees that asynchronous output is performed on a first-in first-out basis.

    • All output buffered by OPOS can be deleted by calling the ClearOutput method. OutputCompleteEvents will not be fired for cleared output. ClearOutput also stops any output that may be in progress (when possible).

    • The FlagWhenIdle property can be set to cause the service object to fire a StatusUpdateEvent when all outstanding outputs have finished, whether successfully or because they were cleared.

SET ErrorModel "ErrorModel" \* MERGEFORMAT ErrorModelThe fiscal printer error reporting model is as follows:

  • Most of the fiscal printer error conditions are reported by setting the DeviceErrorEventArgs.ErrorCode to Extended and then setting ErrorCodeExtended to one of the following error conditions:

Value

Description

ExtendedErrorCoverOpen

The printer cover is open.

ExtendedErrorJournalEmpty

The journal station is out of paper.

ExtendedErrorReceiptEmpty

The receipt station is out of paper.

ExtendedErrorSlipEmpty

The slip station is out of paper.

ExtendedErrorMissingDevices

A device required by local fiscal legislation is not connected. In some countries, a set of peripheral devices (such as cash drawer and customer display) must be connected to the POS to use a fiscal printer. If any of these devices is not present, sales are not allowed.

ExtendedErrorWrongState

The requested method could not be executed in the printer’s current state.

ExtendedErrorTechnicalAssistance

The printer has encountered a severe error condition. Calling for printer technical assistance is required.

ExtendedErrorClockError

The printer’s internal clock has failed.

ExtendedErrorMemoryFull

The printer’s fiscal memory has been exhausted.

ExtendedErrorMemoryDisconnected

The printer’s fiscal memory has been disconnected.

ExtendedErrorTotalsError

The Grand Total in working memory does not match the one in the EPROM.

ExtendedErrorBadItemQuantity

The quantity parameter is invalid.

ExtendedErrorBadItemAmount

The amount parameter is invalid.

ExtendedErrorBadItemDescription

The description parameter is too long, contains illegal characters, or contains a reserved word.

ExtendedErrorReceiptTotalOverflow

The receipt total has overflowed.

ExtendedErrorBadVat

The VAT parameter is invalid.

ExtendedErrorBadPrice

The price parameter is invalid.

ExtendedErrorBadDate

The date parameter is invalid.

ExtendedErrorNegativeTotal

The printer’s computed total or subtotal is less than zero.

ExtendedErrorWordNotAllowed

The description contains a reserved word.

  • Other printer errors are reported by setting the ErrorCode to Failure or another standard error status. These failures are typically due to a printer fault or jam, or to a more serious error.

SET PrinterStates \* MERGEFORMAT Printer StatesSET PrinterStates "here" \* MERGEFORMAT hereSET PrinterStates \* MERGEFORMAT

As previously described, a fiscal printer is characterized by different printing modes. The set of commands that can be executed at a particular moment depends on the current state of the printer.

The current state of the fiscal printer is kept in the PrinterState property.

The fiscal printer has the following states:

  • Monitor

    This is a neutral state. From this state you can move to most of the other printer states. After a successful call to the ClaimDevice method and successfully setting the DeviceEnabled property to TRUE, the printer should be in Monitor state unless there is a printer error.

  • FiscalReceipt

    The printer is processing a fiscal receipt. All PrintRec… methods are available for use while in this state. The FiscalReceipt state is entered from the Monitor state using the BeginFiscalReceipt method.

  • FiscalReceiptTotal

    The printer has already accepted at least one payment method, but the receipt’s total amount has not yet been tendered. This state is entered from the FiscalReceipt state by use of the PrintRecTotal method. The printer remains in this state while the total remains unpaid. The FiscalReceiptTotal state is exited using the PrintRecTotal, PrintRecNotPaid or PrintRecVoid methods.

  • FiscalReceiptEnding

    The printer has completed the receipt up to the Total line. In this state it may be possible to print general messages using the PrintRecMessage method if it is supported by the printer. This state is entered from the FiscalReceipt state via the PrintRecVoid method or from the FiscalReceiptTotal state using either the PrintRecTotal, PrintRecNotPaid or PrintRecVoid methods. The FiscalReceiptEnding state is exited using the EndFiscalReceipt method, at which time the printer returns to the Monitor state.

  • FiscalDocument

    The printer is processing a fiscal document. The printer accepts the PrintFiscalDocumentLine method while in this state. This state is entered from the Monitor state using the BeginFiscalDocument method. The FiscalDocument state is exited using the EndFiscalDocument method, at which time the printer returns to the Monitor state.

  • Monitor and TrainingModeActive = TRUE

    The printer is being used for training purposes. All fiscal receipt and document commands are available. This state is entered from the Monitor state using the BeginTraining method. This state is exited using the EndTraining method, at which time the printer returns to the Monitor state.

  • FiscalReceipt and TrainingModeActive = TRUE

    The printer is being used for training purposes and a receipt is opened. Special text is added to each line of the receipt to differentiate it from a fiscal receipt.

  • FiscalTotal and TrainingModeActive = TRUE

    The printer is in training mode and receipt total is being handled.

  • FiscalReceiptEnding and TrainingModeActive = TRUE

    The printer is being used for training and is in the receipt-ending phase.

  • NonFiscal

    The printer is printing non-fiscal output on either the receipt (echoed on the journal) or the slip. In this state the printer accepts the PrintNormal method. The printer prints a message with all application text to indicate that this is non-fiscal output. This state is entered from the Monitor state using the BeginNonFiscal method. This state is exited using the EndNonFiscal method, at which time the printer returns to the Monitor state.

  • Fixed

    The printer is being used to print fixed, non-fiscal output to one of the printer’s stations. In this state the printer accepts the PrintFixedOutput method. This state is entered from the Monitor state using the BeginFixedOutput method. The Fixed state is exited using the EndFixedOutput method, at which time the printer returns to the Monitor state.

  • ItemList

    The printer is printing a line item report. In this state the printer accepts the VerifyItem method. This state is entered from the Monitor state using the BeginItemList method. The ItemList state is exited using the EndItemList method, at which time the printer returns to the Monitor state.

  • Report

    The printer is printing one of the supported types of reports. This state is entered from the Monitor state using one of the PrintReport, PrintPeriodicTotalsReport, PrintPowerLossReport, PrintXReport or PrintZReport methods. When the report print completes, the printer automatically returns to Monitor state.

  • Locked

    The printer is no longer operational due to one of the following reasons:

    • The printer has been disconnected or has lost power.

    • The printer’s fiscal memory has been exhausted.

    • The printer’s internal data has become inconsistent.

    In the Locked state, the printer accepts only methods that print reports and retrieve data. The printer cannot exit this state without the assistance of an authorized technician.

When the application sets the property DeviceEnabled to TRUE, it also monitors its state. In a standard situation, the PrinterState property is set to Monitor after successfully setting DeviceEnabled to TRUE. This indicates there was no interrupted operation remaining in the printer.

If the printer is not in the Monitor state, the state reflects the printer's interrupted operation and the PowerState property is set to Off. This means that a power failure occurred or the last application to access the device left it in an uncleared state. In this situation, the ResetPrinter method must be called to force the printer to a normal state.

Notice that even in this case, the DeviceErrorEventArgs.ErrorCode property is set to Success after setting DeviceEnabled to TRUE. It is required that the application check the PowerState property and check for a received StatusUpdateEvent with the value Off in the data argument after successfully setting the DeviceEnabled property.

Document Printing

Using a fiscal printer’s slip station, it may be possible (depending upon the printer’s capabilities and on special fiscal rules) to print the following kinds of documents:

  • Fiscal Documents

    To print fiscal documents, an amount value must be sent to and recorded by the printer. The CapSlpFiscalDocument property is set to TRUE if the printer supports printing fiscal documents, and FALSE otherwise. If fiscal documents are supported, they may be either full length (if CapSlpFullSlip is TRUE) or validation (if CapSlpValidation is TRUE). The actual selection is made using the SlipSelection property but only one totalizer is assigned to all the fiscal documents.

  • Non-Fiscal Full Length Documents

    Full length slip documents can be printed if CapSlpFullSlip is TRUE and SlipSelection is set to FullLength.

  • Non-Fiscal Validation Documents

    Validation documents can be printed if CapSlpValidation is TRUE and SlipSelection is set to Validation.

  • Fixed Text Documents

    Fixed text documents can be printed if CapFixedOutput is TRUE. If fixed text documents are supported, they may be either full length (if CapSlpFullSlip is TRUE) or validation (if CapSlpValidation is TRUE). The actual selection is made using the SlipSelection property.

Ordering of Fiscal Receipt Print Requests

A fiscal receipt is started using the BeginFiscalReceipt method. If the CapIndependentHeader property is TRUE, the application must decide if the fiscal receipt header lines are to be printed at this time. Otherwise, header lines are printed immediately before the first line item inside a fiscal receipt. Printing the header lines at this time decreases the amount of time required to process the first fiscal receipt print method, but it may result in more receipt voids as well. The BeginFiscalReceipt method can be called only when the printer is in the Monitor state and will change the printer’s state to FiscalReceipt.

Before selling the first line item it is possible to exit from the fiscal receipt state by calling the EndFiscalReceipt method. If header lines have already been printed, EndFiscalReceipt also cause receipt voiding.

When the first line item has been printed and the printer is in the FiscalReceipt state, the following fiscal print methods are available:

  • PrintRecItem

  • PrintRecItemAdjustment

  • PrintRecNotPaid

  • PrintRecRefund

  • PrintRecSubtotal

  • PrintRecSubtotalAdjustment

  • PrintRecTotal

  • PrintRecVoid

  • PrintRecVoidItem

The PrintRecItem, PrintRecItemAdjustment, PrintRecRefund, PrintRecSubtotal, PrintRecSubtotalAdjustment and PrintRecVoidItem methods leave the printer in the FiscalReceipt state. The PrintRecNotPaid (available only when the CapReceiptNotPaid property is TRUE) and PrintRecTotal methods change the printer’s state to either FiscalReceiptTotal or FiscalReceiptEnding, depending on whether or not the entire receipt total has been met. The PrintRecVoid method changes the printer’s state to FiscalReceiptEnding.

While in the FiscalReceiptTotal state, the following fiscal print methods are available:

  • PrintRecNotPaid

  • PrintRecTotal

  • PrintRecVoid

The PrintRecNotPaid (available only if the CapReceiptNotPaid property is TRUE) and PrintRecTotal methods either leave the printer in the FiscalReceiptTotal state or change the printer’s state to FiscalReceiptEnding, depending on whether or not the entire receipt total has been met. The PrintRecVoid method changes the printer’s state to FiscalReceiptEnding.

While in the FiscalReceiptEnding state, the following fiscal methods are available:

  • PrintRecMessage

  • EndFiscalReceipt

The PrintRecMessage method, available only if the CapAdditionalLines property is TRUE, leaves the printer in the FiscalReceiptEnding state. The EndFiscalReceipt causes receipt closing and then changes the printer’s state to Monitor.

Be aware that at no time can the printer’s total for the receipt be negative. If this occurs, the printer generates an error.

Receipt Layouts

The following is an example of a typical receipt layout:

  • Header Lines

    All of the information about the store, such as telephone number, address, and name of the store. All of these lines are fixed and are defined before selling the first item (using the SetHeaderLine method). These lines can be printed either when the BeginFiscalReceipt method is called or when the first fiscal receipt method is called.

  • Transaction Lines

    All of the lines of a fiscal transaction, such as line items, discounts, and surcharges.

  • Total Line

    The line containing the transaction total, tender amounts, and possibly change due.

  • Trailer Lines

    Fixed promotional messages stored on the printer (using the SetTrailerLine method). Trailer lines are automatically printed when the EndFiscalReceipt method is called. Note that the fiscal logotype, date and time and serial number lines are not considered part of the trailer lines. In fact, depending on fiscal legislation and on the printer vendor, the positions of the trailer and the fiscal logotype lines can vary. Information that must be inserted in the receipt due to fiscal legislation is automatically printed at receipt closure.

VAT Tables

Some fiscal printers support storing VAT (Value Added Tax) tables in the printer’s memory. Some of these printers allow the application to set and modify table entries. Others allow addition of new table entries but not modification of existing entries. Some printers allow the VAT table to be set only once.

If the printer supports VAT tables, the CapHasVatTable property is set to TRUE. If the printer allows the VAT table entries to be set or modified, the CapSetVatTable property is set to TRUE. The maximum number of VAT rate entries in the VAT table is specified by the NumVatRates property. VAT tables are set through a two-step process. First, the application uses the SetVatValue method to set each table entry. Next, the SetVatTable method is called to send the entire VAT table to the printer.

Receipt Duplication

In some countries fiscal legislation allows printing more than one copy of a receipt. The CapDuplicateReceipt property is set to TRUE if the printer can print duplicate receipts. Then, setting the DuplicateReceipt to TRUE causes the buffering of all receipt printing commands. DuplicateReceipt property is set to FALSE after receipt closing. To print the receipt again, call the PrintDuplicateReceipt method.

CURRENCY amounts, percentage amounts, VAT rates, and quantity amounts

  • CURRENCY amounts and prices are passed as values with the data type CURRENCY. On a Win32-based platform this is a 64-bit signed long value that implicitly assumes four digits as the fractional part. So, the range supported is from

    -922,337,203,685,477.5808

    to

    +922,337,203,685,477.5807

    The fractional part used in the calculation unit of a fiscal printer may differ from the CURRENCY data type. The number of digits in the fractional part is stored in the AmountDecimalPlaces property and determined by the fiscal printer. The application has to take care that calculations in the application use the same fractional part for amounts.

  • If the CapHasVatTable property is TRUE, VAT rates are passed using the indexes that were sent to the SetVatValue method. If the CapHasVatTable property is FALSE, VAT rates are passed as amounts with the data type LONG. The number of digits in the fractional part is implicitly assumed to be four.

  • Percentage amounts are used in methods that also allow surcharge and/or discount amounts. If the amounts are specified to be a percentage value, the value is also passed in a parameter of type CURRENCY. On a Win32-based platform the percentage value has then (as given by the CURRENCY data type) four digits in the fractional part. It is the percentage ( 0.0001% to 99.9999% ) multiplied by 10000.

  • Quantity amounts are passed as values with the data type LONG. The number of digits in the fractional part is stored in the QuantityDecimalPlaces property and determined by the fiscal printer.

Inheritance Hierarchy

System.Object
   Microsoft.PointOfService.PosDevice
     Microsoft.PointOfService.PosCommon
      Microsoft.PointOfService.FiscalPrinter
         Microsoft.PointOfService.BasicServiceObjects.FiscalPrinterBasic

Thread Safety

Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.

Platforms

Development Platforms

Windows XP Home Edition, Windows XP Professional, Windows Server 2003, Windows Longhorn, and Windows 2000

Target Platforms

See Also

Reference

FiscalPrinter Members
Microsoft.PointOfService Namespace