Flow Reference

FLOW is used from the main engine to report what is happening inside. As the code moves through its execution it fires FLOW status reports. These can be trapped and handled by external functions for support purposes. Custom FLOW handlers can be used to capture additional error details for problem analysis, measure operation timing or as a debug PC like trace.

Flow points are used to define a place in the code where it is doing something. That are not concerned with how it is being done, only that it is being done. Flow points can be added and removed over time, but the definition of a numbered flow point remains for all time.

Flow point numbers should be considered random numbers. There is no pattern or sequence to them. Instructions for developers around flow can be seen in the examples on Fieldpine Coding Standards

Some flow numbers are designated as "error" flows. These are points that are not expected under normal operation. Errors come in a wide variety and some errors are only just classed as errors and are less fatal than others. Not all error flow numbers necessarily mean you have a system problem. A flow error is only for unexpected errors at a technical level, a flow error is not logged if the user generates errors in normal operation. For example, a user generating a "wrong password" is not a flow error, while a failure to open a file would be.

Logging Flow

You can define the setting FlowInitMask to cause Pos to write flow statements into the log file FlowLog.txt See the examples tab for details of how to capture flow in real time rather than logging.

• Bit 1 (2). Log all flow points
• Bit 2 (4). Log error class flow points

The records written to the FlowLog.txt file have the structure

TIME,TTT,NNN
TIME,TTT,NNN,E,RRR,Z

Where

• TIME is the local date/time when the flow event was logged
• TTT Is the thread id generating the flow
• NNN is the flow number
• E is the actual lettter 'E' and used to indicate an error class flow
• RRR is the system error code, typically taken from GetLastError() or WSAGetLastError().
• Z is a code indicating type of code for RRR. 0=Used GetLastError(), 1=Used WSAGetLastError(), 2=RRR is not valid

Support Flow

A support engineer can inspect the current flow on a system with the QeDebug test 25,001. This can be done interactively on a lane (if enabled/configured) with the following URL

http://IP-ADDRESS-AND-PORT/gnap/buck?3=fieldpineinternal.fdl911.fetch&100=25001

Capturing a Flow

Create your function to handle the event. These functions can be placed in the "functions.c" in the POS folder

:function name(Flow88)
	MessageBox(0, "The FLOW 88 has just happened", "Flow Alert", 0);

Register the handler. This is done by calling the PosRegisterFlowHandler() function. This can be done quite easily by adding the following line to fpos.ctl

force:Setup.CompanyName=My Test Store
... Other parts of fpos.ctl ..

; Register a flow handler for point 88
PosRegisterFlowHandler(88, 0, "Flow88", 0);

.. Fpos.ctl continues ..

Notes.

1. Do not use MessageBox() inside flow handlers or otherwise stop POS operation on production environments. This is used for an example only, but can be used on Test/Dev machines.
2. The names of the functions must match exactly. If you register a function name that does not exist, it will simply not be called. If your implementation of Flow88() does not compile, it will also simply not be called. Essetially the POS ignores all errors in setting up Flow handlers.

A more Complex Handler

The handler above is quite simple, the following indicates a handler that does a little bit more. This handler records how many times the handler has been called and alerts the user if it is too many times. Again, we use MessageBox() for the example but this is considered bad style for production environments

:function name(Flow88)
	struct aa {
		int Cnt;
		int Advised;
	};

	/* Get our memory block, create a new one if none exists */
	struct aa *paa = (struct aa*) PosGetGlobalMemory("Flow88Data", NULL);
	if (paa == NULL) {
		paa = (struct aa*) malloc(sizeof(struct aa));
		if (paa) {
			paa->Cnt = 0;
			paa->Advised = 0;
			PosSetGlobalMemory("Flow88Data", paa);
		}
	}

	if (paa) {
		paa->Cnt++;

		/* Has this happened at least 8 times since last telling user */
		if ((paa->Cnt - paa->Advised) >= 8) {
			char buffer[88];

			sprintf(buffer, "Flow 88 has fired %d times", paa->Cnt);
			paa->Advised = paa->Cnt;
			MessageBox(0, buffer, "Flow 88 message", 0);
		}
	}

