Event Handler Reference

The following table shows all available events in the system. There are different types of events

Passive events are where your event handler is advised of something but cannot control it (ie Logging operation)
Active events allow you respond to the event and control or affect outcome. Some events you can accept, deny or abstain the action about to be undertaken. Other events allow you to respond with specific information.
Junction events allow you to replace the operation about to be performed with your own code.

These types of events can be generated and handled in different ways.

Events that can be handled by PosScript. These can be passive or active.
Events that can be handled by the mini "C" interface. These can be passive, active or Junction events.
Events that can be handled by the Talk-To-Fieldpine (TTF) interface. These can be passive, active or Junction events.
Events that are logged to remote systems using TUEV protocol. Logged events are for auditing and support.
No in the table below means an event is deliberately not available or is technically difficult

There are a large number of events covering both business level and highly technical aspects of the system. The "Use" column in the table attempts to show where the event is primarily consumed.

Common - Frequently used to implement customer specific controls and logic
Normal - Used to implement customer specific controls and logic but less frequently used across sites.
Rare - Used to implement customer specific controls and logic but rarely used. Needing to use these events might be an indication you are taking a slightly wrong approach, but there are valid needs for these events.
Tech - More technical aspects of the system, less focused on business logic
Internal - Deep internals, often quite removed from the actual operation. These events are typically more interesting to automated support and debug tools.
Fieldpine - Fieldpine only use. Used for events that are unstable, new or otherwise not safe for customers.

