PosCommands - Common

Sale() PosCommand

The sale() command has a large collection of functions to affect sales. Sales to the POS can be true customer sales and also used as a collection of items for other purposes such as store to store transfer. The main selling screen is optimised towards capturing items so using it to capture items for writeoff as well is extremely easy for staff to learn and understand.

The POS is capable of having multiple active sales open at once, typically shown as tabs on the screen. These commands only affect the visible sale and designers do not need to worry about the multiple active sales.

Commnd Overview

sale(line,...)

Change individual items on a sale. These commands are documented seperately at PoscSaleline.htm

sale(paycmd,...) sale(pay....)

Commands to affect the payment part of a sale. A sale broadly consists of salelines (items being purchased or returned) and payments

sale(print....)

sale(mustprint)

Marks if this sale should or should not print a receipt. Normally the POS makes this decision itself but in some circumstances you may wish to override the default behaviour. For example, when selling a specific product, the product itself may issue the sale(mustprint) command in order to force a receipt output.

sale(mustprint=0) Internally mark that this sale should not print a receipt. A receipt may still print, depending on other subsequent actions, and other options, such as EFT, performed on the sale

sale(mustprint) or sale(mustprint=1) Internally mark that this sale should print a receipt.

Printing a receipt and opening a cash drawer are unconnected operations in Fieldpine. If you wish to control the cash drawer on a sale basis, use the commands sale(opendrawer) and sale(drawer...) commands.

sale(sellzero), sale(hidden), sale(return), sale(opendrawer), sale(setmode...)

Set sale specific flags to control operation.

sale(sellzero) By default, the POS will not complete sales where the total of products purchased equals zero, but this can occur when some types of transactions occur, such as direct swap of a product. This commands allows this single sale to complete even if the total value is zero. Requiring this flag to be set for $0 sales helps ensure system consistency and avoid common operator mistakes.

sale(hidden) Hide this sale from view and do not populate user salelist displays with this sale. This command is typically used for internal sales that are created temporarily to avoid updating screens or confusing the operator

sale(return) Change this sale from a normal sale to a return sale, where quantities are inverted and products are expected to be returned to stock. This command form is used when free form product returns from customers are allowed.

sale(opendrawer) Open the cash drawer for this sale now. If enabled, the drawer opened is recorded on the sale at this time. This command need not be called directly as the POS will automatically issue this command if not manually executed.

sale(finish?), sale(quit?)

sale(quit?) causes the system to silently delete a single open sale if the following conditions are met:

The number of items on the sale is zero
The number of payments (including failed payment attempts) is zero.

This command can be useful where all sales must be closed before proceeding within the menu system.

sale(finish?) Used internally to check if sales can be completed at this time. Not designed for external use and should not be used in UI files.

sale(layby), sale(appro)

sale(delsel), sale(delseq), sale(delseqignoresecurity)

sale(sel-1), sale(sel-9999), sale(sel-last), sale(sel+), sale(sel-)

sale(alterline), sale(alterqty...)

sale(setcustomer...)

sale(drawer,N)

Sets the cash drawer to open for this sale, if the system has multiple cash drawers configured. Cash drawers number from 1 upwards. If N is -1, then the POS resets to the default cash drawer.

The default cash drawer can vary depending on current logged in teller and site configuration. Multiple cash drawer support may also require specific printer models or cash drawer models

sale(drawer,-1) Set this sale to use the default cash drawer, the default which allows teller specific drawer selection

sale(drawer,1) Set this sale to specifically use cash drawer #1

sale(park)

sale(setbarcode...), sale(setkeystr...), sale(setting...)

sale(store...)

sale(line....)

Send POS Commands to the individual salelines. This allows you to address individual items.

sale(fulladd...), sale(add...)

sale(transfer...), sale(goods_in...), sale(stocktake....), sale(writeoff), sale(dispatch), sale(setstocklevel)

Commands that use the sale as a "collection of products" and complete the sale in different ways.

sale(removealldiscount...)

Removes all item based discounts from a sale. Often used if switching customer mid sale

sale(demographic(...))

sale(split())

Split the sale into multiple parts. Typically used in hospitatility to split a table bill into individual sales

sale(manufacture())

sale(printformat())

sale(priceband())

sale(setting())

sale(dispatch())

sale(state())

sale(restrict())

sale(lock())

sale(flags())

sale(condition())

sale(tax())

sale(custdue())

sale(comments())

sale(receipt())

sale(set-name())

sale(transit())

sale(offer())

sale(svc())

sale(kitchen())

sale(country(CMD))

Indicate that this sale will be delivered in a different country. This can cause additional screens to appear and tax processing to be altered depending on regulatory setup.

The value of CMD can be a country identification number (eg 61 for Australia), in which case the value is simply recorded. If CMD is the keyword "prompt", an interactive screen is displayed to allow country specific entry and tax handling control.

More information: Delivery Details Prompt Screen and screen(standard(28))

sale(loadpref())

sale(setpref())

sale(payment())

sale(prompt(AREA))

(July 2014, P1831) Displays an interactive screen to allow the operator to enter additional information. Some of these prompt screens may require customisation in order to work in a specific site environment

