POSXML

POSXML (acronym for Point Of Sale eXtended Markup Language) is a programming language, based on XML, that is used to create applications for a POS terminal.

Normally the programming language used to develop such applications is C or C++. The main purpose of POSXML is to simplify the development of applications for POS terminals. It contains a set of instructions and pre-programmed commands, which allow direct interaction with the machine, resulting in a large reduction in application development time.

Language features

The structure of POSXML

POSXML is organized and structured in the form of tags, showing levels and subsets of a set of commands and instructions, that form the logical structure of a POSXML application.

Example:

<!-- Variables declaration -->
<stringvariable value="" variable="sTicketInfo"/>
<stringvariable value="" variable="sCityInfo"/>
<integervariable value="0" variable="iQtdTickets"/>
<integervariable value="0" variable="iInvalidInfo"/>
		
<!-- Function Display MAIN Menu -->
<function name="fMainMenu">
    <integervariable value="0" variable="iOption"/>
			
    <!-- Main Menu -->
    <menu options="MAIN MENU:\\1.SALE OF TICKETS\2.REPORT\3.EXIT" variable="$(iOption)"/>
			
    <!-- 1.SALE OF TICKETS -->
    <if operator="equalto" value="1" variable="$(iOption)">
       ...
    </if>
    ...			
</function>

Compiled language

Similar to the vast majority of existing programming languages, POSXML is compiled in a specific format to reduce the file size which allows the application to be run on a POS terminal using a framework (virtual machine).

When compiled, a program written in POSXML, becomes a set of bytecodes that are interpreted by the virtual machine on the POS terminal which results in the implementation on the POS terminal.

Example:

<display line="0" column="0" message="Example of Bytecode" />

Compiled bytecode:

d0 \x0A 0 \x0A Bytecode example \x0A \x0D

Syntax

The commands and instructions of POSXML, such as the compliance on the use of capital letters and lowercase letters (case sensitive), are acquired through training. Some commands that belong to the language do not require parameters, unlike other commands that need input to interact with the machine.

Examples:

Commands that do not require instructions or parameters.

<network.hostdisconect/>
<cleandisplay />
<waitkey />

Commands that require instructions and parameters to interact with the equipment.

<display line="1" column="1" message="POSXML" />
<menu variable="$(var1)" options="MENU\1. first line\2. second line\3. third line"/>
<wait miliseconds="1000" />

The names given to functions, variables, and pages should also obey the rules written in capital letters and lowercase letters, so if a developer creates a function called "calcula_digito" he will not be able to call on the variable via "Calcula_Digito". The call of a function, or variable page must meet the exact name that was assigned by the programmer.

Commands and instructions

Because it is a structured language based on XML, POSXML is a language that is constantly evolving, new commands and instructions can be added to your library at any time. Initially, the language had only two dozen basic commands to create a functional application on a POS terminal, using few resources: only the basic display (LCD), keypad, magnetic card reader and printer.

With the evolution of language, there are now almost one hundred commands and instructions available to deal with files, pictures, mathematical operators, functions to manipulate variables of the String type, definition of variables, logical operators, classes for working with protocol ISO 8583 (Protocol standard for exchanging information in transactions with credit cards), among others.

Command list

if

Instruction of decision making or logical comparison

else

Logical condition in a block of the if statement

while

Instruction that allows the execution of a code multiple times

break

The break command allows immediate exit from while loop

function

Defines a block of code that can be executed later

callfunction

Makes a call on a previously defined function

execute

Execute a POSXML application stored on the device

exit

Immediately closes the execution of the POSXML application

get card variable

Gets the card number and stores it directly on a variable

system.readcard

Waits until a card is passed or a key is pressed

system.inputtransaction

Instruction to receive the data card on a contactless transaction

menu

Displays a menu based on the device screen (number of lines)

menuwithheader

Displays a header with a menu based on the device screen (number of lines)

displaybitmap

Displays a monochromatic bitmap on the display

display

Displays a custom message on device's display

cleandisplay

Clean the device display (like a clear or cls)

system.gettouchscreen

Captures the coordinates (x and y) where the display was pressed

print

Prints a custom message in the default font size

printbig

Prints a custom message in the double font size

printbitmap

Prints a monochromatic bitmap

printbarcode

Prints a bar code in the I25 format, horizontal or vertical

checkpaperout

Checks if the paper compartment still contains paper

paperfeed