Event#	Name	Use	PosScript	"C"	TTF	Logged	Type	Description
16000	PriceAllSale	Rare	No	P1918			Active	Called near the end of POS pricing to allow you to override the pricing on the whole sale
16001	SalelinePreAdd	Common	No	P1918			Active	An item is about to be added to the sale and you can stop this. This event cannot be handled by PosScript, there is an alternative event for PosScript users 2010, SalelineAddPre
16002	PastSalesDisplay	Rare	No	P1921			Active	A sale is about to be drawn on the PastSales screen. This event can block the sale from being displayed
16003	PosVersionChange	Rare	No	P1923			Passive	Called if the Pos detects the underlying code version has changed
16100	ServerLoadedSale	Rare	No	P1918			Passive	Called when a server system is about to store a sale from a trading lane
16300	HttpSocketAccept	Tech	No	P1918			Active	Called after a TCP connection has been accepted. You can abort the connection.
16400	DatabaseOpenQuery	Internal	No	P1918			Passive	Called immediately before an SQL query is sent to the underlying database engine.
10003	ActiveSaleChange	Normal	P623	P1918			Passive	Sent when the active sale the user is seeing on screen changes
100	SaleCreated	Normal	Yes					Not yet fully documented. PS_SALE_NEW
1000	PS_BARCODE_UNKNOWN_DEFINE	Normal	Yes					Not yet fully documented
1001	PS_BARCODE_UNKNOWN_NODEFINE	Normal	Yes					Not yet fully documented
1002	PS_BARCODE_UNKNOWN_CUST	Normal	Yes					Not yet fully documented
1007	PS_SALE_PARK_REQUEST	Normal	Yes					Not yet fully documented
1008	Writeoff request	Normal	Yes					Not yet fully documented
1009	Quit Request	Normal	Yes					Not yet fully documented
1010	Trash Request	Normal	Yes					Not yet fully documented
1011	Saledone Pre	Normal	Yes					Not yet fully documented
1012	Return Request	Normal	Yes					Not yet fully documented
1013	Purge Pre	Normal	Yes					Not yet fully documented
1014	Purge Post	Normal	Yes					Not yet fully documented
1015	Cancel	Common	Yes					Not yet fully documented
1016	Reverse Request	Normal	Yes					Not yet fully documented
1017	Reverse Done	Normal	Yes					Not yet fully documented
1018	Sale Completed	Normal	Yes					Not yet fully documented
1019	Cancel Request	Normal	Yes					Not yet fully documented
1020	Sale TestMode	Normal	Yes					Not yet fully documented
1022	Trash Done	Normal	Yes					Not yet fully documented
1023	Sale Pre Complete	Normal	Yes					Not yet fully documented
1024	Pre Sale Pre Complete	Normal	Yes					Not yet fully documented
1025	Sale payments allowed	Normal	Yes					Not yet fully documented
1100	Reward reached	Normal	Yes					Not yet fully documented
1400	Split Start	Normal	Yes					Not yet fully documented
2000	Http new request	Normal	Yes					Not yet fully documented
10001	Product dispatch	Normal	Yes					Not yet fully documented
2001	SalelineAdd	Common	Yes	No			Actiuve	Item has been added to the sale. The event handler is able to capture and update any additional fields.
2002	Saleline add cash	Normal	Yes					Not yet fully documented
2003	Saleline discount add	Normal	Yes					Not yet fully documented
2004	Saleline discount deleted	Normal	Yes					Not yet fully documented
2005	Saleline price change	Normal	Yes					Not yet fully documented
2006	Saleline quantity change	Normal	Yes					Not yet fully documented
2009	Saleline deleted	Normal	Yes					Not yet fully documented
2010	SalelineAddPre	Common	Yes	No			Active	This event cannot be handled by PosScript, there is an alternative event for PosScript users 16001, SalelinePreAdd
2011	saleline alter total	Normal	Yes					Not yet fully documented
2014	saleline price prompt	Normal	Yes					Not yet fully documented
2015	Return adjustment	Normal	Yes					Not yet fully documented
2016	Return Complete	Normal	Yes					Not yet fully documented
2017	Hire Return	Normal	Yes					Not yet fully documented
2018	Hire unreturn	Normal	Yes					Not yet fully documented
2019	Auto Writeoff	Normal	Yes					Not yet fully documented
2104	Saleline request delete discount	Normal	Yes					Not yet fully documented
3000	Payment add	Normal	Yes					Not yet fully documented
3001	Payment deleted	Normal	Yes					Not yet fully documented
3002	Payment filter	Normal	Yes					Not yet fully documented
3003	Ext Prompt	Normal	Yes					Not yet fully documented
3500	Float log	Normal	Yes					Not yet fully documented
4000	Teller change	Normal	Yes					Not yet fully documented
4002	Teller password failure	Normal	Yes					Not yet fully documented
4003	Teller change request	Normal	Yes					Not yet fully documented
4004	Teller max failure	Normal	Yes					Not yet fully documented
4005	Teller timeout	Normal	Yes					Not yet fully documented
4006	Teller Meta change	Normal	Yes					Not yet fully documented
4500	Cash in	Normal	Yes					Not yet fully documented
4600	Cash out	Normal	Yes					Not yet fully documented
4700	Language change	Normal	Yes					Not yet fully documented
4800	Rightclick menu request	Normal	Yes					Not yet fully documented
5000	Customer set	Normal	Yes					Not yet fully documented
5001	Customer sale history	Normal	Yes					Not yet fully documented
5002	Account detail	Normal	Yes					Not yet fully documented
5003	Account Bill	Normal	Yes					Not yet fully documented
5004	Customer set request	Normal	Yes					Not yet fully documented
5005	Customer set failure	Normal	Yes					Not yet fully documented
5006	Floor limit exceeded	Normal	Yes					Not yet fully documented
5100	Reward advise	Normal	Yes					Not yet fully documented
5200	Purchase new header	Normal	Yes					Not yet fully documented
5201	Purchase new line	Normal	Yes					Not yet fully documented
5202	Purchase order approved	Normal	Yes					Not yet fully documented
5203	Get new Order#	Normal	Yes					Not yet fully documented
10001	Location Change	Normal	Yes					Not yet fully documented
10002	Screen Request	Normal	Yes				Active	The User Interface is about to display a new screen.
10004	User Input	Normal	Yes					Not yet fully documented
10005	Send Email	Normal	Yes					Not yet fully documented
10006	Popup Regno	Normal	Yes					Not yet fully documented
10007	Serial item scanned	Normal	Yes					Not yet fully documented
12000	Cash drawer opening	Normal	Yes					Not yet fully documented
12001	Cash drawer abnormal open	Normal	Yes					Not yet fully documented
12010	Eftpos failure	Normal	Yes					Not yet fully documented
13000	Settle Close	Normal	Yes					Not yet fully documented
13002	Settle Close Parked	Normal	Yes					Not yet fully documented
13003	Settle Printing	Normal	Yes					Not yet fully documented
13004	Settle Close Blind	Normal	Yes					Not yet fully documented
13005	Settle Close Done	Normal	Yes					Not yet fully documented
13006	Shift Close	Normal	Yes					Not yet fully documented
13007	Shift Open	Normal	Yes					Not yet fully documented
14000	Debug Request	Normal	Yes					Not yet fully documented
14001	Config Request	Normal	Yes					Not yet fully documented
14002	Designer publish	Normal	Yes					Not yet fully documented
18997	Maint command	Normal	Yes					Not yet fully documented
18998	Drawer Motion	Normal	Yes					Not yet fully documented
18999	Printer Status Change	Normal	Yes					Not yet fully documented
19000	Stock Level	Normal	No					Not yet fully documented
19001	Hard total	Normal	No					Not yet fully documented
19002	SysError	Normal	No					Not yet fully documented
19003	Pole Display	Normal	No					Not yet fully documented
19004	MessageBox	Normal	No					Not yet fully documented
19005	Store Chat	Normal	No					Not yet fully documented
19006	FIS Change	Normal	No					Not yet fully documented
19007	Makeline Change	Normal	No					Not yet fully documented
19008	Eftpos done	Normal	No					Not yet fully documented
19009	Runtime Error	Normal	No					Not yet fully documented
19010	Sale loaded	Normal	No					Not yet fully documented
19011	TimeCheck	Normal	No					Not yet fully documented
19012	Screen Close	Normal	No					Not yet fully documented
19013	Saleline Post Event	Normal	No					Not yet fully documented
19600	Spy Status	Tech	No					Not yet fully documented
19601	Keypress	Tech	No					Not yet fully documented
19602	barcode scan	Tech	No					Not yet fully documented
19603	printer action	Tech	No					Not yet fully documented
19604	cash drawer	Tech	No					Not yet fully documented
19605	Fuel transaction	Tech	No					Not yet fully documented
19606	Windows	Tech	No					Not yet fully documented
19607	Mouse	Tech	No					Not yet fully documented
19608	Trace	Tech	No					Not yet fully documented
201	System Startup		No			Yes	Passive
202	Version Change		No			Yes	Passive
203	Quickcode Executed		No			Yes	Passive
204	Runtime Error		No			Yes	Passive
205	TimeChanged		No			Yes	Passive
208	BIS End		No			Yes	Passive
216	MsgBox		No			Yes	Passive
217	Sale Complete		No			Yes	Passive
218	Crash Detected		No			Yes	Passive
219	Lots of Files		No			Yes	Passive
220	Major System Issue		No			Yes	Passive
221	Hardware Change		No			Yes	Passive
222	Auto Recovery		No			Yes	Passive
241	Screen Open		No			Yes	Passive
242	Barcode Scanned		No			Yes	Passive
243	Screenshot		No			Yes	Passive
244	Large Change		No			Yes	Passive
245	Manual Discount		No			Yes	Passive
246	Account Balance Change		No			Yes	Passive
247	Online Sale Arrived		No			Yes	Passive
248	Eftpos Failure		No			Yes	Passive
249	Lookup Products		No			Yes	Passive
250	Device Performance		No			Yes	Passive
251	Database Performance		No			Yes	Passive
252	Cash Drawer Open All		No			Yes	Passive
253	Cash Drawer Open Abnormal		No			Yes	Passive
254	System Screen Opening		No			Yes	Passive
255	Bad barcode scan		No			Yes	Passive
256	Login Fail		No			Yes	Passive
257	Database slow		No			Yes	Passive
258	Speedtest		No			Yes	Passive
259	Environment Change		No			Yes	Passive
260	Pos State		No			Yes	Passive
281	Purchase Order Change		No			Yes	Passive
282	Sale Change		No			Yes	Passive
283	Product Change		No			Yes	Passive
284	Supplier Change		No			Yes	Passive
285	Customer Change		No			Yes	Passive
286	Sale Delete Item		No			Yes	Passive
287	Settle Completed		No			Yes	Passive	Fired after the end of day settlement screen is completed.
288	Startup Performance		No			Yes	Passive