Area	Description
Notes	Display current sale notes and allow entry of a new note
Demographic
Delivery	Capture sale wide delivery details. This screen is primarily intended for capturing address in the same country as the store. If you are entering export orders, the preferred command is sale(country(prompt)).
Total	Not available for general use
Staff	Allow manual entry of staff involved in a sale. Typically used where individual sale commissions may be split between multiple staff.

sale(addnote(NNN))

(July 2014, P1831) Stores the string NNN as a new note on the sale. Sale notes are stored as a list of comments and not removed once added. A common use might be updating the progress of a sale that involves work or service actions. To enter notes interactively, use the command sale(prompt(notes)). Sale notes are designed for internal use only at this time.

sale(exception(NNN))

(July 2014, P1831) Allows override of default information for exceptional purposes. This is rarely used.

If the command is sale(exception(date)), the user is prompted for a date and the sale start and end date/times are set to this time. This applies only for an active sale. Typically this command might be used to enter sales for dates that have already been, such as ensuring a sale is added to a statement billing cycle. Any payments applied to this sale are not affected by the entered date and continue to be reported on current days End of day.

In (Aug 2017, P2010) changes were made to the command sale(exception(date))

A staff member requires the security right "Sale Power User" to issue this command
The entered date must not be older in days than the setting SaleExceptionMinDate (default 90). If this setting is 0 (zero), minimum dates are not checked
The entered date must not be in the future by more than setting SaleExceptionMaxDate (default 45). If this setting is 0 (zero), future dates are not checked

Retired Commnds

The following sale() commands have been retired

sale(undo)

This command used to allow users to "undo" the action just undertaken, much like you undo typing actions when using a word processor. As commands become more and more complex it was not always easy to simply undo something.

Selling a product, might involve prompting for serial numbers, activating vouchers or many other actions. These might not always be "undo able" by simply reversing the operation. In this example the users can delete the product themselves, which causes the delete routines to activate. In some cases though, the "delete" operation is not the same as a simple "undo", or may itself cause secondary actions.

In order to avoid inconsistencies, this command was retired. A side effect is that customisations become easier to comprehend

Payments

sale(pay,type(cash) amount(5.00))

Adds a $5 payment of type cash to the current sale.

sale(pay,type(global(564000)) amount(5.00))

Searchs for the local definition of global payment type 564000 and applies a $5 payment of that type. Global codes are defined by Fieldpine and permit the indentification of specific payment types across multiple retailers. Global codes are often used where payment types are defined and controlled over multiple sites, such as a shared loyalty system.

sale(paycmd,allocate(pline,sline,amount))

(13 July 2014. P1812) Allocates the payment "pline" to the saleline "sline" for "amount". If payment #1 is to be allocated to Saleline #2 for $50, then the command sale(paycmd,allocate(1,2,50)) will store this fact. The values pline and sline are the sequence numbers of the payment/saleline not the ordinal position.

sale(paycmd,delsel))

Deletes the last payment from the sale.

sale(paycmd,set,field,name,value))

Stores "value" into the field "name". You should not store values to fields that are defined by Fieldpine, this command is for site specific customised fields only. This command performs no action if the sale is locked against changes.

sale(payment(surcharge))

Causes the system to calculate any payment surcharge that might be applicable and add a surcharge line to the sale for this amount. Payment surcharges arise when extra fees are added because a certain method of payment is being selected by the customer. Most common is a surcharge might be levied for credit card payments, causing the customer to pay some/all of the Merchant Service Fee (MSF).

sale(receipt(OPTIONS))

Add extra information to the receipt to be printed. This can be images, text or QR codes.

OPTIONS consists of

position(N)

Specifies the position this receipt extension should appear on the printed receipt. Possible values for N are first or last, indicating the extreme top and bottom of receipts respectively. If receipt pre printing is enabled, then the first keyword will appear after the pre printed portion, not the extreme top of the receipt.

text(N)

Sets the text to display. Depending on the type parameter, this value may indicate file paths or other relevant information

type(N)

Sets the type of infomation being passed. Possible values are text or image. type(text) is the default and causes the text() paramter to be treated as a literal to place on the receipt.

image(N)

Specifies an image to place on a receipt, where the filename is given by parameter N.

control(N)

Allows a range of extended features, or flags, to be set for this extension

overlay(N)

When image printing is being used by specifying type(image), this option can be used to place text on top of the image. A typical usage may be printing a background ticket graphic and then overlaying the session and admission details.

qr(N)

Creates a QR code from the string N and prints this on the receipt. The string N is processed via symbol replacement at the time this command is issued.

queue(Name)

Causes the receipt extension to print on a seperate printer queue as a individually queued print job. This parameter specifies the name of the printer queue to use. When this parameter is used the position() parameter is ignored.

media()

Provides a hint as to the type of paper in a printer queue. Need only be supplied when queue() is used. The values are:

Value	Description
printed	Indicates that the physical media is pre printed forms, which are a single page long. The system will print as requested and then issue a Form-Feed command to move to the top of the next page.
A4	Indicates A4 paper is loaded

Examples:

Adding a simple image sale(receipt(image(MyImage.bmp)))

Adding a QR code pointing to a website and including the sale reference. This might be used if you are running competitions or customer surveys. sale(receipt(qr(HTTP://EXAMPLE.COM/BUY_AND_WIN.HTM?ID=%SALEID%)))

External Examples: