FiscalPrinter Class (POS for .NET v1.12 SDK Documentation)

2/27/2008

Defines the programmatic interface for a UPOS fiscal printer device.

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

Syntax

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

Remarks

The Fiscal Printer service object does not try to encapsulate the generic Windows graphics printer. Instead, for performance and ease of use considerations, the interfaces are defined to directly control a printer.

Because fiscal rules differ from country to country and from region to region, this interface tries to generalize the common requirements at the maximum extent specifications. This interface is based on the fiscal requirements of the following countries/regions. However, it may fit the needs of other countries/regions also.

  • 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 that prints transaction information. You must give a printed fiscal receipt to the customer. Contains either a knife to delete the paper between transactions, or a tear bar to manually delete the paper.

  • Slip that 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 help personnel.

Device Sharing

The Fiscal Printer is an exclusive-use device, as follows:

  • The application must claim the device before the application enables it.

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

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

General Requirements

Fiscal printers do not 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, and more. It is insufficient to send unformatted strings of text to the printer: each field must be kept separate in a receipt line item, therefore differentiating between descriptions, prices, and discounts. Moreover, different print commands must be defined for each different sale function, such as refund, item, or void.

Fiscal rules differ among countries or regions. 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/regions (Greece, Poland, Brazil, Hungary, and Turkey) tax registers also.

  • 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/regions, 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 be present on any particular fiscal printer.

There are three possible printer modes:

  • Fiscal. 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. 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.

  • Nonfiscal. 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 together with the application-requested output to indicate that this output is not of a fiscal nature. Such printed receipts are usually marked as "nonfiscal" receipts by fiscal printers. The CapNonFiscalMode property is set to true if the printer supports nonfiscal printing; otherwise it is false.

Model

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

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

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

Asynchronous printer methods do not return an error status because of a printing problem, such as out of paper or printer fault. These errors are only reported by an ErrorEvent event. 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 occur because of 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. 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. An OutputCompleteEvent is not raised for cleared output. ClearOutput also stops any output that may be in progress, when it is possible.

  • The FlagWhenIdle property can be set to cause the service object to raise a StatusUpdateEvent event 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 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/regions, 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 help 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 available 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.

ExtendedErrorBadLength

The length of the string to be printed after or before the line is too long.

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 because of 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 by 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 by using the PrintRecTotal, PrintRecNotPaid or PrintRecVoid methods.

  • FiscalReceiptEnding

    The printer has completed the receipt up to the Total line. In this state you may be able to print general messages by using the PrintRecMessage method if it is supported by the printer. This state is entered from the FiscalReceipt state through the PrintRecVoid method or from the FiscalReceiptTotal state by using the PrintRecTotal, PrintRecNotPaid or PrintRecVoid methods. The FiscalReceiptEnding state is exited by using the EndFiscalReceipt method, at which time that 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 by using the BeginFiscalDocument method. The FiscalDocument state is exited by using the EndFiscalDocument method, at which time that 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 by using the BeginTraining method. This state is exited by using the EndTraining method, at which time that 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 nonfiscal 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 that has all application text to indicate that this is nonfiscal output. This state is entered from the Monitor state by using the BeginNonFiscal method. This state is exited by using the EndNonFiscal method, at which time the printer returns to the Monitor state.

  • Fixed

    The printer is being used to print fixed, nonfiscal 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 by using the BeginFixedOutput method. The Fixed state is exited by using the EndFixedOutput method, at which time that 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 by using the BeginItemList method. The ItemList state is exited by using the EndItemList method, at which time that 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 by using one of the PrintReport, PrintPeriodicTotalsReport, PrintPowerLossReport, PrintXReport or PrintZReport methods. When the report print is complete, the printer automatically returns to Monitor state.

  • Locked

    The printer is no longer operational because of 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 you set 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

By using a fiscal printer’s slip station, it may be possible, depending on 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 by using the SlipSelection property but only one totalizer is assigned to all the fiscal documents.

  • Nonfiscal Full Length Documents

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

  • Nonfiscal 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 by using the SlipSelection property.

Ordering of Fiscal Receipt Print Requests

A fiscal receipt is started by using the BeginFiscalReceipt method. If the CapIndependentHeader property is true, the application must determine whether the fiscal receipt header lines are to be printed currently. Otherwise, header lines are printed immediately before the first line item inside a fiscal receipt. Printing the header lines currently reduces the time that is required to process the first fiscal receipt print method. However, it may result in more receipt voids also. 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 you can 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

  • PrintRecItemVoid

  • PrintRecItemAdjustmentVoid

The PrintRecItem, PrintRecItemAdjustment, PrintRecRefund, PrintRecSubtotal, PrintRecSubtotalAdjustment, PrintRecItemVoid and PrintRecItemAdjustmentVoid 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 the receipt total has been met. The PrintRecVoid method changes the printer’s state to FiscalReceiptEnding.

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

  • PrintRecNotPaid

  • PrintRecTotal

  • PrintRecVoid

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

Whereas 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 method 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 the information about the store, such as telephone number, address, and name of the store. All these lines are fixed and are defined before selling the first item by 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 the lines of a fiscal transaction, such as line items, discounts, and surcharges.

  • Total Line

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

  • Trailer Lines

    Fixed promotional messages stored on the printer by using the SetTrailerLine method. Trailer lines are automatically printed when the EndFiscalReceipt method is called. Notice 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 because of 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. Other applications allow addition of new table entries but not modification of existing entries. Some printers allow the VAT table to be set only one time.

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 2-step process. First, the application uses the SetVatValue method to set each table entry. Next, the SetVatTable method is called to send the VAT table to the printer.

Receipt Duplication

In some countries/regions, 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. Setting the DuplicateReceipt property 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 make sure that calculations in the application use the same fractional part for amounts.

  • If the CapHasVatTable property is true, VAT rates are passed by 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 discount amounts 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.

See Also

Reference

FiscalPrinter Members
Microsoft.PointOfService Namespace