#2010, SalelineAddPre

Called just before an item is about to be added to a sale. This event allows you to stop this item being added to the sale. Use "exit 0" to stop the item being added.

Input Arguments:

Symbol Name	Contents
%CTX.product.*%	The product record being added. Any of the product attributes can be fetched. Common values fetched are CTX.product.piditem, CTX.product.plucode
%sale.*%	Details of the current sale
%salecustomer.*%	Details of the current customer. These symbols may return 0/empty if no customer is currently selected
*	All other general symbols are also available

Example PosScript Handler

:event(number(2010) index(0))
	set customer = %salecustomer.cid%
	set plu = %CTX.product.plucode%

	if customer = 17
	then
		if plu = "BEER"
		then
			message(99,1,This customer is not allowed to purchase %CTX.product.description%)
			exit 0
		endif
	endif

	exit

#2001, SalelineAdd

Called after an item has been added to a sale. The saleline is ready for you to capture and store any additional information.

The symbol CTX.product. is not valid during this event. you can access the same information using the PosScript variable "saleline(-1,nnnn)"

Input Arguments:

Symbol Name	Contents

Example PosScript Handler

:event(number(2001) index(0))
	set prodcode = saleline(-1,plucode)
	
	
	//  ************** Part 1 - Save the PLU code ************
	// Would not normally do this, it is for this example only

	sale(line,set,field,u_Saved_Plu,%prodcode%)

	
	//  ************** Part 2 - Update site specific saleline fields ************
	
	// If this product is taxable we have to add VAT to the custom field u_Unit_Avg_Cost
	// We need to check the setting u_FlatTax1_? to determine if the item is taxable
	// as products are stored in groups
	set lncatid = posc(storage(query(field(u_Account_Category) psql(?products,plucode,=,%prodcode%))))
	set a = string((u_FlatTax1_%lncatid%))
	set b = string(settings) + a
	set taxable = symbol(%b%)
	if taxable = Yes
	then
		// Get the line average cost from the products table
		set lnavgcst = posc(storage(query(field(CostPriceAverage) psql(?products,plucode,=,%prodcode%))))
		// Calculate tax
		set vat = tax(2,lnavgcst)
		// Add the tax to the average cost
		set lnavgcst = lnavgcst + vat
		// Round the total
		set lnavgcst = function(lnavgcst,financialround)
		// Store the new value including the VAT
		sale(line,set,field,u_Unit_Avg_Cost,%lnavgcst%)
	endif



	//  ************** Part 3 - Prompt user for product specific information ************

	// Do we have specific prompt screen
	set prodpidcode = saleline(-1,pid)
	if prodpidcode = 0:13427
	then
		screen(4xml(6050_ScriptXml.scr,EnterPricePid13427))
	endif