Sends a signal to the printer by adding blank lines on the ticket

inputfloat

Allows the entry of a value with dot (.) by pressing (*)

inputformat

Allows the entry of a value based on a pre-defined format

inputinteger

Allows the entry of an integer

inputoption

Stores in a variable the option of a menu item

inputmoney

Allows the entry of a monetary value

crypto.crc

16-bit CRC calculation, support CRC-CCITT

crypto.encryptdecrypt

Encryption routines with algorithms DES, 3DES or NEWDES

crypto.lrc

Generates a LRC byte of the string in the buffer

crypto.xor

Performs a binary XOR operation between the bytes of two strings

downloadfile

Downloads a file previously registered on the WALK Manager

filesystem.filesize

Returns the size of a file in the memory of the POS

filesystem.listfiles

Lists the files of a directory by saving them in a file

filesystem.space

Checks the space (free and used) and the number of files in memory

file.open

Opens a file for reading or writing

file.close

Closes a file that was previously opened by file.open

file.read

Reads a file that was previously opened by file.open

file.write

Writes a file that was previously opened by file.open

readfile

Reads a dbfile WALK file (key/value)

readfilebyindex

Reads a key from a file WALK dbfile

editfile

Allows write a file in WALK dbfile format (key/value)

deletefile

Deletes a file from the device memory

iso8583.initfieldtable

Starts field table ISO8583 based on a specified file

iso8583.initmessage

Initiates assembly of the ISO message

iso8583.putfield

Inserts a field in the message, necessarily in ascending order

iso8583.endmessage

Ends assembly of the ISO message

iso8583.transactmessage

Adds size, header and trailer and sends the ISO message to the authorizer

iso8583.analyzemessage

Starts the process of analysis and decomposition of the fields of the message

iso8583.getfield

Extracts a field of the previously analyzed message

openserialport

Opens the serial port for communication with external peripherals

writeserialport

Writes a buffer on the serial port

readserialport

Reads a buffer from an external device captured by the serial port

closeserialport

Closes the serial port

getdatetime

Stores in a variable date and time at runtime

time.calculate

Calculates time. Supports addition, subtraction and difference

adjustdatetime

Updates the device internal clock

predial

Performs a dial-up connection with the provider

preconnect

Connects to the host authorizer

shutdownmodem

Turns off the modem and cancels the operations

network.checkgprssignal

Checks the status of the connection, if the POS supports GPRS

network.hostdisconnect

Disconnects the device from the host, keeping it connected to the network

network.ping

Checks the status of the connection with the host

network.send

Sends a buffer to the host previously connected

network.receive

Receives from the host buffer previously connected

pinpad.open

Enables communication with the external or internal pinpad

pinpad.loadipek

Records an initial key and an initial ksn on the memory of pinpad

pinpad.getkey

Captures a key that is pressed on the external pinpad

pinpad.getpindukpt

Catches a PIN and encrypts it using DUKPT standard

pinpad.display

Displays a custom message on the display of the pinpad

pinpad.close

Terminates communication with the external or internal pinpad

emv.open

Initializes EMV library

emv.loadtables

Load tables EMV and PKI of the file for the buyer

emv.cleanstructures

Clears all input and output parameters

emv.adddata

Adds parameters to EMV process

emv.getinfo

Returns information parameters after the execution of the EMV process

emv.inittransaction

Initializes the EMV process with inserted parameters

emv.processtransaction

Starts the execution of the EMV process

emv.finishtransaction

Terminates the execution of the EMV process

emv.removecard

Waits for card removal

emv.settimeout

Define timeout (in seconds) of the library of the EMV process

system.readcard

Waits until a card is passed or a key is pressed

system.inputtransaction

Instruction to receive the data card on a contactless transaction

integervariable

Creates an instance of the variable of integer type

stringvariable

Creates an instance of the variable of string type

integerconvert

Conversion from integer to binary, octal or hexadecimal

convert.toint

Converts binary, decimal or hexadecimal to integer

inttostring

Conversion from integer to string

stringtoint

Conversion from string to integer

integeroperator

Increases by 1 (+1) or decrements by 1 (-1) a variable of integer type

string.tohex

Converts a string to its hexadecimal representation

string.fromhex

Converts a hexadecimal representation to a string

string.charat

Extracts specified string character

string.elementat

Returns a specific element in the string

string.elements

Returns how many elements there are in the specified string

string.find

