HardTotals Class (POS for .NET v1.12 SDK Documentation)
2/27/2008
Defines the programmatic interface for a UPOS hard totals device.
Namespace: Microsoft.PointOfService
Assembly: Microsoft.PointOfService (in microsoft.pointofservice.dll)
Syntax
'Declaration
Public MustInherit Class HardTotals
Inherits PosCommon
public abstract class HardTotals : PosCommon
public ref class HardTotals abstract : public PosCommon
public abstract class HardTotals extends PosCommon
public abstract class HardTotals extends PosCommon
Remarks
Capabilities
The hard totals device has the following minimal set of capabilities:
Supports at least one totals file that has the name "" (the empty string) in an area of totals memory. Each totals file is read and written as if it were a sequence of byte data.
Each totals file is created by using a fixed size and can be deleted, initialized, and claimed for exclusive use.
The hard totals device may have the following additional capabilities:
Supports additional named totals files. They share some characteristics of a file system with only a root directory level. In addition to the minimal capabilities listed earlier, each totals file may also be renamed.
Supports transactions, with begin and commit operations, plus rollback.
Supports advanced error detection. This detection may be implemented through hardware or software.
Model
Totals memory is frequently a limited but secure resource perhaps of only several thousand bytes of storage. The following is the general model of the hard totals:
A hard totals device is logically treated as a sequence of byte data that the application subdivides into "totals files." This is done by the service object Create method that assigns a name, size, and error detection level to the totals file. Totals files have a fixed-length that is set at Create time.
At a minimum, a single totals file that has the name "" (the empty string) can be created and manipulated. Optionally, additional totals files that have arbitrary names can be created.
Totals files model many of the characteristics of a traditional file system. However, the intent is not to provide a robust file system. Instead, totals files allow partitioning and ease of access into what is frequently a limited but secure resource. To reduce unnecessary overhead usage of this resource, directory hierarchies are not supported, file attributes are minimized, and files may not be dynamically resized.
The following operations can be performed on a totals file:
Read: Read a series of data bytes.
Write: Write a series of data bytes.
SetAll: Set all the data in a totals file to a value.
Find: Locate an existing totals file by name, and return a file handle and size.
FindByIndex: Used to enumerate all the files in the hard totals area.
Delete: Delete a totals file by name.
Rename: Rename an existing totals file.
ClaimFile: Gain exclusive access to a specific file for use by the claiming application. A timeout value may be specified in case another application maintains access for a period a time.The common Claim method can also be used to claim the hard totals device.
ReleaseFile: Releases exclusive access to the file.
The FreeData property holds the current number of unassigned data bytes.
The TotalsSize property holds the totals memory size.
The NumberOfFiles property holds the number of totals files that exist in the hard totals device.
Transaction operations are optionally supported. A transaction is defined as a series of data writes to be applied as an atomic operation to one or more hard totals files.
During a transaction, data writes are typically maintained in memory until a commit or rollback. Also, FreeData is typically reduced during a transaction to make sure that the commit has temporary totals space to perform the commit as an atomic operation.
BeginTrans: Marks the beginning of a transaction.
CommitTrans: Ends the current transaction, and saves the updated data. Software and hardware methods are used to make sure that either the transaction is saved, or that no updates are applied.
This typically requires writing the transaction to temporary totals space, setting state information within the device that indicates that a commit is in progress, writing the data to the totals files, and freeing the temporary totals space. If the commit is interrupted, perhaps because of a system power loss or reset, then when the hard totals service object is reloaded and initialized, it can complete the commit by copying data from the temporary space into the totals files. This guarantees the integrity of related totals data.
Rollback: Ends the current transaction, and discards the updates. This may be useful if there is user intervention to cancel an update. Also, if advanced error detection shows that some totals data cannot be read suitably in preparation for an update, then the transaction may have to be aborted.
TransactionInProgress: This property holds the current state of transactions.
The application should claim the files that are used during a transaction so that no other hard totals Control claims a file before CommitTrans. This causes the commit to fail, returning an already claimed status.
Advanced error detection is optionally supported by the following:
A Read or a Write can report a validation error. Data is usually divided into validation blocks, over which sumchecks or CRCs are maintained. The size of validation data blocks is determined by the specific service object.
A validation error informs the application that one or more of the validation blocks that contains the data to be read or written may be invalid because of a hardware error. (An error on a Write can occur when only a part of a validation block must be changed. The validation block must be read and the block validated before the portion is changed.)
When a validation error is reported, we recommend that the application read all the data in the totals file. The application must determine which sections of data is invalid, and take action based on the results of the reads.
RecalculateValidationData can be called to cause recalculation of all validation data within a totals file. This may be called after recovery has been performed as in the previous paragraph.
ValidateData can be called to verify that all data within a totals file passes validation.
Data writes automatically cause recalculation of validation data for the validation block or blocks in which the written data resides.
Because advanced error detection usually imposes a performance penalty, the application can select this feature when each totals file is created.
Device Sharing
The hard totals device is shareable. Its device-sharing rules are as follows:
After opening the device, most properties are readable.
After opening and enabling the device, the application can access all properties and methods.
If more than one application has opened and enabled the device, all applications can access its properties and methods.
One application can claim the hard totals device. This restricts all other applications from reading, changing, or claiming any files on the device.
One application can claim a hard totals file. This restricts all other applications from reading, changing, or claiming the file, and from claiming the hard totals device.
Inheritance Hierarchy
System.Object
Microsoft.PointOfService.PosDevice
Microsoft.PointOfService.PosCommon
Microsoft.PointOfService.HardTotals
Microsoft.PointOfService.BasicServiceObjects.HardTotalsBasic
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.