#16300, HttpSocketAccept

When a network request connects, this event is fired immediately after the accept() call. You may drop the connection by returning a Deny Response. The POS continues to perform normal restriction checking after this call; so even if you ALLOW a connection it may still be dropped.

Input Arguments:

Field#	Name	Contents
450	FIELDPINE_EVNT_SOCKADDR	The SOCKADDR structure that was filled in by the accept() call

Calling Pseudo Code

  SOCKET s = accept(..., SockAddr);
  if (s != INVALID_SOCKET) {
	... Call event handlers, passing SockAddr ...
	... If any handler returns DENY, close socket and exit ...
  }

Example Mini "C" Handler

:event(number(16300) index(0) lang(C))
	// Deny connections from 192.201.*.*

	SOCKADDR_IN sock;
	memset(&sock, 0, sizeof(sock));

	PosContext_GetFieldToBuffer(pContext, FIELDPINE_EVNT_SOCKADDR, &sock, sizeof(sock));
	if (sock.sin_addr.S_un.S_un_b.s_b1 == 192) {
		if (sock.sin_addr.S_un.S_un_b.s_b2 == 201) {
			return FIELDPINE_REEV_DENY;
		}
	}
	return FIELDPINE_REEV_NO_RESPONSE;
:end

#16400, DatabaseOpenQuery

The system is about to send a new SQL query to the database engine. Primarily this is used for support purposes.

Input Arguments:

Field#	Name	Contents
480	FIELDPINE_EVNT_SQL	The SQL about to be sent to the database engine. This SQL might still be altered to conform to underlying engine syntax and performance requirements

Example Mini "C" Handler