Individual Flow Points may be looked up in the reference database. See Reference Data. ( or Example Record ) When using the lookup function, the information returned includes:

• FlowType. Indicates if this is a normal point or an abnormal point.
• FileName and LineNo. The source file name and line number that defines this Flow Point.
• RelevanceDev. A percentage relevance to developers. 0 indicates not relevant at all to developers, while 100% says developers should be informed of occurence.
• RelevanceSup. A percentage relevance to a customer inhouse support team
• RelevanceOps. A percentage relevance to a customer inhouse operations team
• Common. A rough estimate of how common this FlowPoint is across all customer sites
• Name. A simple common name for this point
• Comments. An comments added by the developer. This will invariably be technical for support staff.

The 3 relevance fields are estimates only. Some flow points refer to errors, and some errors are relevant to developers (eg logic faults), while others are more support (eg failing to print receipts), or customer operations teams (eg transaction declined as account on hold). A relevance of 0,0,0 indicates information not set. A relevance of 100,100,100 would indicate an impossible situation.

<DATS>
	<Value>601160429</Value>
	<FlowType>ErrorGle</FlowType>
	<FileName>PrintOutput.cpp</FileName>
	<LineNo>398</LineNo>
	<RelevanceDev>0</RelevanceDev>
	<RelevanceSup>100</RelevanceSup>
	<RelevanceOps>30</RelevanceOps>
	<Common>50</Common>
	<Name>OpenPrinterGraphics</Name>
	<Comments>Failed to open a printer with CreateDC()</Comments>
</DATS>

The above example shows a flow point that fires when a CreateDC() call fails to open a defined printer name. This example will generate an Event as well. (Events are generated for a subset of Flow Points).

We can see the relevance has been set to 0% for developers (the code is doing the right action), and to 100% for support teams as the POS is trying to use a bad printer, which likely indicates it has either been renamed or removed.

Flow Points are by definition unable to record additional "data". So this flow point does not include the printer name, which is included in the Event record.

Documented Points

The following flow points are defined and published. Other flow points exist in the system, general purpose handlers may be called with unknown flow numbers.

Source code shown in descriptions is similar to actual code, but may not be the exact code in use. The API being called is correct, but arguments and syntax may have been adjusted for readability

Sale Related

Creating a new Sale

Other

Device Related

Printing Related

if (0==pDC->CreateDC(winsp,prter,NULL,NULL)) {
	// We failed to initialise the printer
	long gle = GetLastError();
	FLOW_ERROR(601160429);

if (-1==pDC->StartDoc(&doci)) {
	long gle = GetLastError();
	FLOW_ERROR(602160429);

if (pDC->StartPage() <= 0) FLOW_ERROR(603160429);          // begin a new page

Cash Drawer Related

	if (! GetPrinter(phnd,5,(unsigned char*)&pu.prt5,pcnt,&bcnt)) FLOW_ERROR(733160509);

if (OpenPrinter(pDev,&phnd,NULL)==0) FLOW_ERROR(734160509);

HANDLE hCom = CreateFile(m_Port,....)
if (hCom == INVALID_HANDLE_VALUE) FLOW_ERROR(737160509);

Network Related

int cs = connect(s,  (SOCKADDR*)&trg, sizeof(SOCKADDR_IN));
if (cs != 0) FLOW_ERROR_SOCKET(217160508);

switch(select(0, NULL, &myset, NULL, &WaitTime)) {
case	SOCKET_ERROR:
	FLOW_ERROR_SOCKET(226160508);
}

	hSock = socket(AF_INET, SOCK_DGRAM, NULL);
	if (hSock == INVALID_SOCKET) FLOW_ERROR_SOCKET(1403160707);

Graphics and Windows

Other

if ( GetDiskFreeSpaceEx(NULL, ...) == 0) FLOW_ERROR(2038160430);