Tag 030 - Virtual Keyboard

Simplify supports a Virtual Keyboard Message on touch screen devices. This message displays up to two lines of text at the top of the screen (Title1 field) together with a virtual keyboard.

Title fields should be used in order, starting with Title1. If this is insufficient, Title2 should be used for the additional text, and if necessary Title3. The maximum length of each Title field is 40 characters for the MX915 and 44 characters for the MX925. The maximum length of the formatted input (including any added literals) is 37 for the MX915 and 45 for the MX925.

If the Enter key is pressed, any text entered on the virtual keyboard is returned in the Virtual Keyboard Response.

Virtual Keyboard Message Format

Request

Field 5001

Field Name Length Description
TTT 3 Tag (always = 030)
LLL 3 Length of the following data
Title1 0-40 (MX915)
0-44 (MX 925)		 Title 1
FS 1 Field separator (Hex 1C)
Title2 0-40 (MX915)
0-44 (MX 925)		 Title 2
FS 1 Field separator (Hex 1C)
Title3 0-40 (MX915)
0-44 (MX 925)		 Title 3
FS 1 Field separator (Hex 1C)
Mode 1 Input Mode:
0=Normal (display characters as entered)
1=Password mode (characters are replaced by *)
(not used)
FS 1 Field separator (Hex 1C)
FormatString Var See below.
FS 1 Field separator (Hex 1C)
DisplayString Var This is where the literals for the field display are set up.

Format String

Each character in the FormatString field represents the valid input values for that position.

    C – Corresponding character is a literal, which may not be changed.
    N – Numeric value (0 – 9)
    A – Alpha character (A – Z)
    X– Any character

Display String

If literals are present in the FormatString field, the DisplayString field is used to set up the literals for the field display. The FormatString field determines the input format, regardless of what is in the display string. The format string and the display string (if used) need to be the same length, so the display string will automatically adjust to match the format string by padding with blanks or truncating the last field(s). Eg. (with blanks in the Display string represented as X's):

    Format string: CNNNCCNNNCNNNN
    Display string: (XXX)XXXX-XXXX

This will only allow numeric input, and preserve the literal formatting. The entire display string will be returned to the POS. If the literals are not desired, the POS will need to filter them out.

Response

Field 5001

Field Name Length Description
TTT 3 Tag (always = 030)
LLL 3 Length of the following data
ActionButton var If field 11 Completion Code = 000 (success), returns code for key pressed:
777=Enter (green) key
888=Cancel (red) key
FS 1 Field separator (Hex 1C)
Data 0-37 (MX915)
0-45 (MX925		 If ActionButton =777 (Enter), returns formatted input text (if any).

Sample Virtual Keyboard Message

Request

The following request tells Simplify to display the screen shown below.

API Field #, Value Description
0001,36 Transaction Type
0011,14124030000 User Data. See Appendix F for the use of this field.
5001, [see value below] Non-Financial Data
    030=Tag
    044=Length of data
    Enter Email Address=Title1
    1=Input mode (not used)
    XXXXXXXXXXXXXXXXXXXX=Format string

5001,030044Enter Email AddressFSFSFS1FSXXXXXXXXXXXXXXXXXXXXFS

sample enter email screen

Response

API Field #, Value Description
0001,36 Transaction Type
0011,14125020000?V142.18.65_2.18.1 User Data. See Appendix F for the use of this field.
5001,030019777FSTEST@ELAVON.COM Non-Financial Data
    030=Tag
    019=Length of data
    777=Enter key pressed
    TEST@ELAVON.COM=User input

Additional Samples (Request field 5001)

Value in Field 5001 Screen Use
030041Enter Date (YYMMDD)FSFSFS0FSNNCNNCNNFSMM/DD/YY Prompt for date
030041Enter Time (HHMMSS)FSFSFS0FSNNCNNCNNFS : : Prompt for time