:event(number(16400) index(0) lang(C))
	#include <stdio.h>
	#include <share.h>

	FILE* pf = _fsopen("SqlLog.out", "a", _SH_DENYNO);
	if (pf) {
		char* pValue = NULL;
		int ValueLen = 0;
		PosContext_GetFieldPtr(pContext, FIELDPINE_EVNT_SQL, &pValue, &ValueLen);
		if ((pValue != NULL) && (ValueLen > 0)) {
			fprintf(pf, "Sql=%*s\n", ValueLen, pValue);
		}
		fclose(pf);
	}
	return FIELDPINE_REEV_NO_RESPONSE;
:end

#10002, Screen Request

The User interface is about to display a new screen. This event fires to allow you to block or override this operation. You can allow the operation (default action), block the screen or set a replacement screen to be used.

Input Arguments:

Field#	Name	Contents
300	FIELDPINE_EVNT_CONTEXT1	The name of the screen being requested

Example Mini "C" Handler

:event(number(10002) index(0) lang(C))
	#include <stdio.h>
	#include <share.h>
	#include <string.h>

	// Get the name of the screen being invoked
	int ValueLen = 0;
	char* pValue = PosContext_GetFieldPtr(pContext, FIELDPINE_EVNT_CONTEXT1, &ValueLen);

	// Log this to an audit file
	FILE* pf = _fsopen("ScreensLog.out", "a", _SH_DENYNO);
	if (pf) {
		if ((pValue != NULL) && (ValueLen > 0)) {
			time_t ltime;
			time( &ltime );

			char buff[70];
			strftime(buff, sizeof(buff), "%d-%b-%Y %H:%M:%S", localtime(&ltime));
			fprintf(pf, "%s Screen=%*s\n", buff, ValueLen, pValue);
		}
		fclose(pf);
	}

	// Or, Block the Menu screen completely
	if ((ValueLen == 4) && (strnicmp(pValue, "menu", 4) == 0)) {
		return FIELDPINE_REEV_DENY;
	}


	// Or, If they are requesting the screen "hidden", change to "secret"
	if ((ValueLen == 6) && (strnicmp(pValue, "hidden", 6) == 0)) {
		PosContext_SetData(pContext, "workingcommand.newscreen", "secret");
		return FIELDPINE_REEV_ALLOW;
	}

	return FIELDPINE_REEV_NO_RESPONSE;
:end

#10003, Active Sale Change

The active sale on screen has changed and the user is working with a different sale. This can be as simple as the user is clicking on tabs to select multiple sales or is starting a new sale.

Input Arguments:

Field#	Name	Contents
421	FIELDPINE_EVNT_ORIGINAL_SID	The SaleId (specific to this machine) now being displayed

Example Mini "C" Handler

:event(number(10003) index(0) lang(C))
	long DisplaySid = PosContext(pContext, FIELDPINE_EVNT_ORIGINAL_SID);
	// The current SID on screen is now  DisplaySid.
	// If DisplaySid is zero, no sale is currently displaying
	// ....  Do whatever ....

	return FIELDPINE_REEV_NO_RESPONSE;
:end

#16002, PastSales Display Request

The Past sales screen has selected a sale to be displayed. This event fires to allow you to block or override this operation.

Input Arguments:

Field#	Name	Contents
421	FIELDPINE_EVNT_ORIGINAL_SID	The local sale number for the sale
310	FIELDPINE_EVNT_COUNTER_1	The number of sales that have alreay been added to the display
311	FIELDPINE_EVNT_CALLER_ID	unique number that is the same for every call from this run, but will differ the next time the screen is displayed

Example Mini "C" Handler

:event(number(16002) index(0) lang(C))

	// Get the Sid 
	long Sid = PosContext_GetField(pContext, FIELDPINE_EVNT_ORIGINAL_SID);

	// If it is just this sale#, do not allow it
	if (Sid == 8382200) return FIELDPINE_REEV_DENY;

	return FIELDPINE_REEV_NO_RESPONSE;
:end

Example of Blocking a Customer

:event(number(16002) index(0) lang(C))

	// Get the Sid 
	long Sid = PosContext_GetField(pContext, FIELDPINE_EVNT_ORIGINAL_SID);

	// Ask for the Cid number from this sale
	// Note, this API is not available at time of writing, but will be shortly
	long Cid = PosDatabase_GetLong_clc(pContext, "Sale[#1]", Sid, ".cid");

	// If it is just this Cid#, do not allow it
	if (Cid == 83) return FIELDPINE_REEV_DENY;

	return FIELDPINE_REEV_NO_RESPONSE;
:end