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

• getcardvariable

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 />

Menu, functions and impressions

<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 />

See also

• Credit cards
• Private label
• VISA
• Mastercard
• Visanet
• Redecard
• HDLC
• GPRS
• SSL
• RENPAC
• ADSL