Searches for a substring in the specified string

string.getvaluebykey

Searches in the string for a value based on key/value

string.trim

Eliminates the blanks on the left and right of the string

string.insertat

Inserts an element at specific index in string

string.length

Returns length of the specified string

string.pad

Adds a padding with specific character in string

string.removeat

Removes an element from specific index in string

string.replace

Replace all occurrences of the specified substring

string.replaceat

Replaces an element at a specific index in string

string.substring

Capture a specific part of string

substring

Copies part of a variable string to another variable

joinstring

Concatenates in a string the value of another 2 strings

input.getvalue

Captures a string and displays it on the screen in any position

smartcard.insertedcard

Checks if the card is inserted in the smart card reader

smartcard.closereader

Terminates communication process of with the smart card

smartcard.startreader

Starts the smart card reader and try to start the card

smartcard.transmitapdu

Sends an APDU command to the smart card

mathematicaloperation

Performs a mathematical operation between two values

system.beep

Produces a short beep

system.checkbattery

Checks the device battery status

system.backlight

Allows to control the backlight level of the terminal

system.info

Gets device information (MAC Address, SIM ID, etc

system.restart

Restarts the device

unzipfile

Unpacks a zip file

waitkey

Pauses execution until a button is pressed

waitkeytimeout

Same as command waitkey but has a timeout

readkey

Same as command waitkey, but holds the pressed key

wait

Pauses execution for a set time

Tens of commands and instructions complete the set of language.

Variables and data types

Variables in POSXML are typed; there are only two types, integer and string. POSXML limits the number of declared variables to 512.

These variables are declared global, i.e. They are shared throughout all the scheduled pages of the POSXML program in runtime process.

Examples:

String type variable:

<!-- Declaring a string type variable containing: "http://en.wikipedia.org/wiki/posxml" -->
<stringvariable value="http://en.wikipedia.org/wiki/posxml" variable="url" />

<!-- Accessing the content of the declared variable -->
<display line="0" column="0" message="$(url)" />

Integer type variable:

<!-- Declaring an integer type variable containing: "0" -->
<integervariable value="0" variable="iValue" />

<inputmoney column="0" line="0" message="Enter the amount:" variable="$(iValue)" />

A call to a variable that is declared in the memory, is made by $(name_of_the_variable), regardless of its type.

It is also possible to covert a variable of one type into the other type. In POSXML the commands inttostring and stringtoint are used for this.

Examples:

<integervariable value="1" variable="iOpcao_Tipo_Inteiro" />
<stringvariable value=""  variable="sOpcao_Tipo_String" />

<inttostring integervariable="$(iOpcao_Tipo_Inteiro)" stringvariable="$(sOpcao_Tipo_String)" />

File system

When writing an application for a POS terminal, the developer is faced with the need to write to the specific file system of the equipment. The POSXML language works with files of type WALK dbFile (A file system defined by the framework that interprets a program compiled POSXML). This file system WALK dbFile uses the format: key = buffer \ n key = buffer \ n, basically the format of text files in a Unix environment, where \ n is used to wrap. There are 8 basic commands in the POSXML language to work with files in the POS terminal, they are.

* editfile
* readfile
* readfilebyindex
* deletefile
* file.open
* file.write
* file.read
* file.close

Examples:

<editfile filename="test.txt" key="$(sChave)" value="$(sValor)" />
 
<readfile filename="test.txt" key="$(sChave)" variabledestination="$(sRetorno)" />

<readfilebyindex filename="test.db" index="0" variablekey="$(var1)" variablevalue="$(var2)" variablereturn="$(var3)" />
 
<deletefile filename="test.txt" />

Code examples

The traditional "Hello World"

<!-- An example application that shows the phgrase "Hello World" on the display. -->

<!--  The command "display" shows a message in a row and column specific. -->
<display line="3" column="0" message="Hello World" />
<!--  The command "waitkey" waits till the operator press someone key for continue the execution. -->
<waitkey />

<stringvariable value="" variable="stringName" />
<stringvariable value="" variable="stringValue" />
<integervariable value="0" variable="integerValue" />
<integervariable value="0" variable="integerOption" />
  
<!--  The command menu is used to show a menu in the terminal's display. The captured value is put in variable.  -->
<menu variable="$(integerOption)" options="\Menu\ 1) Main Function\ 2) Print Function" />

<if variable="$(integerOption)" operator="equalto" value="1" >
   <!--  The command callfunction is used to call a function defined with the function instruction.  -->
   <callfunction name="Main" />
</if>
  
<if variable="$(integerOption)" operator="equalto" value="2" >
   <!--  The command callfunction is used to call a function defined with the function instruction.  -->
   <callfunction name="Print" />
</if>
 
<!-- The command function is used to make functions in PosXml Application. -->
<function name="Main" >
  <!-- The command inputmoney is used to enter money values in the terminal.
       The terminal shows a mask with comma and points, while pressing the digit keys.
       The captured value is multiplied by 100 and put in variable without comma and points.
   -->
   <inputmoney variable="$(integerValue)" line="0" column="0" message="Input de Value:" />
   <cleandisplay />
   <!-- The command inttostring is used to convert an integer variable in a string variable. -->
   <inttostring variableinteger="$(integerValue)" variablestring="$(stringValue)" />
   <display line="2" column="0" message="Value is:" />
   <display line="3" column="0" message="$(stringValue)" />
   <waitkey />
</function>
 
<function name="Print" >
   <!-- The command inputformat is used to enter a value in a specific format.
        The format is specified in the format parameter. The value captured is put in variable.
    -->
   <inputformat variable="$(stringName)" line="0" column="0" message="Enter your name:" format="AAAAAAAAAA" / >
   <print message="$(stringName)" />
   <!-- The command paperfeed is used to advance paper of the terminal's printer. -->
   <paperfeed />
</function>

Dealing with the POS file

<stringvariable value="" variable="stringRet" />
<stringvariable value="" variable="stringWriteKey" />
<stringvariable value="" variable="stringWriteValue" />
  
<inputformat variable="$(stringWriteKey)" line="0" column="0" message="Input a key:" format="AAAAAAAAAA" />
<inputformat variable="$(stringWriteValue)" line="2" column="0" message="Input a value:" format="9999999999" />
<!-- The command editfile is used to write or edit a file in 'Walk Db format'.
     The format of the file in 'Walk Db format', is: ('key=value\nkey=value\n ... '). 
-->
<editfile filename="test.txt" key="$(stringWriteKey)" value="$(stringWriteValue)" />
<!-- The command readfile is used to read a file in 'Walk Db format'.
     The format of the file in 'Walk Db format', is: ('key=value\nkey=value\n ... ').
     If the file or key does exist, the value is a white space ' '.
 -->
<readfile filename="test.txt" key="$(stringWriteKey)" variabledestination="$(stringRet)" />
<!-- The command deletefile is used to remove a file from the terminal's memory. -->
<deletefile filename="test.txt" />
<!-- The command joinstring is used to join firstvalue and secondvalue in variabledestination. -->
<joinstring firstvalue="Result:" secondvalue="$(stringRet)" variabledestination="$(stringRet)" />
<cleandisplay />
<display line="4" column="0" message="$(stringRet)" />
<waitkey />

An example with while "While"

<!-- The command "stringvariable" creates in memory one variable of a type string, in this case the name is "sData". -->
<stringvariable value="" variable="stringData" />
<stringvariable value="KEY_CANCEL" variable="stringKey" />
  
<!-- The command "while" realizes a loop till the condition be satisfied in this case,
     when the value of "sKey" be different of "KEY_CANCEL". 
-->
<while variable="$(stringKey)" operator="equalto" value="KEY_CANCEL" >
   <!-- The command cleandisplay is used to clean the terminal's display. -->
   <cleandisplay />
   <!-- The command "getdatetime" extract the date and the hour internal in format specified,
     and save this value in "variabledestination". 
   -->
   <getdatetime format="d/M/yy h:m:s" variabledestination="$(stringData)" />
   <!-- The command "display" shows a message in a row and column specific. -->
   <display line="2" column="0" message="$(stringData)" />
   <!-- The command "readkey" waits a specified time in miliseconds to save in a string on "variablereturn",
        case not be tight anybody key, will be return the value "KEY_CANCEL". 
   -->
   <readkey miliseconds="800" variablereturn="$(stringKey)" />
</while>

<display line="2" column="0" message="$(stringKey)" />
<waitkey />

POSXML

Language features

The structure of POSXML

Compiled language

Syntax

Commands and instructions

Command list

Variables and data types

File system

Code examples

The traditional "Hello World"

Menu, functions and impressions

Dealing with the POS file

An example with while "While"

References

See also