0% found this document useful (0 votes)

33 views348 pages

Dokumen - Tips - Doc00310 Verix Evo Act Programmers Guide

This document is a programmer's guide for the Verix eVo ACT terminal. It provides information on integrating shared libraries, using the application idle engine, message/data entry engine, and ISO 8583 message interface engine in applications. The guide describes engine components, global data definitions, typical packet structures, and how to construct maps, tables, and implement conversion routines for each engine.

Uploaded by

srx dev

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

33 views348 pages

Dokumen - Tips - Doc00310 Verix Evo Act Programmers Guide

Uploaded by

srx dev

We take content rights seriously. If you suspect this is your content, claim it here.

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 348

Verix eVo ACT

Programmers Guide

VeriFone Part Number DOC00310, Revision B

Verix eVo ACT Programmers Guide

© 2010 VeriFone Systems
All rights reserved . No p art of the con tents o f thi s documen t may be rep roduced or transmitte d in any form witho ut th e written
permission of VeriFone, Inc.
The information contained in this d ocument is su bject to chan ge without notice. Although VeriFone has attempted to ensu re the
accuracy of the contents of this document, this document may include errors or omissions. The examples and sample programs are
for illustration only and may not be suited for your purpose. You should verify the applicability of any example or sample program
before placing the software into productive use. This document, including without limitation the e xamples and software programs, is
supplied “As-Is.”

VeriFone, the V eriFone l ogo, Verix eV o terminals are registered trademarks o f VeriFone. Other brand na mes o r trademarks
associated with VeriFone products and services are trademarks of VeriFone, Inc.
All other brand names and trademarks appearing in this manual are the property of their respective holders.
Comments? Please e-mail all comments on this document to your local VeriFone support team.

VeriFone Systems
2099 Gateway Place, Suite 600
San Jose, CA, 95110 USA
(800) VeriFone (837-4366)
www.verifone.com
VeriFone Part Number DOC00310, Revision B

CONTENTS

CHAPTER 1
Introduction Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Manual Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Syntax Notation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Code Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

CHAPTER 2
Getti ng Started Shared Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
wit h Verix eVo ACT Building Applications Referencing a Shared Library. . . . . . . . . . . . . . . . . . . 17
Library Resides in Flash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

CHAPTER 3
Programmers Function Calls. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Quick Reference

CHAPTER 4
Ap pl icat io n Id le Integrating the AIE into an Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Engine Programmer-Defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Application-Defined Idle Loop Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Handling CANCEL Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Slow Poll function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Fast Poll function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Application Idle Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Branch Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Function Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Event Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
System Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Periodic Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Application Idle Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

CHAPTER 5
Message/Data Message File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Entry Engine TXOFILE Utility. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
File Type and Compression Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Message File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Message/Data Entry Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

CHAPTER 6
ISO 8583 Message ISO 8583 Engine Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Interface Engin e ISO 8583 Bitmaps. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Message Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
ISO 8583 Engine Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

VERIX EVO ACT PROGRAMMERS GUIDE 3

C ONTENTS

Engine Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Engine Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Incorporating the Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Global Data and Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Global Defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Global Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Typical Host/Terminal Packet Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Application Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Map Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Map Manipulation Routines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Field Table Construction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Variant Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Computed Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Convert Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Conversion Routines. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Packet Assembly and Disassembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
ISO 8583 Message Interface Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

CHAPTER 7
ISO 8583 Prot oco l ISO 8583 Protocol Engine Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Engine Programmer-Defined Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
mdm_tr_8583 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
def_valid_8583 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
prot_8583() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
check_8583_tpdu_msg_id() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
process_8583_request() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

CHAPTER 8
PIP Engine Compiling Source Code Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Programmer-Defined Functions/Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PIP Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
PIP Engine and Application Construction Toolkit . . . . . . . . . . . . . . . . . . . . . 80
Modular Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
ISO 8583 Protocol. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
ISO 8583 Message Engine. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
The Field Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
The Convert Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Variant Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Computed Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
ISO 8583 Protocol Engine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Protocol 8583 Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Programmer-Defined Setup Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Integrating the PIP Engine Into Your Application . . . . . . . . . . . . . . . . . . . . . . . . 89
AMEX Validation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
The Validation Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
PIP Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Troubleshooting PIP Application Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
PIP/ISO 8583 Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

4 VERIX EVO ACT PROGRAMMERS GUIDE

C ONTENTS

CHAPTER 9
Data Capture Keyed File System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Engine Application Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Data Capture Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Example Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

C H A P T E R 10
Modem Engine Modem Engine Functions and Macros. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
MDM_READ_BLK() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
MDM_RESET_ERROR() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
MDM_STATUS(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
MDM_WRITE_BLK() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
XMODEM.H Listings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
XMODEM.H Structures and Unions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Modem Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Example Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

C H A P T E R 11
Report Formatter Incorporating the Report Engine in an Application . . . . . . . . . . . . . . . . . . . . . . 118
Conditional Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Report Conversion Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Report Format Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Report Format File Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Example Format File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Global Variables Declaration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Data Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Global #defines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Global Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Sample Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Report Formatter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Example Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

C H A P T E R 12
Database Lib rary Database Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Database File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Index File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
File Storage Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
File Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Database Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

C H A P T E R 13
Printer Drivers Verix eVo Based Terminal ITPs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Downloadable User Fonts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Downloadable Printer Logo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Printing Monochrome Bitmap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Printer Driver Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Example Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133

VERIX EVO ACT PROGRAMMERS GUIDE 5

Organization The organization of the manual is as given in Table 1:

Table 1 Organization
Chapter Description
Chapter 1, Introduction Provides information on the Verix eVo ACT Library,
including modules supported within the library.
Chapter 2, Getting Started Lists the advantages of using Verix eVo ACT and
with Verix eVo ACT describes the procedure to build an application using
ACL as a shared library.
Chapter 3, Programmers Lists the system function calls and its description for
Quick Reference Verix eVo Operation System.
Chapter 4, Application Idle Describes the features of AIE, describes the process
Engine flow of Integrating the AIE into the application, and
lists the different function calls, events and its usage.
Chapter 5, Message/Data Lists the tasks that Message/Data Entry Engine is
Entry Engine responsible, describes the message file, and
TXOFILE Utility.
Chapter 6, ISO 8583 Provides an overview on ISO 8583 Engine, ISO 8583
Message Interface Engine Interface Engine components, files, global data
definition, variables, and structures.
Chapter 7, ISO 8583 Protocol Describes about the ISO 8583 Protocol Engine data
Engine structure and programmer defined functions.
Chapter 8, PIP Engine Describes the PIP Engine, modular design that is
adopted, ISO 8583 Message Engine, programmer-
defined function calls, and the structure of the 8583
protocol used.
Chapter 9, Data Capture Explains about the Data Capture Engine, key files
Engine and application data.
Chapter 10, Modem Engine Describes about the Modem Engine and macros used
in that Modem Engine.

VERIX EVO ACT PROGRAMMERS GUIDE 11

I NTRODUCTION
Re fe ren ce s

Table 1 Organization (continued)

Chapter Description
Chapter 11, Report Formatter Explains the report formatter and the steps to use it.
Chapter 12, Database Library Lists the features of database library, file formats, and
file storage structure.
Chapter 13, Printer Drivers Describes information about the Verix eVo based
Terminal ITPs, downloadable fonts, logos. Explains
about different dot matrix printers that communicate
with the host terminal through the RS-232 port.
Chapter 14, Function Calls Describes the different function calls for various
modules.
Appendix A, Example Provides example codes for different programming
Programs functions.

References Refer to the following set of manuals for additional information on the Verix eVo
OS or the Verix eVo TX OS:
• AMEX Express 3000 PIP Terminal Technical Specifications
In addition to VeriFone programming support manuals listed in the introduction
section of this manual, refer to the following industry manuals for PIP application
development:
• ISO 8583 Bank Card Originated Messages—Interchange Message
Specifications—Content for Financial Transactions (part number ISO 8583:
1987(E))
• AMEX Express 3000 PIP Terminal Technical Specifications

12 VERIX EVO ACT PROGRAMMERS GUIDE

I NTRODUCTION
Ma nu al Conv en ti on s

Manual This section provides a quick reference to conventions, syntax notation, and
Conventions acronyms used in this manual, and discusses how to access the text files
associated with code examples.

Conventions The following conventions help the reader distinguish between different types of
information:
• The cour i er typeface is used for code entries, filenames and extensions, and
anything that requires typing at the DOS prompt or from the terminal keypad.
• The italic typeface indicates book title or emphasis.
• Text i n blue indicates terms that are cross-referenced. When the pointer is
placed over these references the pointer changes to the finger pointer,
indicating a link. Click on the link to view the topic.

NOTE
Note points out interesting and useful information.

CAUTION
Caution points out potential programming problems.

The various conventions used throughout this manual are listed in Table 2.
Table 2 Conventions
Ab br evi ati on Defini ti on
bps bits per second
KB KiloByte
MIN minimum (value)
ms Millisecond (one-thousandth of a second)
sec seconds

Syntax Notatio n This library reference uses the following syntax notation:
c har * f get s ( c har * s t r g, i nt n, The Cour i er typeface is used for
FI LE * st r m) ; source code, DOS commands, and
filenames.
%[ *] [ wi dt h] [ modi f i er ] Items in braces are optional, such as an
optional argument to a function.
( st r eam, f or mat [ , ar gument , . . . ] ) ; A series of three dots (either in a
column or in a line) signifies that an item
can be repeated any number of times.
S_I READ | S_I WRI TE A vertical bar separates optional
choices.

VERIX EVO ACT PROGRAMMERS GUIDE 13

I NTRODUCTION
Ma nu al Co nv en ti on s

variable Variable names (identifiers) or

information to be supplied by the
programmer appears in italics.
0x7F Hexadecimal values are denoted with a
leading 0x.

All source code characters are case sensitive. For example, f pr i nt ( ) and
FPRI NT( ) may not be the same facilities. All source code punctuation must be
included as shown.

Ac ro ny ms The acronyms used in this manual are listed in Table 3.

Table 3

Acronym Definitions
Ac ro ny m Defini ti on s
AC Application Construction
ACL Application Construction Library
ACT Verix eVo ACT
AIE Application Idle Engine
ADR Address
AMEX American Express
API Application Programmers Interface
ASCII American Standard Code for Information Interchange
BCD Binary Coded Decimal
ABA American Bankers Association
BLEN Backward Length
C C-Language Program
CAS Credit Authorization System
CB Control Byte
CLR Clear
CCITT Comite Consultatif International de Telegraphique et Telephonique
COM Common Object Model
CR Carriage Return
CRC Cyclic Redundancy Check
CTS Clear To Send
CVLR Compressed Variable Length Records
DATA REC Data Record
DCD Data Carrier Detect
DCP Distributed Credit Authorization System (CAS) Processor
DOS Disk Operating System
DVLR Double Variable Length Records
EOF End Of File
ESC Escape
FLEN Forward Length
HDLC High-Level Data Link Control

14 VERIX EVO ACT PROGRAMMERS GUIDE

I NTRODUCTION
Ma nu al Conv en ti on s

Table 3 Acronym Definitions (continued)

Ac ro ny m Defini ti ons
ID Identification
IATA International Air Transport Association
ISO International Organization for Standardization
ITP Internal thermal printer
IVLR Integer Variable Length Records
MAC Message Authentication Code
N/A Not Applicable
NMS Network Management System
OS Operating System
PC Personal Computer
PIP Plural Interface Processing (also referred to as split-dial)
POS Point-Of-Sale
PVN Providian Financial Corporation
RAM Random-Access Memory
REV_OFF No Reversal Processing
REV_ON Normal Reversal Processing
REV_ONLY Process Only a Pending Reversal
RI Ring Indicator
ROC Record of Charge
RRN Retrieval Reference Number
RX Receive
SDK Software Development Kit
SDLC Synchronous Data Link Control
SDS Software Development Suite
TNMS Telecommunication Network Management System
TPDU Transport Protocol Data Unit
TX Transmit
TXO Transaction eXpress Option
VFI VeriFone
VLR Variable Length Records
VPN VeriFone Part Number

Code Examples Links to code example text files included on the Verix eVo ACT CD are provided
throughout this manual. The . t x t file opens in your specified default text editor.

NOTE
Writing your own applications is recommended.

Links are referenced by the underlined word Example; click on the following
section title to bring up a text file example:

VERIX EVO ACT PROGRAMMERS GUIDE 15

I NTRODUCTION
Ma nu al Co nv en ti on s

Example

NOTE
So that the entire code example can be read on screen, ensure that the word-
wrap option is enabled in your preferred text editor.

16 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 2

Getti ng Started wi th Verix eVo ACT

Verix eVo ACT is a collection of C code modules designed to reduce the effort
required to design and develop applications for VeriFone Verix eVo based
terminals.
Verix eVo ACT provides the following benefits:
• Reduces design, coding, and testing time. Commonly used functions and
procedures are simply incorporated into your new and existing applications
designs.
• Consistent methodology for common procedures. Using Verix eVo ACT
ensures that applications complete the same tasks in the same way. This
reduces the amount of effort to debug new code and eases the effort required
for quality control.
• Easier maintenance. One of the time consuming tasks of code maintenance is
the learning curve required when a new programmer must enhance or modify
an application. Verix eVo ACT provides code that the programmer can already
be familiar with and can concentrate on the unique aspects of the application.
• Optimization and error trapping. The Verix eVo ACT modules provide error
trapping and have been compiled with full optimization. This helps to provide
the most efficient code for the application programmer.
• Code leveraging. The application programmer can develop additional
specialized functions using the Verix eVo ACT modules as a base. This helps
control the size of the application by reusing code from the toolkit. The
components of the toolkit use this principle as the various engines call AC
Library (ACL) functions to complete their tasks.

Shared This chapter describes using the ACL as a shared library.

Libraries In a multi-application environment, more than two applications can reside on a
single Verix eVo based terminal. However, the memory space available on the
terminal is limited. To efficiently utilize the memory on the terminal, use a common
copy of the ACL for all applications. Verix eVo ACT allows the application to be
linked to the library as a shared library.

Building This section explains the procedure for building an application using ACT as a
Ap pl ic ati on s shared library. Change the project make file (typically the SMK file) to build the
Referencing a terminal application for the shared version of ACT. For example, build the
Shared Library sample.c file with the shared version of ACT. The following is a sample . MAK file
with the changes required for using ACT as a shared library:

VERIX EVO ACT PROGRAMMERS GUIDE 17

G ETTING S TARTED WITH VERIX E VO A CT

Shared Libraries

Example The linked example code file demonstrates use of MAK().

Library Resides in In the previous example, the sample application is built so that the shared ACL
Flash resides in the terminal flash memory. The following is an example download file,
where s et dr i ve. f designates the flash partition, set gr oup. 15 is the flash
memory partition, GI D 15, and s et dr i ve. i designates the RAM partition:
*go=sampl e. out
setgr oup. 15
- i act . l i b. p7s
s et dr i ve. f
- i act . l i b
s et dr i ve. i
setgr oup. 1
- i sampl e. out
- i sampl e. out . p7s

18 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 3

Programmers Quick Reference

This section provides programmers quick access to system function calls,

CONFIG.SYS variables, device variables, error codes, download procedures,
instructions on erasing flash, and keypad key return values for the Verix eVo
operating system.

Function Calls The functions listed in Table 4 are arranged by device or purpose. Refer to the
function description for associated parameters and valid error conditions, and
details on how and when to use the function. In the online version of this manual,
the page number can be clicked on to jump to the function description.
Table 4 Function Calls
Function Call Description Page

ISO 8583 Message Int erface Engi ne

Table 4 Function Calls (continued)

Function Call Description Page
short db_open Creates a database file and the corresponding 306
( DB_FI LE *db_pt r , char *f i l ename, i nt key_l en,
index file and updates the database file structure.
i nt mode) ;
shor t db_r ead Retrieves a specified record from the database 307
( DB_FI LE *db_ptr , voi d *key_st r uct , char *data_buf ,
file.
i nt dl en, l ong rec_num) ;
shor t db_r emove(char *f i l ename); Deletes the database file and the corresponding 308
index files.
l ong db_seek_key Searches the index file records for the specified 309
( DB_FI LE *db_pt r , voi d *key_str uct, voi d *Matchst r ,
key value.
l ong acti on, l ong *r ec_num) ;
l ong db_seek_r ecor d Searches for a specified record in an index file 310
( DB_FI LE *db_ptr , l ong r ec_num, i nt or i gi n) ;
and modifies the file pointer position accordingly.
short db_wr i t e Writes/updates a record in both the database and 311
( DB_FI LE *db_ptr , voi d *key_st r uct , char *data_buf ,
index files.
unsi gned i nt dat a_l en, l ong r ec_num) ;
Print Pak 3700 Functi on Calls
i nt p3700_cl ose( shor t h_comm_por t ) ; Waits for all pending data to transmit to the 313
printer, then returns.
short p3700_dnl d_char Transmits a single character to the printer. 314
( shor t h_comm_por t , unsi gned char *r d_buf ,
unsi gned shor t wr i t e_bytes);
short p3700_dnl d_f ont _f i l e Downloads a font file set to the printer. 315
( short handl e, short h_f ont _f i l e,
s hor t f ont _ t abl e) ;
short p3700_dnl d_graphi c_f i l e Downloads a graphic logo file into the printer. 316
( short h_comm_port , short h_graphi c_f i l e) ;
i nt p3700_i d( shor t h_comm_por t , shor t i d_t i me_out ) ; Sends the <ESC>i command (request printer ID) 317
to the ITP, and waits for a response.
i nt p3700_i ni t ( short h_comm_por t , short t i me_out ) ; Sets the printer to native mode by sending the 318
<GS><ESC>c<GS> command.
unsi gned char *p3700_mode Converts special print characters to a valid printer 319
( unsi gned char mode, unsi gned char * buf ) ;
command sequence.
i nt p3700_pri nt Sends a text string to the ITP. 319
( short h_comm_port , unsi gned char *buf ) ;
short p3700_pri nt _graphi c Prints a graphic file already in printer memory. 320
( short h_comm_port , short i mageI d, short of f set ) ;
shor t p3700_sel ect_ f ont Selects the font table to use for printing or 320
( short h_comm_port , short f ont _si ze,
downloading.
s hor t f ont _ t abl e) ;
shor t p3700_sel _t bl _dnl d_char Selects the font table, and then downloads a 321
( shor t h_comm_por t , unsi gned char * f ont _buf ,
single font character to the printer.
s hor t f ont _ t a bl e, s hor t f ont _ s i z e,
s hor t f ont _ byt e s) ;
i nt p3700_st at us Sends the <ESC>d command to the ITP and 322
( short h_comm_port , short st at_t i me_out ) ;
waits for it to respond with its status byte.
Printing Monochrome Bitmap
pr i nt _i mage( i nt of f set , char * f i l ename) ; Prints the monochrome bitmap. 311

30 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 4

Application Idle Engine

In a typical transaction environment, the terminal waits for an event (card swipe,
keypress, or incoming dialup) to continue the application. This is known as theidle
state. From the idle state, every application is required to execute tasks that are
triggered by such events. Other tasks, such as opening devices or setting flags,
are only required to execute during power up or on return from another code
module.
The Application Idle Engine (AIE) assists the application programmer in managing
the idle state; it acts as a traffic manager. When an event occurs at the idle state,
such as a keypress or card swipe, the engine references an application-defined
table to determine which function to execute. The format and functions of the
Application Idle tables are described in this manual.

NOTE • AIE will not support the dual keypress events.

• VX680 terminal does not have alpha and functional keys.

Integrating t he AIE is designed to be used as a generic module. It provides most of the

AIE into an functionality required to process events from the idle state; however, it does not
Applicat ion provide the functionality unique to each application. The engine cannot know if the
application must monitor the system clock, perform an upload at a specified time,
and what processing to perform each time the terminal powers up. To help meet
the applications requirements, AIE assists in creating the following application
routines:
• System initialization (power up)
• Cancel key processing
• Display the idle prompt (as required)
• Idle state processing
Figure 1 illustrates the AIE role in the application.

VERIX EVO ACT PROGRAMMERS GUIDE 31

A PPLICATION I DL E E NGINE
In te grat in g th e AIE in to an Appl ic at io n

ai e_mai n( ) (BRANCH TABLE, IDLE TABLE,

IDLE LOOP FUNCTION, FAST POLL HANDLER,
SLOW POLL HANDLER, ACTIVATE HANDLER,
DEACTIVATE HANDLER)

SET TIMERS
IDLE LOOP TIMERS
SLOW POLL TIMER
FAST POLL TIMER
CANCEL KEY DETECT TIMER

IDLE LOOP FUNCTION

DETECT EVENT

N
EVENT OCCURRED

N
TIMER EVENT

PROCESS TIMER

ACTIVA TE/ N
DEACTIVATE
EVENT

Y
HANDLE
ACTIVA TE/DEACTIVA TE

N
ANY OTHER EVENT

CLEAR TIMER

PROCESS EVENT

RESET TIMER

Fi gur e 1 A pp li cat io n Pr oc es si ng Fl ow Ch ar t
32 VERIX EVO ACT PROGRAMMERS GUIDE

A PPLICATION I DL E E NGINE
Ap plic at io n- De fi ne d Idle Lo op Func ti on

Programmer- Figure 1 shows functions in the application idle process that must be written by
Defined Functions the programmer. These functions allow the application to easily meet the specific
requirements within the framework of the AIE.

Ap pl ic ati on Ini ti ali zation

The application defines the mai n( ) of the program. The functionality defined by
appl _col dboot ( ) can be directly invoked by the application. Before calling
aie_main(), the application should typically execute tasks performed during
system initialization, such as:
• opening devices to be accessed by the application (card reader, modem, and
so on)
• setting or testing flags (such as a download-needed flag)
• performing file maintenance
• moving CONFIG.SYS data to a file
• setting up user passwords. If the cancel key trap is armed in this function, it is
overwritten (see Figure 1). In addition, this function must return TRUE (1). Any
other return value causes AIE to exit.

Applicat ion- The Idle Loop function is passed as a parameter to aie_main() and is the main
Defin ed Idle loop in the engine. It is called immediately after the timers are set, and then once
Loop Function per cycle. This function can be used for timed events, such as:
• print spooler management,
• automatic upload or download of data,
• idle display management,
• automatic settlement, and
• error processing.
Since this function is called once per cycle, the code must be very efficient.
Executing complex or time-consuming operations in this function delays event
processing of events.

Handling CANCEL Handling the cancel key is the responsibility of the application. Use the
Key KEY_CANCEL parameter of act_kbd_pending_test(), to determine if a cancel key
is pending and the appropriate action is taken. In the idle state, AIE periodically
checks (50 ms) for the cancel key and flushes the keyboard.

Slow Poll funct ion The Slow Poll function, defined by the application, is called by AIE once every
250 ms during the normal idle state. The programmer can create code to
determine if programmer-defined events have occurred and handle them.

Fast Poll fu nction The Fast Poll function, defined by the application, is called by AIE once every
50 ms during the normal idle state. The programmer can create code to determine
if programmer-defined events have occurred and handle them.

VERIX EVO ACT PROGRAMMERS GUIDE 33

A PPLICATION I DL E E NGINE
Ap pl icat ion Id le Tabl es

Both the slow poll and fast poll functions can be used to perform any periodic
activity.

Applicat ion One powerful feature of the AIE is its ability to use tables to control event
Idl e Tables processing. Two tables are required by the engine: the Branch Table and the
Function Table. These must be passed as parameters to aie_main(), however,
create additional tables to meet the requirements of the application. To
understand the relationship between Branch Table and Function Table and how
they are used by the engine, refer to Figure 2.

Figur e 2 AIE Event Proc essi ng Tabl e

Branch Table The Branch Table contains an index to function pointers defined in the Function
Table. Each time an event occurs in the idle state, the event processor accesses
the Branch Table to determine which function to process. Each entry in the Branch
Table has three members:
• The event to process (defined in APPLI DL. H)
• The index into the Function Table
• The current (new) Branch Table to access on return from the function

34 VERIX EVO ACT PROGRAMMERS GUIDE

A PPLICATION I DL E E NGINE
Ap plic atio n Id le Tabl es

The Branch Table function increases flexibility and reduces code space by
allowing creation of a table-driven application. To do this, create two tables that
reference the events to process (refer to the idle_table[ ] and appl_table[ ]
examples) and the br anch_t abl e( ) function does the rest. After executing the
event, br anch_t abl e( ) returns a pointer to the next table used to process
events.

NOTE To switch to the new Branch Table, BRANCH_EXIT or any non negative value can
be returned from the event handler functions. The following example shows that
the KEY_CR event sets f unc_t abl e[ ] as the new Branch Table. After executing
the KEY_CR event handler function, f unc_t abl e[ ] becomes the active table
and waiting for events. func_table[] does not become the active Branch Table
unless the function referenced by FT_FUNC returns BRANCH_EXIT or any non
negative value. In this case, if any non negative value is returned from the handler
function, the event is processed in the active table ( f unc _t abl e[ ] ) and not in
the idle table.

Example The linked code example file demonstrates use of br anch_t abl e( ) .

NOTE
BRANCH_TBL_ENTRY is defined in APPLI DL. H (using typedef).

In addition to the programmer-defined table entries (for example, keypress or card

swipe), the engine recognizes five other table entries:
• END_TABLE (required)
• COMMON_FUNC (optional)
• ENTRY_FUNC (optional)
• ERROR_FUNC (optional)
• EXIT_FUNC (optional)
Using any of the above four optional entries to perform common routines will
reduce code space and increase application flexibility. If any of these entries are
used in the application, the entry must be included in both the Branch Table and
the Function Table, as well as write the function that executes when the entry is
processed (see the BRANCH_TBL_ENTRY example above).

END_TABLE

This entry is required to truncate the table. It must be the last entry in the table. All
entries occurring below END_TABLE are ignored. In addition, this entry can be
used to process invalid application events, that is, events returned by the event
handler functions (callback functions) and not listed in the active Branch Table.
For example, in i dl e_ t abl e[ ] only KEY1 - KEY5 are mapped and event
handler functions are provided. If any of the event handler functions return KEY6

VERIX EVO ACT PROGRAMMERS GUIDE 35

A PPLICATION I DL E E NGINE
Ap pl icat ion Id le Tabl es

which is not listed in the active table, the function associated with the
END_TABLE entry is processed. The END_TABLE function can be used for error
beep and display “INVALID KEY” etc. However it can still perform any other tasks
required by the application. The END_TABLE function will not get executed for the
system generated events which are not listed in the table. Refer to the Example
for more details.

COMMON_FUNC

This entry executes prior to any other event for example, used to display
messages or set transaction flags.

ENTRY_FUNC
This entry executes if Branch Table entry is called with the current event set to 0
(zero). After execution, ENTRY_FUNC must return the next valid event to process
(refer to APPLIDL.H) for example, use ENTRY_FUNC to display a menu. When
the user makes a selection from the menu, ENTRY_FUNC returns the keypress
as the next event to process.

ERROR_FUNC

This entry executes if the value returned by an event is a negative value, which is
then passed to ERROR_FUNC. The return values from ERROR_FUNC have the
following significance:
• Positive integers ( 0): Process the return as the next event within the same
table.
• Negative integers (< 0): Process the absolute value of the return as the next
event, under the next (branch) table, as indicated by the current table entry.
• BRANCH_EXIT: Exits with no new events; forces the engine under control of
the idle_table.

EXIT_FUNC
This entry executes prior to passing control to another table, or when
BRANCH_EXIT is returned under the current table. For example, it can be used to
hang up the phone, complete a print job, or perform other housekeeping tasks.
The previously described entries can be placed anywhere in the table (with the
exception of END_TABLE); however, the entries are always processed in the
following order:
1 COMMON_FUNC

2 ENTRY_FUNC

3 Standard event (for example, a keypress or card swipe)

4 ERROR_FUNC

5 EXIT_FUNC
36 VERIX EVO ACT PROGRAMMERS GUIDE

A PPLICATION I DL E E NGINE
Ap plic atio n Id le Tabl es

Functi on Table The Function table is an array of pointers to integer functions. Each element in the
table is a name of an application-defined function written to process an event.
Every entry in the Branch Table must have a corresponding entry in the Function
Table.

Example PF_TABLE appl _t abl e[] =

{
sal e_t r an,
f or ce_t r an,
c r edi t _ t r an,
voi d_t r an,
f unc_ mai n,
i dl e_common,
i dl e_ exi t ,
i dl e_ er r or ,
not _avai l abl e,
( PF_ TABLE) END_TABLE
};

NOTE To make referencing the function name to the corresponding table entry value
easier, include the #def i ne directive above the function name. The #def i ne
values must start at 0 (zero) and continue in ascending order.

Example appl _ t abl e[ ] wi t h #def i nes

PF_TABLE appl _t abl e[] =
{
#def i ne FT_SALE 0
sal e_t r an,

#def i ne FT_ FORCE 1

f or ce_t r an,

#def i ne FT_ CREDI T 2

c r edi t _ t r an,

#def i ne FT_VOI D 3
voi d_t r an,

#def i ne FT_FUNC 4
f unc_ mai n,

#def i ne FT_COMMON 5
i dl e_common,

#def i ne FT_EXI T 6
i dl e_ exi t ,

VERIX EVO ACT PROGRAMMERS GUIDE 37

A PPLICATION I DL E E NGINE
Ap pl icat ion Id le Tabl es

#def i ne FT_ ERROR 7

i dl e_ er r or ,

#def i ne NO_KEY 8
not _avai l abl e,

( PF_ TABLE) END_TABLE

};

These functions must be integer functions with no parameters. In addition, the

functions must return one of the following values:
• A value  0 indicates an error. In this case, the ERROR_FUNC entry executes
(if included in i dl e_ t abl e[ ] and appl _t abl e[ ] ).
• BRANCH_EXIT: Continues processing (defined in APPLI DL. H).
• A valid event number to process (as defined in APPLI DL. H). Returning an
event number causes the event to be processed as if it was executed from the
idle state.

38 VERIX EVO ACT PROGRAMMERS GUIDE

A PPLICATION I DL E E NGINE
Even t De te ct io n

Event AIE detects events for all devices opened by the application.
Detection

System Events System events are as follows:

APPL_CARD Magnetic card reader event

C1_IN COM1 event

C2_IN COM2 event

BARIN Barcode reader event

PIPE_IN Pipe event

C3_IN COM3 event

C4_IN COM4 event

C5_IN COM5 event

ICC1_IN Smart card reader1 event

DEACTIVATE_IN Deactivate event

ACTIVATE_IN Activate event

SYSTEM_IN System event

CONSOLE_IN Console event

CLK_IN Clock event

TIMER_IN Timer event

USB_IN USB event

C6_IN C OM6 event

WLN_IN WL AN event

USER_IN User event

SHUTDOWN_IN Sh utdown event

USB_CLIENT_IN USB slave event

C8_IN C OM8 event

SOCKET_IN Socket event

NOTE
To avoid wasting system resources, do not set traps at the idle state for these
devices.

Perio dic Events AIE sets up four timers to handle:

• idle loop processing,
• cancel key detection,
• slow poll handling, and
VERIX EVO ACT PROGRAMMERS GUIDE 39

A PPLICATION I DL E E NGINE
Ap pl icat ion Id le Fu nc tion s

• fast poll handling.

The programmer may define Slow Poll and Fast Poll functions that will be called
periodically. These need to be passed as parameters to aie_main(). The Idle Loop
function defined by the application is called periodically when the idle loop
processing timer expires.
Similarly, in the idle state, on a Cancel key detect timer, the AIE checks for the
Cancel Key and flushes the keyboard.
All of the following four timers are configurable and can be set using the calls
specified in the Application Idle Engine Function Calls. The default values are:
• Idle timer - 750 msec
• Cancel timer - 50 msec
• Slow Poll timer - 250 msec
• Fast Poll timer - 50 msec

Applicat ion The application idle functions are described in the Application Idle Engine
Idle Functio ns Function Calls section.

40 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 5

Message/Data Entr y Engine

The Message/Data Entry Engine is a group of functions that control the display of
prompts and messages, and reads data from the keypad or card reader. This
library assists application development in the following tasks:
• retrieve messages,
• clear the display,
• display messages,
• set the cursor position,
• wait a specified time for a keypress, and
• accept input from the keypad or cardreader.
Other functions in this library support manual- or auto-scrolling through
messages, which is useful for displaying long messages or menus.

Mess age File The functions in the Message/Data Entry library are designed to retrieve prompts
and messages from a message file created by program called TXOFILE. The
format of the message file and instructions on how to create it are provided in this
section.
While other types of files are discussed, the Message Engine is designed to use
only message-type files that use any of the available compression types.

TXOFILE Util it y TXOFILE is a PC-based utility that allows quick and easy generation of TXO-
compatible files that can be downloaded to the terminal. Using a DOS program to
generate application modules provides two important advantages:
• The application code space is reduced because the data is stored in a file.
• This method provides greater flexibility since the data is not compiled as part
of the application. If the data in the file needs to be modified, only the file is
updated and downloaded to the terminal, rather than through the application.
Files generated by TXOFILE typically contain data that is not modified by your
application program (for example, prompts and messages). Although TXOFILE is
discussed here in conjunction with the Message/Data Entry Library, it also
supports additional file and compression types that allow you to generate binary
files, and so forth. The following sections list the file and compression types
supported by TXOFILE. Before you select a file and compression type, review the
file type and compression type considerations discussed later in this section.

VERIX EVO ACT PROGRAMMERS GUIDE 41

M ESSAGE /D A TA E NTRY E NGINE

TXOFILE Utility

Compression Types

• 8 bit-to-6 bit (lowercase characters are converted to uppercase)

• 8 bit-to-4 bit (uppercase and lowercase characters are preserved)
• BCD (only digits are compressed)
• No compression

File Types

• VLR
• CVLR
• DVLR
• Fixed
• Keyed
• Message (ASCII)

TXOFILE Comm and Lin e Opti ons

The input file should have the following string if two byte addressing is used. This
string should precede any valid messages.
"/ * Byte addr essi ng: 2 */ "

To install TXOFILE, copy t xof i l e. exe and msgf mt . exe file to the same

directory on your PC. Follow standard DOS pathing conventions (place the file in
a PATHed directory or edit the AUTOEXEC.BAT PATH line). To display the
command line syntax and compression/file type/format, enter TXOFILE with no
command line arguments.

TXOFILE Syntax
t xof i l e [- opt i ons] i nput _f i l ename out put _f i l ename

TXOFILE Option s

The options are case sensitive. Each option must be preceded by a dash:
- p ( s pec i f i er ) ( f or mat - I nt el or Mot or ol a)

i Indicates that the input file uses two byte addressing and bytes need to be
swapped.
m Indicates that the output file should be generated for Motorola format, that is, the
bytes are not swapped.

- c ( t ype#) ( compr essi on t ype)

0 No compression (default)

1 8-to-6 bit

42 VERIX EVO ACT PROGRAMMERS GUIDE

M ESSAGE /D AT A E NTRY E NGINE

TXOFILE Utility

2 8-to-4 bit (VFI)

3 BCD

- t ( speci f i er ) ( f i l e t ype)

c CVLR
d DVLR
f Fixed
k Keyed
m Message file (default)
v VLR

NOTE
The default values are no compression and message file.

Example Assume that input.txt has messages specified in two byte addressing. Add the
string “/ * Byt e Addr essi ng: 2 */ ” to i nput . t xt . This string should precede
the list of valid messages. Run t xof i l e. exe as follows:
t xof i l e - pi i nput . t xt out put . dat

The generated message file output.dat can be used with an application running on
a PC.

Recommended Usage

Run TXOFILE utility twice for the same input file; once with - pi option and once
without the - pi option.

Example t xof i l e - pi i nput . t xt f i l ename. i at

This generates the message file for a PC.

t xof i l e i nput . t xt f i l ename. dat

This generates the message file for a terminal. Note the change in the file
extension for the two output files.
In the application, select the message file as follows:
#i f def _WI NDOWS
ms g_ s el ec t _ f i l e( f i l ename. i at )
#el se
msg_sel ect_f i l e( f i l aname. dat )
#endi f

You do not need to change the application for SDS compilation. You also do not
need to download *. i at files to the terminal.

VERIX EVO ACT PROGRAMMERS GUIDE 43

M ESSAGE /D A TA E NTRY E NGINE

File Type and Compression Type

File Typ e and The file type and compression type options you specify on the command line are
Compression determined by the type of data being stored in the file and how it is accessed by
Type your application. The following information explains how TXOFILE handles the
various file types.

CVLR, Fixed Length , and Keyed Files

You cannot specify a compression type parameter. TXOFILE automatically

compresses CVLR and keyed files using 8-bit-to-4-bit compression. Fixed length
and DVLR files are not compressed.

Message Files

These include a two-byte header record. Byte 1 (0x02) indicates the length of the
header record. Byte 2 indicates the type of compression used. It is recommended
that you select 8-to 6-bit compression for message files.

Hex, Octal, and Decimal Values

TXOFILE supports hex, octal, and decimal values in a quoted string. For example,
\x0F is stored in the output file as one byte (0x0F). These values must be
preceded by \n where n is one of the following:
• x or X: The two letters/digits immediately following the \X or \x are treated as
two hex digits and are stored as one byte in the output file.
• 0–7: The three digits immediately following the \ are treated as three octal
digits and are stored as one byte in the output file.
• d or D: The three digits immediately following the \D or \d are treated as three
decimal digits and are stored as one byte in the output file.

NOTE
Values represented by hex, octal, or decimal cannot exceed 255 decimal.

Mess age File A message file is an ASCII file that contains one #def i ne directive for each
Format message (refer to the following example). The #def i ne is not required, however,
it allows you to relate the record number to the associated message.
#def i ne ENTER_CODE 1
/ * Message number f or " ENTER CODE" */
#def i ne PRI MARY_ PHONE 2
/ * Message number f or " PRI MARY PHONE#" */
#def i ne ALT_PHONE 3
/ * Message number f or " ALT PHONE #" */
#def i ne MERCHANT_ I D 4
/ * Message number f or " MERCHANT I D #" */

Each line in the message file must conform to the following format:
#def i ne [ name] [ val ue]

44 VERIX EVO ACT PROGRAMMERS GUIDE

M ESSAGE /D AT A E NTRY E NGINE

Me ssag e/ Da ta En try Func tion s

/ * Mess age number f or " [ message] " * /

When TXOFILE processes the input file, the value becomes the record number
and the quoted string within the comment becomes the message text in the output
file.

NOTE In the message (quoted string), only include ASCII characters. Escape sequences
(for example, hex or decimal) are not valid unless they are indicated by \x0F, \187,
\d032, and so on.

Message/Data The message/data entry functions are described in Message/Data Entry Engine
Entry Function Calls.
Functions

VERIX EVO ACT PROGRAMMERS GUIDE 45

M ESSAGE /D A TA E NTRY E NGINE

Me ssag e/ Da ta En try Func ti on s

46 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 6

ISO 8583 Message Interface Engine

The ISO 8583 Message Interface Engine is an interface engine designed to aid in
the assembly and disassembly of data packets conforming to the ISO 8583
standard. The engine is beneficial for the application programmer by providing a
single routine to complete both assembly and disassembly.
The engine allows for the handling of computed fields, such as the MAC, whose
value is based on the preceding bytes in the ISO packet. Verix eVo ACT includes
two additional modules that rely on the ISO 8583 Message Interface Engine, the
ISO 8583 Protocol Engine, and the PIP Engine.
The PIP Engine is a specific ISO 8583 implementation using PIP. The ISO 8583
Protocol Engine assists the PIP Engine in building, sending, receiving, and
unpacking an ISO 8583 message. Other ISO 8583 applications can also use the
ISO 8583 Message Interface Engine and the ISO 8583 Protocol Engine.
Figure 3 illustrates how the ISO 8583 Message Interface Engine interfaces to the
ISO 8583 Protocol Engine.

NOTE
This engine can only be used with Verix eVo ACT, (VPN P006-212-02), for Verix
eVo terminals.

Fi gu re 3 ISO 8583 Mes sag e Int er fac e

VERIX EVO ACT PROGRAMMERS GUIDE 47

ISO 8583 MESSAGE I NTERFACE E NGINE

IS O 85 83 En gine Ov er vi ew

ISO 8583 Services of the financial industry include the exchange of electronic messages
Engine relating to financial transactions. The ISO 8583 international standard specifies a
Overview common interface by which bankcard-originated messages relating to financial
transactions can be exchanged between private systems. The standard has
nothing to do actual transmittance and receipt of data, but concentrates on the
construction of the data packets.

ISO 8583 Bitm aps The ISO 8583 standard identifies 126 possible fields that can be included in a
data packet. For each data packet, various combinations of these data fields are
included depending on the type of request or response represented by the data
packet. Each of these data fields is represented by a single bit in one of two
bitmap elements in the data packet.
The first bitmap field is always included in the data packet. The first bit is used to
indicate whether the second bitmap field exists. The ISO 8583 standard arranges
the various data fields so that the most common data packets can be formed
using only the first bitmap field, which reduces transmission size.
Each of the remaining 63 bits represents a particular data field as described in the
ISO 8583 standard. The application programmer must review the host interface
specification to ensure the correct fields are included for each message type. For
every data field included in the data packet, the corresponding bit in the bitmap is
set to one. Any unused fields must set their corresponding bit to zero. The bitmap
is completed as the data packet is assembled, and is used at the destination to
disassemble the data.
Figure 4 represents a partial first bitmap field.
Bitmap = i

Figur e 4 Par ti al Fir st Bit map Field

Message Stru ctur e Each ISO 8583 message is constructed in the following sequence:
1 Message type identifier

2 One or more bit maps

3 A series of data elements in the order of bitmap representation

48 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

ISO 85 83 En gi ne De si gn

The message identifier is a four-digit numeric field used to describe each

message class and function. Digits one and two identify the class of message,
while digits three and four represent the message function or the transmission
mode when digits one and two range between 01 and 08. For example:
Identifier = 0100
Message class is 01, authorization message
Message mode is 00, transaction processed, interactive
The second message component is one or more bitmap(s), as previously
described.
The third message component and its data content is made up of a series of data
elements. Data elements can be of fixed or variable length. The actual length of
any variable-length-data element is provided in its fixed-length prefix. Note that
the message structure does not preclude the use of additional data elements in a
message as required for national interchange or private use. Some fields are
reserved for private and other uses. If necessary, additional bitmaps can be
included and the appropriate data fields defined. Additional field definitions require
mutual agreement by the parties involved.
Applications developed for systems using the ISO 8583 international standard
must format all messages accordingly. The construction of each message is a
tedious job, and most programmers do not really want to know how the messages
are constructed. Most programmers like to manipulate data in a form that is
convenient for their requirements, not in a foreign form required by the interface.
This implies that the data resides in a subset of the application variables and
stored in formats selected by the programmer.

ISO 8583 This engine is designed to be table driven. A single routine is used for the
Engine Desig n assembly and disassembly of ISO 8583 packets. The assembly and disassembly
of ISO 8583 packets is driven by the following structures:

Maps One or more collections of 64 bits that drive packet assembly and
indicate what is in a message.

Field table Defines all the fields used by the application.

Convert table Defines data-conversion routines.

Variant tables Optional tables used to define variant fields.

The process_8583() routine is used for the assembly and disassembly of ISO

8583 packets.

Engine The ISO 8583 Interface Engine is divided into two major parts:
Components • A set of map manipulation and data conversion routines, and
• A set of routines to handle packet assembly and disassembly.

VERIX EVO ACT PROGRAMMERS GUIDE 49

ISO 8583 MESSAGE I NTERFACE E NGINE

En gi ne File s

Engine Files The ISO 8583 Message Interface Engine consists of the following files:

Engine ISO8583.H Function headers and #def i ne preprocessors for the

Header File bitmap manipulation and data conversion routines.
Contains the primary data structures, required global
variables, and function headers for the primary
interface routine.
Sample APPL8583.C File to be modified by the application programmer to
Ap pl ic ati on include the variables used to interface to the assembly
Files and disassembly routines. Contains the field tables,
variant field tables (if any), and the two required integer
functions for processing variant fields. This file is listed
at the end of this manual section.
APPL8583.H Companion header file for APPL8583. C.

Incorporating To incorporate this engine into an application, modify the APPL8583. C and
the Engine APPL8583. H files so that each has all the application variables required in the bit
map and set up the map properly. Compile APPL8583. C and link it with your
application and the ISO 8583 library.
Use the following procedures to transmit or receive an ISO 8583 packet using the
ISO 8583 Interface Engine:

To transmi t an ISO 1 Set data values in the application variables for those to transmit.
8583 pack et
2 Call the prot8583_main() routine.

This constructs the complete message and returns the number of bytes in
the constructed message.
3 Call wr i t e( ) to transmit the message.

To receive a 1 Call r ead( ) to receive the message.

message
2 Call the process_8583() routine.

This results in all fields being deposited into the application variables.
3 Use the values in the application variables.

NOTE The routines provided by this engine simplify the handling of bitmapped
messages. The determination of which message type to send and which fields to
include in that message is the responsibility of the application programmer.
Similarly, validation of a host response and the fields it provides is the
responsibility of the application.

50 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

Global Data and Definitions

Fi gu re 5 Tr an sac ti on Pr oc es si ng Fl owc har t

Glob al Data
and Definitio ns

Global Defines The following #def i ne preprocessors are used by the 8583 Interface Engine and
can be found in I SO8583. H:
#def i ne BI T_MAP_SI ZE 8
#def i ne map_bytes( f n) ( ( ( ( ( f n) - 1) ( BI T_MAP_SI ZE* 8) ) /
+1) * BI T_MAP_SI ZE)
#def i ne bi t _map( name, f n) unsi gned char name[ map_byt es/
(fn)]
#def i ne STOP 0x8000
#def i ne SKI P 0x4000
#def i ne FI ELD_MASK 0x0f f f
#def i ne OFF 0x4000
#def i ne LEGAL_FI ELD( map, f n) ( ( f n) >= 1) &&( ( f n) <= ( map_s i ze( map) *
BI T_MAP_SI ZE) ) )
#def i ne LS_MAP_BI T 0x80
#def i ne ASC_ASC 0
#def i ne AV3_AV3 1
#def i ne BI T_BI T 2
#def i ne BCD_BCD 3
#def i ne BCD_ASC 4

VERIX EVO ACT PROGRAMMERS GUIDE 51

ISO 8583 MESSAGE I NTERFACE E NGINE

Global Data and Definitions

#def i ne ASC_STR 5
#def i ne BCD_STR 6
#def i ne BCD_SNZ 7
#def i ne AV2_STR 8
#def i ne BV2_STR 9
#def i ne AV3_STR 10
#def i ne XBC_STR 11
#def i ne BI N_HST 12
#def i ne BI 2_HST 13
#def i ne BI 3_HST 14

Global Variables The following global variable can be found in LI B8583. C:

unsi gned char pad_ni bbl e_8583 = 0;

The following global variables are used by the 8583 Interface Engine and can be
found in I SO8583. H:
conver t er s conver t _t abl e[ ] ;
unsi gned char *s r c_8583;
unsi gned char *dst _8583;
i nt f n_8583;
unsi gned char map_8583 [ ] ;

Global Structures The following global structures are used by the Interface Engine and can be found
in I SO8583. H:
t ypedef st r uct
{
i nt f i el d_num; / * 1st col - f i el d number */
i nt packet _sz; / * 2nd col - packet si ze */
i nt conver t _i dx;
/ * 3r d col - i ndex i nt o cover t t abl e */
voi d *r ef erence;
/ * 4t h c ol - poi nt er t o var i abl e or t abl e * /
i nt v ar _ s z ; / * 5t h c ol - var i abl e s i z e * /
} f i el d_ st r uc t ;
t ypedef st r uct
{
unsi gned i nt var i ant 1; / * 1st col - t ar get */
unsi gned i nt var i ant 2; / * 2nd col - t ar get */
i nt packet _sz; / * 3nd col - packet si ze */
i nt conver t _i dx; / * 4r d col - i ndex i nt o cover t t abl e */
voi d *r ef erence;
/ * 5t h c ol - poi nt er t o var i abl e or t abl e */
i nt v ar _ s z; / * 6t h c ol - var i abl e s i z e * /
} var i ant _st r uct;

t ypedef voi d ( * ( c onver t er s [ 2] ) ) ( ) ;

52 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

Typical Host/Terminal Packet Structure

Typi cal Host / The structure of a terminal/host message is:

Terminal
Packet
Structure

where,
• ADR: is the HDLC (SDLC) poll address (normally 0x30).
• CB: is the HDLC control byte.
• TPDU: is the Transport Protocol Data Unit (see below).
• CRC: is the HDLC checksum (CCITT CRC).
The structure of the request message TPDU is:

where,
• TPDU ID: identifies TPDU type:
• 0x60 = Transactions
• 0x68 = NMS/TNMS
• DESTINATION ADDRESS: is the network international identifier
• ORIGINATOR ADDRESS–Identifies the individual terminal or process
originating the transaction.
The structure of the response message TPDU is:

where,
• TPDU ID: Identifies the TPDU type. This is the same value as in the request
message.
• DESTINATION ADDRESS: This is the same as the originator address from
the request message.
• ORIGINATOR ADDRESS: This is the same as the destination address from
the request message.
The structure of APPLICATION DATA is:

VERIX EVO ACT PROGRAMMERS GUIDE 53

ISO 8583 MESSAGE I NTERFACE E NGINE

Ap plic at ion De sign

where,
• MESSAGE TYPE: is four BCD digits
• BIT MAP: 64 or 128 bits numbered from the left, starting with 1.
• DATA: The following rules apply:
• All data elements begin on a byte boundary.
• Fixed-length, n-type fields with an odd length are right-justified to a byte
boundary, and zero-filled on the left.
• All lengths for variable-length fields are represented in BCD, right-justified
to a byte boundary, and zero-filled on the left.
• The length indicator for a variable-length field is a count of data elements
to follow. It does not include itself in the count.
• Variable-length, n-fields with an odd length are left-justified within a field
and zero-filled.

Applicat ion When designing an application that uses the ISO 8583 Interface Engine, the
Design programmer must understand how to construct maps and field tables. The
following sections describe these two topics in detail.

Map Construc tion A map is one or more 64-bit collections used to define which fields to include in an
outgoing packet and to indicate which fields are present in an incoming packet.
There is a direct correspondence between the bits in the map and the order of the
data fields in the packet. The first bit that is on in the map (moving from bit 1 to
128) defines the number of the first data field. Bits 1 to 64 constitute the primary
bit map, while bits 65 to 128 make up the optional secondary bit map. Bit number
1 indicates the presence of the secondary bit map, with bit 65 indicating the
presence of a tertiary map. The current ISO 8583 standard only defines fields up
to 128, and hence it uses only two maps.
The application programmer typically creates a map for each packet which the
application is required to send. These maps may be handled in any one of the
following ways:
• Create a table of maps used by the application then refer to a particular map
with an index into this table.
• Use individually named maps.
• Create each map on the fly just before packet assembly.
• Use a mixture of the above methods.
The ISO 8583 Engine handles maps with up to 256 bits.

Map Manipulatio n In most cases, maps are created once for each particular message type and then
Routines used without change. Occasionally however, it can be necessary to manipulate
these maps. To assist in this process, the ISO 8583 Interface Engine provides the
following map manipulation functions:

54 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

Field Table Construction

• map_clear()
• map_test()
• map_set()
• map_reset()
• map_man()

Field Table Use the field table to define all fields required by the application and transmitted
Construction by the host. There are as many rows in the field table as there are unique fields.
Each row in the table has the following five fields:

Field Num The number of the field. Corresponds to the bit set in the bitmaps.

The number of units called for by the 8583 packet. These units could
8583 Size
be single bits, 4-bit BCD digits, or 8-bit bytes.
Convert An index into the Convert table, as explained in Variant Field Strategy.
Index
A pointer to the actual variable or place where the data resides within
Ap pl ic ati on
the application. May also point to a second table, as is the case for
Variable
variant fields.
Variable Number of units called for by variable.
Size

The header file, I SO8583. H, defines the following structure which is used for the
field table:
t ypedef st r uct {
i nt f i el d_num;
/ * 1st col - f i el d number */
i nt packet _sz;
/ * 2nd col - packet si ze */
i nt c onver t _ i dx;
/ * 3r d col - i ndex i nt o conver t t abl e */
voi d *r ef er ence;
/ * 4t h c ol - poi nt er t o var i abl e or t abl e * /
i nt var _ s z ;
/ * 5t h c ol - var i abl e s i z e * /
}
f i el d_ st r uct ;

The following #def i ne preprocessors are provided in APPL8583.H:

#def i ne VARI ABLE( name)
( voi d *) name, si zeof ( name)
#def i ne TABLE( name)
( voi d *) name, 0
#def i ne FUNCTI ON( name)
( voi d*) name, 0

VERIX EVO ACT PROGRAMMERS GUIDE 55

ISO 8583 MESSAGE I NTERFACE E NGINE

Field Table Construction

If the application specified data length (8583 packet_sz) is less than the actual
data length, then it will fail returning an error (-4).
Correct the value of 8583 packet_sz to reflect the maximum length of the data
field and inspect 8583 packet_sz field while using the following conversions:
AV2_STR, BV2_STR, AV3_STR, HST_BI 2, HST_BI 3, STR_AV2, STR_BV2, STR_AV3,
BI 2_HST, BI 3_HST, and AV3_AV3
The following is an example of the field table:
f i el d_ s t r uc t f i el d_ t abl e [ ] =
{
/ * Fl d 8583 Conver t Var i abl e name and si ze */
/ * no. sz i ndex */
{ 0, 10, BCD_STR, VARI ABLE( t pdu) },
{ 0, 4, BCD_STR, VARI ABLE( message_i d) },
{ 2, 19, BV2_STR, VARI ABLE( pr i _acct _num) },
{ 3, 6, BCD_STR, VARI ABLE( proc_ code) },
{ 4, 12, BCD_SNZ, VARI ABLE( amount ) },
{ 11, 6, BCD_STR, VARI ABLE( sys_t r ace) },
.
.
.
{ 32, 11, BV2_STR, VARI ABLE( acq_i ns_i d) },
{ 35+ SKI P, 37, AV2_STR, VARI ABLE( di scar d) },
{ 37, 12, ASC_ASC, VARI ABLE( r et r _r ef _num) },
.
.
{ 43, 40, ASC_STR, VARI ABLE( car d_acc_ name) },
{ 44, 0, COMPUTE, FUNCTI ON( bui l d_44) },
{ 60+ STOP, 0, VARI ANT, TABLE( f i el d_60) },
};
This field table must define all fields that the host will send, including those not
used by the application. This is necessary to allow the engine to skip them.
However, to skip a field, the engine must know how long that field is. See field 35
in the example above.
Packets are assembled and disassembled from left to right, that is, from low field
number to high field number. During packet assembly, an index is used to
reference entries in the field table. This index increments to the next field called for
by the driving bitmap.
Use the following steps to construct the field table:
1 Create column one for each field used by the application or transmitted by the
host.
2 Fill in the values for the second column taken from your host interface
document.

56 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

Field Table Construction

Use the field sizes specified by the particular host with which the application
is communicating.
3 Make a list of the types of fields required by the ISO 8583 packets from the
host interface document.

Here is the start of the list:

BCD Binary coded decimal. Length given by packet size column.

BV2 BCD preceded by 2-digit length.

AV3 ASCII string preceded by a 3-digit length.

These are the symbolic names used for the first part of the entries in the
third column (the names to the left of the underscore). See the header file
ISO8583.H for a complete list of all supported data types.

4 Decide on the format the application will store and manipulate the data for
each field.
Give each of these types a descriptive name, as described in step 3. Use the
same name if the forms are the same. These are the symbolic names used
for the second part of the entries in the third column (the names to the right of
the underscore). There are also two special #def i nes , COMPUTE and
VARIANT, to use with computed or variant fields. Use one of the following
three defines for the fourth column: VARIABLE, TABLE, or FUNCTION:
• VARIABLE: if the data is stored in a simple program variable.
• TABLE: specifies variant fields.
• FUNCTION: specifies computed fields.
See Variant Fields and Computed Fields.

Variant Fields The 8583 specification defines fields 60–63 as private fields. This means that
these fields can be used by the application in any way. Following are several
possibilities for the usage of these fields:
• Always use them the same way to store the same type of data. If this is done,
these private fields be used as if they were defined fields and are no more
difficult to handle than any other field.
• Let their usage and contents to vary depending of the type of message. Since
there are only four of these fields andsince a lot of data simply does not fit into
the other defined fields, most applications are forced to think of these private
fields as variant fields. Accordingly, the ISO 8583 Interface Engine provides a
mechanism to manipulate variant fields. Note that this mechanism can be
ignored or modified by the programmer— this is only one method and works in
most cases.For completeness, two other schemes are provided that could be
used to handle variant fields.
• Define special conversion routines that use other application variables to
determine exactly what they should do.
VERIX EVO ACT PROGRAMMERS GUIDE 57

ISO 8583 MESSAGE I NTERFACE E NGINE

Field Table Construction

• Always move the field onto a C structure that uses a union to offer different
views of the data.

Variant Field Str ategy

Refer the previous field table example and note the following for field 60:
{ 60+ STOP, 0, VARI ANT, TABLE( f i el d_60) },

Column three normally has an index into the convert table. The define VARIANT is
a special value defined to be one greater than the last valid index into the convert
table. If this value is used it simply tells the engine “the contents of this field
depend on the two additional integers”. These two integers can be the first two
digits of the processing code and the message type. Accordingly, the pointer in
the fourth column, instead of pointing at an application variable points at a table of
the following form:
var i ant _st r uct f i el d_60[ ] =
{
/ * Vari ant 1, Vari ant 2 8583 Si ze Conver t i ndex, var i abl e name and si ze
*/
{ 00, 0x0220, 12, BCD_STR, VARI ABLE( or i g_amount ) },
{ 02, 0x0220, 12, BCD_STR, VARI ABLE( or i g_amount ) },
{ 90, 0x0810, 6, BCD_STR, VARI ABLE( bat ch_num) },
{ 92+ STOP, 0x0500, 6, BCD_STR, VARI ABLE( bat ch_ num)
},
};

The format of a variant field table is simply that of the basic field table with two
new columns added to the left. When the interface engine encounters a variant
field, it moves to the variant field table and then sequentially searches for a row
where the integers specified by the first two columns match two integers provided
by the application.
If a match is not found, the engine aborts the assembly or disassembly and
returns an error code. Due to the sequential search, the variant field tables must
be ordered with the most-common definition first and the least common last.
Exactly what these two integers represent is up to the application, as they are
provided by two functions found in the file APPL8583.C. The above table uses the
first two digits of the processing code and the message . Accordingly, these two
functions are:
unsi gned i nt r et ur n_var i ant 1( )
{
unsi gned char x [ 3] ;
/ * Most si gni f i cant 2 di gi t s of pr oc_code */
st r ncpy( x, pr oc_code, 2) ;
r e t ur n at oi ( x) ;
}
unsi gned i nt r et ur n_var i ant 2( )

58 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

Computed Fields

{
r et ur n at oi ( message_i d) ;
}

When the match is found, the interface engine proceeds to use the other columns
of the table just as with non-variant fields.

Computed A computed field is one whose value depends on either the partially assembled
Fields ISO 8583 packet or some other real time data. In other words, the value of the
field prior to calling the process_8583() routine to build the packet cannot be
determined. Such an example would be a MAC. The value of this field is
determined using the assembled ISO 8583 packet. The interface engine caters to
these types of fields by providing a mechanism whereby during assembly a call
will be made to a routine written by the user that will be responsible for providing
the value of the fields. This user-written routine should be included in
APPL8583. C and must be of the form:
/ *******************************************************/
/ * Exampl e of a comput ed f i el d. */
/ * Such a r out i ne must have f our par amet er s. */
/ * how - how= 0 = pack; how= 1 = unpack * /
/ * buf f er - Poi nt er t o wor ki ng buf f er . Copy of val ue
/* passed t o t he mai n pr ocess_8583 dr i ver . */
/ * psz - Number of uni t s i n packet . Must be set by */
/* t hi s r out i ne. * /
/ * vsz - Number of byt es i n var i abl e. Must be set by
/* t hi s r out i ne. * /
/ *****************************************************/
i nt comput e_f i el d ( how, buf f er , psz, vsz)
i nt how; unsi gned char *buf f er;
i nt * ps z; i nt * v sz ;
{
*psz = 19 / *val ue f r om second col umn of f i el d t abl e */
* vs z = s i z eof ( f i el d_ 02) ; / * s i z e of dat a i n appl i c at i on var i abl e * /
i f ( how == 0) / * We ar e bui l di ng a packet */
sr c_8583 = ( unsi gned char *) f i el d_02; / * Poi nt er t o
sour ce dat a */
el se
dst _8583 = ( unsi gned char *) f i el d_02;
/ * Poi nt er t o dest i nat i on dat a */
return
}
If a computed field is encountered while the interface engine is building a packet,
it will first call a user-written routine of the form shown above. This initializes the
data value, establishes the construction pointers, sets the sizes, and ultimately
returns the conversion type. The mechanism then has all the data as if it were
presented explicitly in the field table. The value will then be properly formatted into
the packet and the construction process will continue.

VERIX EVO ACT PROGRAMMERS GUIDE 59

ISO 8583 MESSAGE I NTERFACE E NGINE

Convert Table

Conv ert Table The convert table contains pairs of pointers that point to simple routines used to
convert the data between the form required by the ISO 8583 packet and the
application. For example, it may be most natural for the C application to store the
expiration date as a null-terminated string. The packet, however, requires that it
be stored as four BCD digits. Therefore, two conversion routines are required:
One to change a null-terminated string to packed BCD, and one to do the reverse.
Scan column three of the field table to determine which conversion routines are
required. Each conversion results in a pair of routines: one named A_to_B() and
the other B_to_A(). The convert table contains as many rows as there are unique
conversion pairs. For example:

As sembl y Disass embly Descri pt ion

str_to_bcd() bcd_to_str() ASCII, null-terminated, to BCD
asc_to_bcd() bcd_to_asc() ASCII, count from field table, to BCD

A #def i ne is created for each row in the convert table, which is then used in
column 3 of the field table. For example:
#def i ne BCD_STR 1 / * t hi s t ype of def i ne */
/ * f ound i n I SO8583. H */
#def i ne BCD_ASC 2 / * t hi s t ype of def i ne */
/ * f ound i n I SO8583. H */

The convert table is created using the following type declaration:

t ypedef voi d ( * ( c onver t er s [ 2] ) ) ( ) ;
/ * a pai r or poi nt er s * /
/ * t o f u nc t i ons * /

The ISO8583.H file contains the #def i nes for conversion types, and the ISO
8583 library contains the routines that perform the following conversions:
Tab le 5 ISO 8583 L ib rar y Co nv er si on Ro ut in es
Convert
Description
Index
0 Fixed-size ASCII to same.
1 3-digit ASCII counted to same.
2 Fixed-size bits to same.
3 Fixed-size BCD to same.
4 Fixed-size BCD to ASCII with same number of digits.
5 Fixed-size ASCII to null-terminated string.
6 Fixed-size BCD to null-terminated string.
7 Fixed-size BCD to null-terminated string (drop lead zeros).
8 2-digit ASCII counted to null-terminated string.
9 2-digit BCD counted to null-terminated string.
10 3-digit ASCII counted to null-terminated string.
11 Fixed-size “signed” (C/D) BCD to null-terminated string.
12 Fixed-size binary to ASCII hex.

60 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

Convert Table

Tab le 5 ISO 8583 L ib rar y Co nv er si on Ro ut in es (continued)

Convert
Description
Index
13 2-digit counted binary to null-terminated ASCII hex string.
14 3-digit counted binary to null-terminated ASCII hex string.

The convert indices in ISO8583.H are as follows:

#def i ne ASC_ASC 0
#def i ne AV3_AV3 1
#def i ne BI T_BI T 2
#def i ne BCD_BCD 3
#def i ne BCD_ASC 4
#def i ne ASC_STR 5
#def i ne BCD_STR 6
#def i ne BCD_SNZ 7
#def i ne AV2_STR 8
#def i ne BV2_STR 9
#def i ne AV3_STR 10
#def i ne XBC_STR 11
#def i ne BI N_HST 12
#def i ne BI 2_HST 13
#def i ne BI 3_HST 14

The convert table itself is actually created with an initialized variable in

APPL8583.C:
conver t ers conver t _t abl e [] = {
{ asc_t o_asc, asc_t o_asc },
{ av3_t o_av3, av3_t o_av3 },
{ bi t _ t o_ bi t , bi t _ t o_ bi t },

{ bcd_t o_bcd, bcd_t o_bcd },

{ asc_t o_bcd, bcd_t o_asc },
{ s t r _ t o_ as c, as c_ t o_ s t r },
{ st r _t o_bcd, bcd_t o_st r },
{ snz_t o_bcd, bcd_t o_snz },
{ st r _t o_av2, av2_t o_st r },
{ st r _t o_bv2, bv2_t o_st r },
{ st r _t o_av3, av3_t o_st r },
{ st r _t o_xbc, xbc_to_str },
{ hst _t o_bi n, bi n_t o_hst },
{ hst _t o_bi 2, bi 2_t o_hst },
{ hst _t o_bi 3, bi 3_t o_hst }
};

The following convert indices are defined in ISO8583.H:

#def i ne VARI ANT - 1

VERIX EVO ACT PROGRAMMERS GUIDE 61

ISO 8583 MESSAGE I NTERFACE E NGINE

Convert Table

#def i ne COMPUTE ( VARI ANT- 1)

These indices identify the variant and computed fields.

Each conversion routine is called with a single integer parameter, obtained from
column two of the field table. In addition, each routine must advance the following
two global character pointers:
sr c_8583 Points at the source data. On an incoming packet, this points at the packet.
On an outgoing packet, this is set to the value in the fourth field of the field
table.
dst _8583 Points at the destination data with reverse orientation from src_8583.

In addition, the following global variables are available to the conversion routine
and can be used as necessary:
f n_8583 Current field number being worked on.
map_8583 Copy of current working map.

As an example of one of these conversion routines, the following converts a

packed BCD string of cnt digits into a null-terminated string of ASCII digits:
voi d bcd_t o_st r ( cnt )
i nt c nt ;
{
bcd_t o_asc( cnt ) ;
*dst _8583++ = 0;
}
voi d bcd_t o_asc( cnt ) i nt cnt ; {

whi l e ( cnt > 0)

{
*dst _8583++ = get _bcd_t o_asc( cnt - - & 1 ?
*sr c_ 8583++ :
*s r c_ 8583>> 4) ;
}
} st at i c unsi gned char get _bcd_t o_asc( bcd) unsi gned char bcd;
{
r et ur n ( bc d & 0xf ) + ’ 0’ ;
}

Conversion The following routines are included in Verix eVo ACT to perform all data
Routines conversions required to format ISO 8583 packets. Refer to ISO 8583 Message
Interface Engine Function Calls for details about these routines.
• asc_to_asc() copies n bytes from source to destination. It then advances the
global pointers dst_8583 and src_8583 by n.

62 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

Convert Table

• av3_to_av3() copies a 2-byte counted string from source to destination. The

2-byte count is in BCD format. If the value of count bytes exceeds n, no move
is performed and the operation is terminated.
• bit_to_bit() copies n bits from the source to destination, always in whole bytes.
• bcd_to_bcd() moves n BCD nibbles from source to destination.
• asc_to_bcd() converts n ASCII digits to packed BCD and stores them in the
destination.
• bcd_to_asc() expands n nibbles of packed BCD into ASCII equivalents. It
assumes all the BCD digits are in the range 0–9.
• str_to_asc() converts a null-terminated ASCII string to fixed-size (n) ASCII.
The resulting string is padded with spaces or truncated, as necessary, to n
bytes.
• asc_to_str() moves n characters from source to destination then appends a
null in the destination.
• str_to_bcd() converts a null-terminated ASCII string to fixed-size (n) BCD
nibbles with zero padding on the left.
• bcd_to_str() copies n BCD digits from the source to destination, then appends
a null character in the destination. Leading zeros in the source are preserved.
• bcd_to_snz() copies n nibbles of BCD to a null-terminated ASCII string.
Leading zeros are removed, but are included in the conversion count.
• str_to_av2() converts a null-terminated ASCII string to a 1-byte counted string.
The count is in BCD form. If the size of the ASCII string exceeds n bytes, no
move occurs and the operation terminates.
• av2_to_str() converts a 1-byte counted string into a null-terminated ASCII
string and stores the result in the destination. The count is in BCD form. If the
value of count byte exceeds n, no move occurs and the operation terminates.
• str_to_bv2() converts a null-terminated ASCII string (contains digits only) to a
1-byte counted BCD string. The count is in BCD form. If the size of the ASCII
string exceeds n bytes, no move occurs and the operation terminates.
• bv2_to_str() converts a 1-byte counted BCD string to a null-terminated ASCII
string. If the value of count byte exceeds n, no move occurs and the operation
terminates.
• str_to_av3() converts a null-terminated ASCII string to a 2-byte counted string.
The count is in BCD form. If the size of the ASCII string exceeds n bytes, no
move occurs and the operation terminates.
• av3_to_str() converts a 2-byte counted ASCII string to a null-terminated ASCII
string. The byte count is in BCD form. If the value of count byte exceeds n, no
move occurs and the operation terminates.
• str_to_xbc() converts a null-terminated ASCII string to a BCD string while
preserving the first byte of the source (C = Credit, D = Debit).

VERIX EVO ACT PROGRAMMERS GUIDE 63

ISO 8583 MESSAGE I NTERFACE E NGINE

Convert Table

• bcd_to_str() converts n bytes of a BCD string to a null-terminated ASCII string,

preserving leading zeros.
• hst_to_bin() converts n bytes of ASCII hex digits to binary and stores them in
the destination.
• bin_to_hst() converts n bytes of binary into 2n bytes of ASCII hex digits.
• hst_to_bi2() converts a null-terminated ASCII hex string to a 1-byte counted
binary and stores it in the destination. The count is in BCD format and is only
half the length of the ASCII hex string. If the size of the ASCII string exceedsn
bytes, no move occurs and the operation terminates.
• bi2_to_hst() converts a 1-byte counted string of binary to a null-terminated
ASCII hex string. If the value of count byte exceeds n, no move occurs and the
operation is terminates.
• hst_to_bi3() converts a null-terminated ASCII hex string to a 2-byte counted
binary and stores it in the destination. The count is in BCD format and is only
half the length of the ASCII hex string. If the size of the ASCII hex string
exceeds n bytes, no move occurs and the operation terminates.
• bi3_to_hst() converts a 2-byte counted string of binary to a null-terminated
ASCII hex string. If the value of count bytes exceeds n, no move occurs and
the operation is terminates.

Packet Assembly The routine used for the assembly and disassembly of ISO 8583 packets is
and Disassembl y process_8583(). It accepts five parameters from the caller. These parameters are
as follows:
• how: An integer type that determines if the function should assemble or
disassemble a packet. 0 indicates assembly; a 1 indicates disassembly.
• f i el d_ t bl : A pointer to a struct field_struct that is the field table.
• map: An unsigned char pointer that points to the map defining the packet being
processed. This parameter is ignored when disassembling an incoming
packet.
• buf f er : An unsigned char pointer that points to a buffer area used in both
assembling and disassembling a packet.
• l i mi t : An integer type that denotes the maximum size for the packet being
processed.
The function prototype is as follows:
i nt pr ocess_8583( how, f i el d, map, buf f er , l i mi t )
i nt how;
f i el d_ st r uct * f i el d_ t bl ;
unsi gned char *map;
unsi gned char *buf f er ;
i nt l i mi t ;

64 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 MESSAGE I NTERFACE E NGINE

IS O 85 83 Me ssa ge In te rf ac e Func ti on s

This function processes assembly or disassembly of a packet by checking the bits

in the map. The return values for this integer function are as follows:

Success: >= 0: Assembly: Number of bytes placed into the buffer. Use for writes.
Disassembly: Number of bytes in the buffer not yet processed. Should be
zero.

Failure: -1: Field not defined in the field table. The variable fn_8583 contains the
field in error.

-2: Exceeded the destination buffer limit while packing.

-3: Exceeded the source buffer limit while unpacking.

-4: Variable-length field conversion exceeded limit parameter.

-5: No matching variant field definition.

The following global variables are used in this function and are defined in the
ISO8583.H header file:
ext er n unsi gned char * sr c_8583; / * Sour ce poi nt er * /
ext er n unsi gned char *dst _8583; / * Desti nati on poi nt er */
ext er n i nt f n_8583; / * Fi el d number */
ext er n unsi gned char map_8583[ ] ; / * Map */

ISO 8583 The ISO 8583 message interface functions are described in ISO 8583 Message
Message Interface Engine Function Calls.
Interface
Functions

VERIX EVO ACT PROGRAMMERS GUIDE 65

ISO 8583 MESSAGE I NTERFACE E NGINE

IS O 85 83 Me ssage In te rfac e Func ti on s

66 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 7

ISO 8583 Proto col Engin e

The ISO 8583 Protocol Engine builds and sends ISO 8583 packets to a host. To
accomplish this, it interfaces with the ISO 8583 Message Engine. The ISO 8583
Protocol Engine adheres to all requirements in the ISO 8583 standard.
The ISO 8583 Protocol Engine interfaces to the programmer defined validation
function used to determine if an appropriate response was received. This engine
interfaces to the programmer-defined communication function used to transmit
and receive request and response messages. It processes reversals as specified
in the ISO 8583 standard.
The PIP Engine requires the ISO 8583 Protocol Engine, but the ISO 8583
Protocol Engine does not require the PIP Engine. It does, however, require the
ISO 8583 Message Engine.
Although this engine was written to support the PIP Engine and the ISO 8583
process, it could be used to interface to any engine that uses ISO 8583 packets
for processing. This section treats the ISO 8583 Protocol Engine as a generic
module. See PIP Engine for specific implementation of the ISO 8583 Protocol
Engine
This engine can only be used with Verix eVo ACT, (VPN P006-212-02), for Verix
eVo based terminals.

ISO 8583 The ISO 8583 Protocol Engine requires a data structure to provide information
Protocol and application data variables. By using a structure to contain this information, the
Engin e Data interface to the ISO 8583 Protocol Engine is simplified. The protocol 8583 data
Structure structure is defined in the PROT8583.H header file.

Prototype t ypedef st r uct c8583dat

{
f i el d_ s t r uc t * p_ f l d_ t abl e;
i nt *comm_handl e;
unsi gned comm_t i meout ;
unsi gned wai t _f or _car r i er ;
unsi gned char *map;
i nt ( * v al i dat i on) ( v oi d * , i nt ) ;
voi d *v_ par ms;
unsi gned v_par ms_ si ze;
i nt ( * tr anscei ver ) ( i nt , i nt , unsi gned char *, unsi gned,
unsi gned char *, unsi gned, unsi gned, unsi gned) ;

VERIX EVO ACT PROGRAMMERS GUIDE 67

ISO 8583 PROTOCOL E NGINE

IS O 85 83 Proto co l En gi ne Da ta Str uc tu re

unsi gned char * t r ansmi t ;

unsi gned i nt t r ansmi t _si ze;
unsi gned tr ansmi t _l i mi t ;
unsi gned char * r ecei ve;
unsi gned r ecei ve_si ze;
unsi gned r ecei ve_l i mi t ;
unsi gned char *r ever sal ;
unsi gned r ever sal _si ze;
unsi gned r ever sal _l i mi t ;
unsi gned char *base_name;
unsi gned char r ev_msg_i d[ 5] ;
i nt s t at e;
} COMM_8583_ DATA;

Parameters
p_ f l d_ t a bl e The ISO 8583 Protocol Engine calls the ISO 8583 Message
Engine to assemble and disassemble messages for each
transaction. The p_ f l d_ t a bl e member is a pointer to the
applications field table that contains all the required information.
comm_handl e A pointer to the communications device. This handle is passed to
the communications routine as required.
comm_t i meout A time-out value specifying the length of time to wait for a
response from the host. This parameter is passed to the
communications routine as required.
wai t _ f or _ c ar r i er A time-out value passed to the communications routine to
specify the period of time to wait if the carrier is not present. In
applications where the call to the host is initiated early in the
transaction, the carrier may already be present when the
message is available for transmission. In other cases, it is
necessary for the communications routine to wait for carrier to
indicate the connection to the host is complete.
map A pointer to the completed bitmap for the transaction. This
bitmap can be constructed by the application in various ways or
at various times, including as a file.
val i dat i on A function pointer called after receiving a response to a request
message. The function should return a 0 if the response is valid,
or -1 to -14 if the validation routine fails. Any positive return value
is taken as a request to wait for a new response packet. The
return value is, therefore, the number of seconds to wait for the
next response. The #def i ne RETRY_CURRENT_TIMEOUT
may be returned to request a new response packet using the
current time-out value.
Two parameters are passed to this function: a pointer to the
validation structure, and the result of an internal validation of the
TPDU and response message ID by the Protocol 8583 Engine
(refer to check_8583_tpdu_msg_id() for a list of valid values for
this parameter).

68 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 PROTOCOL E NGINE

ISO 85 83 Proto co l En gine Da ta Str uc tu re

v_ par ms A pointer to the application validation structure, v_par ms_ si ze

v_par ms_s i ze specifies the size of that structure. By using a structure to
contain the validation parameters, parsing is reduced and
comparisons are easier.
For AMEX transactions, the response message is validated by
comparing the amount, systems trace number, and terminal ID to
the request message. During disassembly, some application
variables are overwritten (such as, the transaction amount) by
the field information in the response.

Note: To preserve this information, the validation structure is

created to hold the values needed to validate the
response.

v_par ms_ si ze builds the reversal and advice files, and is

widely used throughout the ISO 8583 Protocols Engine.
v_par ms_ si ze must be set to include the RRN field. It uses the
space to manage the RRN under time-out conditions.
t r anscei ver A function pointer used as the entry point to the communications
routine. This routine is called to send or receive any messages.
t r ansmi t These three parameters define the buffer used to contain out-
t r ansmi t _si ze going messages. The buffer must be large enough to contain the
t r ansmi t _l i mi t largest transmit message and the size of the validation structure.
t r ansmi t _si ze is the size of the message to send.
t r ansmi t _l i mi t is the maximum size of the buffer.
r ecei ve These three parameters define the buffer used to contain in-
r ecei ve_si ze bound messages. The buffer must be large enough to contain
r ec ei ve_ l i mi t the largest message that will be received. r ecei ve_si ze is the
size of the message to be received in the buffer.
r ec ei ve_ l i mi t is the maximum size of the buffer.
r eversal The ISO 8583 Protocol Engine provides reversal processing.
r ever s al _ s i z e These three parameters process reversal requests and must be
r ever s al _ l i mi t identical to the transmit buffer requirements (size and limit).

base_ name String used to construct a separate reversal file. The file
extension . REV is appended to base_ name when the reversal is
created. This allows the ISO 8583 Protocol Engine to support
different hosts and separate reversal files.
r ev_msg_i d[ 5] Like all other ISO 8583 messages, reversals require a message
ID. The ISO 8583 Protocol Engine must be able to create a
reversal for any transaction at any time. r ev_msg_i d[ ] must
be loaded with the appropriate reversal message ID for the host.

VERIX EVO ACT PROGRAMMERS GUIDE 69

ISO 8583 PROTOCOL E NGINE

IS O 85 83 Proto co l En gi ne Da ta Str uc tu re

state Flag to determine the processing state of the ISO 8583 Protocol
Engine. Uses TRAN_REQ (transaction request), REV_REQ
(reversal request), or NEW_REV_REQ (new reversal), as
defined in PROT8583. H. The state is included in the control
structure so that the application can determine the current
transaction being processed. This is useful in controlling the
types of messages displayed during communications. The
application treats this as a read-only parameter.

70 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 PROTOCOL E NGINE

Programmer-Defined Functions

Programmer- Although the ISO 8583 Protocol Engine provides interfaces to the validation and
Defined communications functions, the programmer is responsible for writing these
Functions functions. This allows programmers to meet their application-specific
requirements within the framework of the ISO 8583 standard. For examples on the
user routines and how they should look, see the example file t xrx8583. c
supplied with the Verix eVo ACT library.

mdm_tr_8583

A user-defined function that transmits and receives ISO 8583 packets. See the
TXRX8583. C file in the Verix eVo ACT library.

Prototype i nt mdm_t r _8583( i nt h_devi ce, i nt mode, unsi gned char *r eq_buf , unsi gned
r eq_si ze, unsi gned char *r cv_buf , unsi gned r cv_l i mi t ,
unsi gned t i meout , unsi gned carr i er _t i meout ) ;

Parameters
h_devi ce Device handle.
mode Transmit, receive, or TX/RX mode of modem.
r eq_buf Buffer containing request packet.
r eq_ s i z e Size of request packet.
r cv_buf Buffer to hold received packet.
r c v_ l i mi t Maximum size of receive packet.
t i meout Maximum wait period to wait for receive packet.
car r i er _t i meout Maximum wait period for the carrier to become active.

Retur n Values The following returns inform the ISO 8583 Protocol Engine that a specific transmit/
receive failure occurred.

Success: The number of characters received.

Failure: Negative: Failure.

TR_CLR_KEY: The [CLEAR] key was pressed.

TR_LOST_CARRIER: The carrier was lost.

TR_RD_FAIL: The transmit failed.

TR_TO_RESPONSE: Transmit error. Any other negative value returns as a

failure of the ISO 8583 Protocol Engine.

VERIX EVO ACT PROGRAMMERS GUIDE 71

ISO 8583 PROTOCOL E NGINE

def_valid_8583

A user-defined function that validates the received packets. See the TXRX8583. C

file in the Verix eVo ACT library.

Prototype i nt def _val i d_8583( i nt *par ms, i nt com_r esul t ) ;

Parameters
par ms Parameter used by the routine.
com_r esul t Result of the return from the communications call.

Return Values
Success: 0

Failure: Positive: Wait the number of seconds specified in the return value.

Negative: Failure.

RETRY_CONTROL_TIME: Wait another time-out.

72 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 PROTOCOL E NGINE

pro t_ 85 83 ()

prot_8583()

Transmits and receives a transaction using the ISO 8583 protocol. The PIP
Engine of Verix eVo ACT is in compliance with the ISO 8583 Messaging
standard, manage a potential power failure by creating a reversal file (when
applicable) immediately before the transaction request is sent, and delete the
reversal upon appropriate (non-reversal) return from the communication function.

NOTE
The application variables must all be loaded prior to calling this function.

A valid field table must be declared and all appropriate information loaded. The
standard global variables for transmit, receive, store, sizes, limits, and so on must
be declared and appropriate for the packets being built. The modem engine is
expected to be available if the provided communication routines are to be used.
The ISO 8583 engine for packet assembly/disassembly must be available.

Prototype i nt pr ot _8583( COMM_8583_DATA *cont r ol _dat a, i nt r ev_opt , unsi gned

r esp_t i meout ) ;

Parameters
cont r ol _dat a Protocol engine structure for this transaction.
r ev_opt Reversal option:
• REV_OFF,
• REV_ON,
• or REV_ONLY.

r esp_t i meout Time-out period for response.

Retur n Values Returns a negative return value if the function fails. errno is set with the actual
error code.

Success: 1: Received packet has been unpacked into the application

Failure: TR_CLR_KEY: Clear key pressed.

TR_LOST_CARRIER: Carrier lost by modem engine.

TR_RD_FAIL: Transmit failed in modem engine.

CREATE_REVERSAL: A reversal was created.

PROT8583_UNPACK_ERROR: Unpack routine failed.

TR_TO_RESPONSE: A transmit error occurred in the modem routine.

REQ_FAILED: Request failed.

PROT8583_FAILED_REVERSAL: Reversal failed.

PROT8583_FAILED_TRANSMIT: Transmit failed.

PROT8583_PARM_ERROR: An illegal parameter passed.

VERIX EVO ACT PROGRAMMERS GUIDE 73

ISO 8583 PROTOCOL E NGINE

check_8583_tpdu_msg_id()

PROT8583_REVERSAL_FILE_ERROR: An error occurred accessing the

reversal file.

PROT8583_CREATED_REVERSAL: The request resulted in a reversal

created.

PROT8583_CLR_KEY: Clear key pressed.

-17: Field not defined in the field table.

-18: Exceeded specified limit when parsing outgoing packet.

-19: Incoming packet exceeded specified limit.

-20: Incoming field size too large.

-21: No matching variant in variant table.

check_8583_tpdu_msg_id()

Checks the current TPDU address. Validates the message ID and TPDU in the
response message against the TPDU and message ID from the request message.
The return value is passed to the validation function for processing.

Prototype i nt check_8583_t pdu_msg_i d( COMM_8583_DATA *c ont r ol , BYTE or i g_t pdu, BYTE

*or i g_msg_i d) ;

Parameters
cont r ol Protocol engine structure for this transaction.
or i g_t pdu Request TPDU.
ori g_msg_i d Request message ID.

Return Values
Success: 1: TPDU and message ID match.

Failure: Negative: message ID and TPDU do not match.

PROT8583_RCV_TPDU_ERROR: TPDU failed.

PROT8583_RCV_MSG_ID_ERROR: Message ID failed.

PROT8583_BAD_TPDU_MSG_ID: Both the message ID and TPDU failed.

74 VERIX EVO ACT PROGRAMMERS GUIDE

ISO 8583 PROTOCOL E NGINE

pro ce ss_ 85 83 _re qu est()

process_8583_request()

Sends and receives an 8583 request. Unpacks the response, validates the TPDU
address, the message ID, and calls the users validation routine. A validation
function must be provided by the user. This routine calls process_8583_request()
and if successful, calls check_8583_tpdu_msg_id(). The return value of a
successful call is the return value of the user-defined validation function.

Prototype i nt pr ocess _8583_r equest ( COMM_8583_DATA *cont r ol _dat a, i nt mode, unsi gned
cur r ent _t i meout , BYTE *r equest _buf , unsi gned
r equest _si ze, BYTE *t pdu_buf , BYTE *msg_i d_buf ) ;

Parameters
cont r ol _dat a Protocol data structure for this transaction.
mode Transmit, receive, or TX/RX mode of modem.
cur r ent _t i meout Passed to user TXRX8583 routine as a time-out.
r equest _buf Buffer containing packet to send.
r equest _si ze Size of packet to send.
t pdu_buf TPDU address for this transaction.
msg_ i d_buf Message ID for this transaction.

Retur n Values
Success: Value of validation routine.

Failure: PROT_8583_UNPACK_ERROR.

Positive: Communication error.

VERIX EVO ACT PROGRAMMERS GUIDE 75

ISO 8583 PROTOCOL E NGINE

pro ce ss_ 85 83 _re qu es t()

76 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 8

PIP Engine

Several transaction processors, most notably American Express, require certain

applications to analyze information entered by the user (typically the account
number) and route the transaction request to the appropriate host computer. The
ability to route transactions to multiple hosts is referred to as PIP.
This section describes the key design criteria and issues that must be addressed
to successfully implement the PIP Engine in an application. In addition to
describing each of the components required to provide PIP capability, example
modules are included to illustrate how the components interface.
A glossary of PIP and ISO 8583 terminology is included in PIP/ISO 8583
Glossary.

NOTE
To ensure a successful PIP implementation, be familiar with the terminology,
protocol, and processing requirements of each host the application must support.

This engine can only be used with the Verix eVo ACT, (VPN P006-212-02), for
Verix eVo based terminals.

Compiling Most of the PIP Engine is provided in library form. Certain files, such as the
Source Code communications example TXRX8583 are provided in source form. This example
Modules code can be incorporated into the application and modified as necessary to meet
the applications communications requirements.
The source files must be compiled and linked with the application in the same
manner as all other application files. These files become, in effect, another
application file and should be processed in the same way.

Overview The PIP Engine (and associated components) provides the ability to perform the
following:
• ISO 8583 message assembly and disassembly
• ISO 8583 protocol processing (including reversal management)
• AMEX host protocol processing (including advice management)

NOTE
The AMEX host protocol processing component can be adapted for other hosts.

VERIX EVO ACT PROGRAMMERS GUIDE 77

PIP E NGINE
Overview

Each PIP host incorporates the ISO 8583 protocol from the application
construction engine. This protocol was originally developed for communications
between financial institutions and has been adapted for use in the POS
environment. It is generally used in conjunction with SDLC communications links.
ISO 8583 defines the request/response and error processing scenarios.
Adherence to these rules ensures that independently developed applications can
communicate with each other.
The main component of the ISO 8583 protocol is the message. Each message
(either a request or response) is passed between the originator and the processor.
The message is composed of a TPDU, message ID, bitmap, and a variable
number of data fields. The key to the message is the bitmap. Each field that
appears in a message is explicitly defined and assigned a number. When a field
occurs in the message, the bit corresponding to the field is set in the bitmap. In
this way, the number of fields in each message can vary. This allows the message
to contain only those fields necessary for the type of request or response being
processed.
The PIP Engine relies on various ISO 8583 engines and application-specific code
to provide the functionality required to support PIP. By allowing specific
processing to be completed by the application programmer, much more flexibility
is gained in application design, communications device management, displays,
and data storage.
Figure 3 illustrates how the PIP Engine interfaces to both the application program
and various ISO 8583 engines.

Figure 3 PIP Engine Interface

78 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
Programmer-Defined Functions/Data

The PIP Engine interfaces to the application program and the ISO 8583 Protocol
Engine. The ISO 8583 engines can be used to interface to other ISO 8583-based
hosts. The ISO 8583 Protocol Engine interfaces to the ISO 8583 Message
Engine, a validation function that validates the host response message, and
communications functions that transmits and receive messages (both of these
functions must be provided by the application). The communications function
interfaces to a communications module that processes communications to and
from the host computer. Although the ACL is not illustrated in the diagram, it is
also used at a lower level by both the PIP and Protocol 8583 Engines.
Figure 3 does not illustrate the supporting data structures. These structures are
crucial to the implementation of the PIP and ISO 8583 Engines. The application
must declare and properly initialize these data structures. Many of the
requirements of PIP are satisfied by simply completing the data declarations and
initialization. However, other requirements must be considered when planning
code requirements.

Programmer- Several data structures and five functions must be completed to support the PIP
Defined Engine. This manual clearly defines the data structures and the purpose of their
Functions/Data members. PIP does not dictate the form in which data must be managed. The
application requirements, by engine, are listed in the following table.

ISO 8583 Message Engine • Field Table

• Convert Table
• Variant field table(s)
• Bitmap
• r et ur n_var i ant {}
• r et ur n_var i ant 2{}
ISO 8583 Protocol Engine • COMM_ 8583_DATA structure
• Validation Function

• Communications Function

PIP Engine • HOST_ 8583_DATA structure

• s et _ t r ans _ f i el ds {}

PIP Files Some files are created and maintained by the PIP and ISO 8583 Protocol
Engines. Each host that uses the ISO 8583 Protocol Engine and supports
reversals requires a file to store the pending reversal. This file is managed by the
ISO 8583 Protocol Engine and is deleted once the reversal is sent to the host.
The PIP Engine creates two files for every host that supports advice. Advice is a
transaction sent to the host to inform it of some previous action or offline
transaction. On occasion, AMEX uses a stand-in host. All transactions approved
by the stand-in must be forwarded to the capture host in the form of an advice
message. One file is an index file and the other file contains the actual advice
transactions. These files are completely managed by the PIP Engine and must not
be altered.
VERIX EVO ACT PROGRAMMERS GUIDE 79

PIP E NGINE
Mo du la r De sign

PIP Engine and The PIP Engine is a modular component in a larger application. The interface
Ap pl icat io n requirements are defined and must be strictly adhered to. The PIP Engine also
Construction requires additional modular components in Verix eVo ACT.
Toolkit
PIP requires that application include the following components from Verix eVo
ACT:
• ACL
• ISO 8583 Message Engine
• ISO 8583 Protocol Engine
There are several options available to complete interface requirements of the PIP
Engine. Recommendations and examples are provided in this manual. Feel free
to employ other techniques that are compatible with the overall application design,
provided that the application meets the stated interface requirements.

Modular A modular design approach enhances the flexibility of ISO 8583 programming and
Design the PIP Engine. Many applications may require support for one or more hosts
based on the ISO 8583 protocol. However, the requirements of these hosts may
vary greatly.

ISO 8583 Prot oco l Virtually any ISO 8583 host can be supported by making calls directly to the ISO
8583 Protocol Engine level rather than at the PIP level. In fact, the ISO 8583
Protocol Engine can be used in applications that do not require PIP-level
processing.

Communications

The PIP Engine requires a user-defined communications routine as an external

interface to the application used to process transmit and receive messages
between the terminal and host. The ISO 8583 Protocol Engine makes no
assumptions about the link to the host. This means that you can easily connect to
devices other than the modem. This call is only required to send the request and
obtain a response. This simple definition also means that other hosts, including
async hosts, can be supported with the same communications routine (as long as
calling and return requirements are met). For example, you may be connected to
a PC for standard transaction processing using the COM1 port and to the modem
port for dial backup processing.

ISO 8583 The ISO 8583 Message Engine supports the message processing requirements
Message of the ISO 8583 Protocol. The functionality provided by this engine includes:
Engine • Assembly and disassembly of packets based on the ISO 8583 standard
• Management of the bitmap that defines the valid fields in each packet
• Conversion of data packet fields in request and response messages

80 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
ISO 85 83 Me ssa ge En gi ne

The ISO 8583 Message Engine uses a field table, a variant field table, and a
converter table.

NOTE Although the ISO 8583 Message Engine is being discussed in the context of PIP, it
can be used in any application that is required to support the ISO 8583 standard.
For more information about the ISO 8583 Message Engine, refer to ISO 8583
Message Interface Engine.

The Field Table The field table is a master table that lists every data field that can be included in
any request or response packet. This is necessary to provide the engine with the
required information to access the application data elements, as well as complete
the necessary data conversion.

Field Table Structure

The field table describes every field that can be included in any request or
response packet. This table is used by the ISO 8583 Message Engine to
assemble and disassemble packets. Each table entry contains the field number,
the length of the field in the packet, an index into the conversion table for
converting the packet fields to and from the application data types, a pointer to the
application data variable, and the size of the application data element.
The table is an array of the following structure:
t ypedef st r uct
{
i nt f i el d_num;
i nt packet _sz;
i nt conver t _i dx;
voi d *r ef erence;
i nt var _ s z;
} f i el d_ st r uct ;

NOTE
The field table structure is defined in the ISO8583.H file.

VERIX EVO ACT PROGRAMMERS GUIDE 81

PIP E NGINE
IS O 85 83 Me ssag e Engi ne

Parameters
f i el d_ num The field number corresponds to a bit position in the bitmap for the
ISO 8583 packet. When a packet is assembled or disassembled, the
bitmap indicates the next field to assemble or parse. The first ISO
8583 field is bit two, as bit one is used as a bitmap extension
indicator.
There must be a minimum of two elements in the field table array: the
TPDU and the message ID. Each of these fields is expected to be
packed BCD values and must be loaded into the appropriate
application variables by the s et _ t r ans _ f i el ds ( ) function. In
addition to the field number, the following two special entries can be
used in this field:
• SKIP indicates that the engine should skip over this field, because
it is being sent by the host but is not used by the application.
• STOP indicates that this is the last field in the table.
Note: The stop entry must be included in the table.
packet _sz Specifies the length of the field (or the maximum length for variable
length fields) in the ISO 8583 message. To determine the correct field
length, refer to the host documentation.
conver t _i dx Each field in an ISO 8583 message is required to be in a specific data
format. The ISO 8583 Message Engine includes a variety of
conversion functions that convert the data format defined for the field
to the required ISO 8583 data format (for example, BCD to string).
The convert index is an index into the convert table (see The Convert
Table) that indicates what conversion function pair to use for the
message field.
In addition to the convert index, the following two special entries can
be made in the convert index field:
• VARIANT indicates that the field varies depending on the
message. In this case, a variant field table is used as the
application variable. The ISO 8583 Message Engine accesses the
variant field table to determine the conversion required for the field.
• COMPUTE indicates that the contents of the field are calculated at
the time the message is assembled/disassembled. The application
variable field becomes a pointer to a function that performs the
required calculation.
r ef er ence Contains a pointer (variable name) to the application variable, variant
field table, or compute function required for the field. These variables
are usually character arrays (for example, char xxx[ xx] ; ) when
using the standard ISO 8583 conversion functions. Conversion
functions (for example, long to BCD) must be written and included in
the convert table when using a data format for variables other than a
character array.
var_sz Specifies the size of the application variable for this field. This
performs limits checking when disassembling messages.
An example of a completed field table follows. For more information
about how to construct the field table, refer to ISO 8583 Message
Interface Engine.

82 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
ISO 85 83 Me ssa ge En gi ne

Applications specifying a value for 8583 sz smaller than the actual data length to
be converted may have been successful with earlier versions. Such applications
will now fail, returning an error value (-4). Programmers should correct the value
of 8583 sz to accurately reflect the maximum length of the data field.
Carefully inspect the 8583 sz field when using the following conversions:
AV2_STR, BV2_STR, AV3_STR, HST_BI2, HST_BI3, STR_AV2, STR_BV2,
STR_AV3, BI2_HST, BI3_HST, and AV3_AV3.
f i el d_ st r uct f i el d_ t abl e [ ] =
{
/ * Fi el d Packet Conver t Var i abl e Var i abl e */
/ * # Si ze I ndex Name Si ze */
{ 0, 10, BCD_STR, ( voi d *) t pdu, si zeof ( t pdu) },
{ 0, 16, BI T_BI T, ( voi d *) t _msg_i d, si zeof ( t _msg_i d) },
{ 3, 24, BI T_BI T, ( voi d *) t _pr oc_code, si zeof ( t _pr oc_code) },
{ 4, 12, BCD_SNZ, ( voi d *) t _amount , si zeof ( t _amount ) },
{ 5+ SKI P, 12, BCD_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{10+ SKI P, 8, BCD_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{11, 6, LNG_BCD, ( voi d *)& t _sys_t r ace, si zeof ( t _sys_tr ace) },
{12, 6, BCD_STR, ( voi d *) t _t i me, si zeof ( t _t i me) },
{13, 4, BCD_STR, ( voi d *) t _dat e, si zeof ( t _dat e) },
{14, 4, BCD_STR, ( voi d *) t _car d. exp, si zeof ( t _car d. exp) },
{15+ SKI P, 4, BCD_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{21+ SKI P, 4, BCD_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{22, 3, BCD_STR, ( voi d *) t _posem, si zeof ( t _posem) },
{23+ SKI P, 3, BCD_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{24, 3, BCD_ STR, ( voi d * ) t _ ni i , s i z eof ( t _ ni i ) },
{25, 2, BCD_STR, ( voi d *) t _poscc, si zeof ( t _poscc) },
{26+ SKI P, 2, BCD_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{34+ SKI P, 28, AV2_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{35, 37, BV2_STR, ( voi d *) t _car d. t r ack, si zeof ( t _car d. t r ack) },
{36+ SKI P, 104, AV2_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{37, 12, ASC_STR, ( voi d *) t _key. r r n, si zeof ( t _key. r r n) },
{38, 6, ASC_STR, ( voi d *) t _aut h_code, si zeof ( t _aut h_code) },
{39, 2, ASC_STR, ( voi d *) t _r esp_code, si zeof ( t _r esp_code) },
{40+ SKI P, 3, ASC_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{41, 8, ASC_STR, ( voi d *) t _host _dat a. t i d, si zeof ( t _host _dat a. t i d) },
{42, 15, ASC_STR, ( voi d *) t _host _dat a. mi d, si zeof ( t _host _dat a. mi d) },
{43+ SKI P, 40, ASC_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{44, 2, AV2_STR, ( voi d *) t _add_r esp, si zeof ( t _add_r esp) },
{45, 79, AV2_STR, ( voi d *) t _car d. t r ack, si zeof ( t _car d. t r ack) },
{46+ SKI P, 999, AV3_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{53+ SKI P, 16, BCD_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{54, 12, AV3_STR, ( voi d *) t _t i p, si zeof ( t _t i p) },
{55+ SKI P, 999, AV3_STR, ( voi d *) di scar d, si zeof ( di scar d) },
{59+ SKI P, 999, AV3_STR, ( voi d *) di scar d, si zeof ( di scar d) },

VERIX EVO ACT PROGRAMMERS GUIDE 83

PIP E NGINE
IS O 85 83 Me ssag e Engi ne

{60, 0, VARI ANT, ( voi d *) var i ant _60, 0 },

{61, 8, AV3_STR, ( voi d *) t _product _code, si zeof ( t _product _code)},
{62, 10, AV3_STR, ( voi d *) t _key. t i cket , si zeof ( t _key. t i cket ) },
{63, 0, VARI ANT, ( voi d *) var i ant _63, 0 },
{64+ SKI P+ STOP, 64, BI T_BI T, ( voi d *) di scar d, si zeof ( di scar d) },
};

The first two elements, the TPDU and message ID, have special meaning. These
elements must always be present in the field table. Each of these elements has a
field number of 0, which means they do not have bitmap assignments. More
information about each of these special fields follows.

The TPDU

The Transport Protocol Data Unit (TPDU) routes the SDLC message. It consists
of a transaction type identifier, an originator address, and a destination address.
For AMEX transactions, the transaction type identifier is either 0x60 for application
messages or 0x68 for NMS/TNMS transactions. The typical application only uses
0x60.

NOTE
Refer to Typical Host/Terminal Packet Structure for a diagram of each of the host/
terminal packet formats.

The originator and destination addresses are each two bytes. The TPDU should
be provided by the host. The TPDU is the only SDLC component that must be
provided (other than opening the port in SDLC mode).

NOTE In a request message, the destination address occurs before the originator
address. In a response message, the originator address occurs before the
destination address. This distinction is important.

84 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
ISO 85 83 Me ssa ge En gi ne

The Message ID

The message ID indicates the type of message and message function. The
message ID is an ISO 8583 requirement, not an SDLC requirement. The message
ID is four digits and is compressed to two bytes when placed in an ISO 8583
packet. A description of each of these digits is in the following table.

Position Description
First Digit The version number (always 0).
Second Digit Message class. This variable depends on the requested transaction.
The following list identifies valid values for the message class. A host
may not use every message class.
• 1 = Authorization
• 2 = Financial capture
• 3 = File update
• 4 = Reversals
• 5 = Reconciliation
• 8 = Maintenance
Third Digit Message function. This identifies a particular operation for a message
type (as in a request for authorization or a financial capture response).
Valid values are:
• 0 = Request
• 1 = Response to a request
• 2 = Advice
• 3 = Response to an advice
• 4 = Notification
• 5–9 = These codes are reserved for ISO use
Fourth Digit Transaction originator. This position is always 0 for requests and
responses.

An example of a typical message ID is a 0200 request message (financial capture

request). This message is sent to a host to request authorization for a transaction
that, if approved, is electronically captured and settled. The host responds with a
0210 response message (financial capture response).
For more information about the message ID fields, refer to the AMEX 3000 PIP
Terminal Technical Specifications document.

VERIX EVO ACT PROGRAMMERS GUIDE 85

PIP E NGINE
IS O 85 83 Me ssag e Engi ne

The Convert Table The convert table contains pairs of pointers to functions that allow the ISO 8583
Message Engine to convert application data to packet data and vice versa. The
PIP Engine includes a standard set of conversion routines and a standard convert
table, which provide all the conversions needed for processing AMEX
transactions.

NOTE The ISO 8583 Message Engine Reference section contains instructions for
adding additional conversions to support other host packet requirements. The
function references for each of the conversion functions are located in the ISO
8583 Message Interface Engine Function Calls section.

The convert table must contain all the pairs are used by the application to convert
the data. Do not change the name of this table, conver t _t abl e. Entries may be
added to the end of this table. However, do not modify existing entries
conver t er s conver t _t abl e [ ] =
{
{asc_t o_asc, asc_t o_asc}, / * ASC_ASC 0 */
{av3_t o_av3, av3_t o_av3}, / * AV3_AV3 1 */
{bi t _ t o_ bi t , bi t _ t o_ bi t }, / * BI T_ BI T 2 * /
{bcd_t o_bcd, bcd_t o_bcd}, / * BCD_BCD 3 */
{asc_ t o_bcd, bcd_t o_asc}, / * BCD_ASC 4 */
{st r _t o_asc, asc_t o_st r }, / * ASC_STR 5 */
{st r _t o_bcd, bcd_t o_st r }, / * BCD_STR 6 */
{st r _t o_bcd, bcd_t o_snz}, / * BCD_SNZ 7 */
{st r _t o_av2, av2_t o_st r }, / * AV2_STR 8 */
{st r _t o_bv2, bv2_t o_st r }, / * BV2_STR 9 */
{st r _t o_av3, av3_t o_st r }, / * AV3_STR 10 */
{st r _t o_xbc, xbc_t o_st r }, / * XBC_STR 11 */
{hst _t o_bi n, bi n_t o_hst }, / * BI N_HST 12 */
{hst _t o_bi 2, bi 2_t o_hst }, / * BI 2_HST 13 */
{hst _t o_bi 3, bi 3_t o_hst }/ * BI 3_HST 14 */
};

Variant Fields Variant fields depend on the type of message being sent and the function of that
message. An example of a variant field might be the private fields 60 to 63. These
fields can be any length up to 999 bytes, and can be used for any purpose agreed
upon by the host and requesters.
The field table allows a special entry, VARI ANT, in the convert index to indicate that
a variant field table exists to further define this field. When the ISO 8583 Message
Engine encounters this entry, it selects the indicated field table and continues to
process the field entry for the message.

NOTE To use variant fields, you must create two functions: unsigned int return_variant1()
and unsigned int return_variant2(). For more information on how to write these
functions, refer to PIP Engine and Application Construction Toolkit.

86 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
ISO 85 83 Pro toco l En gine

Computed Fields In some cases, a field may need to be computed. This computation may depend
on other fields in the packet, other application variables, the entire packet (such
as, a checksum), or other types of calculations.
The field table allows a special entry, COMPUTE, in the convert index to indicate that
a computed field table exists to further define this field. When the ISO 8583
Message Engine encounters this entry, it calls the function pointed to in the field
table entry and accepts the result as the contents of the packet field.

NOTE
Computed fields are not currently required to interface with the AMEX host. This
information is included in the event an alternate host requires this type of field.

ISO 8583 In addition to assembling/disassembling data packets (as described in the ISO
Protocol 8583 Message Engine section), the application must support the ISO 8583
Engine protocol. The ISO 8583 Protocol Engine was developed to provide this support.
This engine includes:
• an interface to the ISO 8583 Message Engine to assemble and disassemble
packets,
• an interface to the programmer-defined validation function that determines if
an appropriate response was received,
• an interface to the programmer-defined communications function that
transmits and receives request/response messages, and
• processes reversals as specified in the ISO 8583 Messaging standard.
PIP Engine has the following power-fail recovery mechanism:
• Determines if reversals are allowed, and that a transaction request is to be
generated. Create a contingent reversal file for that transaction request just
prior to the internal call to the programmer-supplied communication and
validation functions.
• On successful return of the programmer-supplied communication and
validation functions, or on return of any error not considered a reversal
condition, delete this contingent reversal file.
If a power failure occurs during this period of vulnerability, an internal routine
checks for a reversal file at the beginning of the next transaction request session.
If this file exists, it sends a reversal request as appropriate. No intervention by the
application is necessary.

VERIX EVO ACT PROGRAMMERS GUIDE 87

PIP E NGINE
IS O 85 83 Pro to co l Engi ne

Protocol 8583 Data The ISO 8583 Protocol Engine uses the following data structure (defined in
Structure PROT8583. H) to provide information and application data variables.
t ypedef st r uct c8583dat
{
f i el d_ s t r uc t * p_ f l d_ t a bl e;
i nt *comm_handl e;
unsi gned comm_t i meout ;
unsi gned wai t _f or _car r i er ;
unsi gned char *map;
i nt ( * val i dat i on) ( ) ;
voi d *v_ par ms;
unsi gned v_par ms_ si ze;
i nt ( * t r ans cei ver ) ( ) ;
unsi gned char * t r ansmi t ;
unsi gned i nt t r ansmi t _si ze;
unsi gned tr ansmi t _l i mi t ;
unsi gned char * r ecei ve;
unsi gned r ecei ve_si ze;
unsi gned r ecei ve_l i mi t ;
unsi gned char *r ever sal ;
unsi gned r ever sal _si ze;
unsi gned r ever sal _l i mi t ;
unsi gned char *base_Pur posef name;
unsi gned char r ev_msg_i d [ 5] ;
i nt s t at e;
} COMM_8583_ DATA;

Programmer- To use the PIP Engine, write a function called s et _ t r ans _ f i el ds ( ) . This
Defined Setup function is called at the beginning of the PIP Engine and must set up the following
Function information:
• the processing code,
• the message ID,
• the TPDU, and
• the bitmap.
This information is used to build the request packet. In addition, this information
must be preserved as a structure to ensure that it is not overwritten by the data
included in the host response.

NOTE
For more information on how to write this function, refer to Integrating the PIP
Engine Into Your Application.

88 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
Inte gr atin g th e PI P En gi ne In to Your Ap pl ic at io n

Integrating t he Integrating the PIP Engine and its associated modules into the application is a six-
PIP Engi ne Into step process:
Your 1 Plan and define all required tables and data structures.
Applicat ion
2 Write and test the r et ur n_var i ant 1( ) and r et ur n_var i ant 2( ) functions.

3 Write the s et _ t r ans _ f i el ds ( ) function.

4 Write a communications (transceiver) function.

5 Write a validation function.

6 Make the appropriate calls to pip_trans() from the application.

This process must be clearly understood before beginning the integration.

Step 1 - Plan and Declare the data elements required by each of the following engines:
define all required
Field table
tables and data ISO 8583
structures Variant field tables (if required)
Message Engine
Convert table
ISO 8583 COMM_8583_DATA structure
Protocol Engine Validation structure

PIP Engin e HOST_8583_DATA structure

Declarations and examples can be found with the engine files (when appropriate).

Ap pl ic ati on Vari able

In addition to declaring the tables and data structures listed above, also declare a
variable named gu_cl r _st at e ( unsi gned i nt ) and initialize it to 0. This
variable can be used to support clear key processing in the pip_trans() and
prot_8583() functions. Each of these functions aborts processing and returns to
the caller if this variable is set to any value other than 0 (zero). This is a
convenient way to interrupt the function processing when the clear key is pressed.

Step 2 - Develop t he Variant field tables use two additional pieces of information to determine the
return_variant1 and description of the field. The functions r et ur n_var i ant 1( ) and
return_variant2 r et ur n_var i ant 2( ) must return values that are compared to entries in the
functions
variant field tables to indicate if the current entry in the field table is to be used, or
if the message engine should continue to process the variant field table. The ISO
8583 Message Engine provides functions for r et ur n_var i ant 1( ) and
r et ur n_var i ant 2( ) used to access the variant field tables constructed for the
AMEX host. These functions are generally useful in processing any ISO
8583-based host.

VERIX EVO ACT PROGRAMMERS GUIDE 89

PIP E NGINE
In te grat in g the PIP En gine Into Your Appl ic at io n

When processing the field tables, the ISO 8583 Message Engine calls
r et ur n_var i ant 1( ) and r et ur n_var i ant 2( ) , then compares these values to
the values in the first two positions of each array element of the variant field table.
The convert index, variable name, and variable size fields have the same function
as their counterparts in the field table.
The following examples show the r et ur n_var i ant 1( ) and r et ur n_var i ant 2( )
functions and two sample variant field tables for fields 60 and 63. In these
examples, r et ur n_var i ant 1( ) returns the first two digits of the processing code
and r et ur n_var i ant 2( ) returns the message ID (each converts the data to
integer form).
/ * I f var i ant f i el ds ar e used, t hi s i nt eger val ued f uncti on must r et ur n a
val ue whi ch wi l l be used t o mat ch agai nst t he val ues i n t he f i r st f i el d of
var i ant f i el d t abl es . * /
unsi gned i nt r et ur n_var i ant 1( )
{
unsi gned char x [ 3] ;
MEMCLR ( x, 3) ;
/ * Most si gni f i cant 2 di gi t s of pr oc_code. */
SVC_UNPK4 ( x, t _pr oc_code, 1) ;
r e t ur n ( s t r 2i nt ( x) ) ;
}

/ * I f var i ant f i el ds ar e used, t hi s i nt eger val ued f uncti on must r et ur n a

val ue whi ch wi l l be used t o match agai nst t he val ues i n t he second f i el d
of var i ant f i el d t abl es . * /
unsi gned i nt r et ur n_var i ant 2( )
{
unsi gned char x [ 5] ;
MEMCLR ( x, 5) ;
SVC_UNPK4 ( x, t _msg_i d, 2) ;
r e t ur n ( s t r 2i nt ( x) ) ;
}

/ * Type def i ni t i on f or an i ndi vi dual member of a var i ant f i el d t abl e

ar r a y. * /
t ypedef st r uct
{
unsi gned i nt var i ant 1; / * Tar get . */
unsi gned i nt var i ant 2; / * Tar get . */
i nt packet _sz; / * Packet si ze. */
i nt conver t _i dx; / * I ndex i nt o conver t t abl e. */
voi d *r ef er ence; / * Poi nt er t o var i abl e or t abl e. */
i nt var _ s z ; / * Var i abl e s i z e. * /
} var i ant _st r uct;

var i ant _st r uct var i ant _60[ ] =

90 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
Inte gr atin g th e PI P En gi ne In to Your Ap pl ic at io n

{
/ * Var i - Var i - Pack Conver t Var i abl e Var i abl e ant 1 ant 2 Si ze I ndex
Name Si ze * /
{ 00, 320, 37, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 02, 320, 37, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 22, 320, 37, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 09, 320, 37, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 29, 320, 37, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 92, 500, 6, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 96, 500, 6, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 97, 500, 6, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 92, 510, 12, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 96, 510, 12, AV3_STR, ( voi d *) or _msg, si zeof ( or _msg) },
{ 00, 420, 22, AV3_STR, ( voi d *) ah_dat. dcp_or i g_msg, si zeof
( ah_dat . dcp_or i g_msg) },
{ 02, 420, 22, AV3_STR, ( voi d *) ah_dat. dcp_or i g_msg, si zeof
( ah_dat . dcp_or i g_msg) },
{ 22+ STOP, 420, 22, AV3_STR, ( voi d *) ah_dat . dcp_or i g_msg, si zeof
( ah_dat . dcp_or i g_msg) },
};

/ * Var i ant s t r uc t ur e f or f i el d 63.

* 0500 = Reconci l i ati on
* 0320 = Bat ch upl oad - sal e, f or ce, credi t , voi d ( debi t and cr edi t )
* 0200 = Sal e
*/
var i ant _st r uct var i ant _63 [ ] =
{
/ * Var i - Var i - Pack Conver t Var i abl e Var i abl e ant 1 ant 2 Si zeI ndex
Name Si ze * /
{ 00, 200, 112, BI T_BI T, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 00, 210, 40, AV3_STR, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 00, 110, 40, AV3_STR, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 02, 320, 112, BI T_BI T, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 22, 320, 112, BI T_BI T, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 22, 330, 40, AV3_STR, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 20, 330, 40, AV3_STR, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 97, 500, 36, AV3_STR, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 93, 510, 42, ASC_ASC, ( voi d *) bat _t ot , si zeof ( bat _t ot ) },
{ 94+ STOP, 510, 42, ASC_ASC, ( voi d *) bat_ t ot, si zeof ( bat_ t ot) },
};

Step 3 - Writ e the Write a s et _ t r ans _ f i el ds ( ) function (an example is provided with the PIP
set_trans_fields Engine files). When this function call ends, the following must be complete:
function
• the system trace number is properly set (increment as needed),
• the processing code is loaded,

VERIX EVO ACT PROGRAMMERS GUIDE 91

PIP E NGINE
In te grat in g the PIP En gine Into Your Appl ic at io n

• the message ID is loaded,

• the TPDU is loaded,
• the bitmap is loaded, and
• the validation structure is initialized.
The following is an example of a s et _ t r ans _ f i el ds ( ) function. It is not
necessary to follow this example exactly. In fact, it is necessary to alter the
processing of this function depending on the way handle data storage is handled.
/ * Thi s f unct i on uses a f i l e t o st ore t he bi t map, message I D, & pr ocessi ng
code. */
i nt s et _ t r ans _ f i el ds ( hos t , t r ans ac t i on_ t ype) ;
i nt hos t ;
i nt t r ansacti on_t ype;
{
i nt f _handl e; / * Handl e used t o access t he f i l e. */
ext er n BYTE sour ce_map[ 8] ;
/ * Var i abl e used t o cont ai n t he mandat or y bi t f i el ds f or t he t r ansact i on.
*/
/ * Open b- m- p f i l e, r et ur n i f an er r or occur s. */
i f ( - 1 == ( f _handl e = open( " bmp. l od" , O_RDONLY) ) )
r et ur n( f _handl e) ;
/ * Thi s f unct i on r eads t he bi t map, message I D, and pr ocessi ng code i nt o
t he i ndi cat ed var i abl es. These are t he gl obal val ues whose addr esses
appear i n t he f i el d t abl e. */
l oad_bmp( f _handl e, t r ansacti on_t ype, sour ce_map, t _msg_i d, t _pr oc_code);
cl ose( f _handl e) ;
/ * Load t he TPDU. */
st r copy( t pdu, " 6001000000" ) ;
/ * I ncr ement t he syst ems t r ace number . Thi s i s mai nt ai ned as a LONG val ue
and i s conver t ed when pl aced i n t he I SO 8583 packet . The conver si ons
bcd2l ng( ) and l ng2bcd( ) are used f or t hi s pur pose. */

t _s ys_t r ace++;
/ * The val i dat i on st r ucture f or t hi s appl i cat i on cont ai ns t he addr ess of
t he syst ems t r ace number and the or i gi nal val ue of t he t r ace number . Thi s
makes val i dat i on easi er . */
i nput _val _st r uct . p_t r ace = &t _sys_tr ace;
i nput _val _st r uct. b_t r ace = t _sys_t r ace;

92 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
Inte gr atin g th e PI P En gi ne In to Your Ap pl ic at io n

/ * Some t r ansacti ons, such as adj ust ment s, r equi r e t he RRN of t he or i gi nal
t r ansact i on be sent as a f i el d i n t he r equest . Thi s appl i cat i on saves t he
val ue of t he request RRN si nce t he val ue i n t he f i el d t abl e wi l l be
overwr i t t en when t he response i s processed. */

s t r c py( i nput _ val _ s t r uc t . , t _ key. r r n) ;

/ * The t er mi nal I D i s a val i dat i on par amet er . The or i gi nal t er mi nal I D
must be compar ed t o t he t er mi nal I D i n t he r esponse message. Si nce t he
ori gi nal wi l l be l ost when t he r esponse i s unpacked, t hi s st ep saves t he
ori gi nal val ue f or compari son. The poi nt er i s used t o conveni ent l y access
t he message I D dur i ng val i dati on. */

i nput _val _st r uct. p_t i d = ( unsi gned char *) t _host _dat a. t i d;

s t r c py( i nput _ val _ s t r uc t . b_ t i d, t _ hos t _ dat a. t i d;

/ * The r equi r ement s f or t he above message I D appl y t o t he amount whi ch
means t he amount must be pr ocess ed i n a si mi l ar manner . */

i nput _val _st r uct . p_amount = ( unsi gned char *)

t _amount ;

st r cpy(i nput _val _st r uct . b_amount , t _amount ) ;

/ * set _t r ans_f i el ds shoul d r et ur n 1 i f i t i s successf ul . Any negat i ve
val ue wi l l abor t . * /

return(1);
} / * end s et _ t r ans _ f i el ds ( ) * /

Step 4 - Writ e the The user-defined communications function (also called the transceiver function)
communications ensures that no restrictions are placed on the way communications are
function accomplished. The ISO 8583 Protocol Engine makes no assumptions about how
the application communicates and permits processing through a serial port,
modem, and so on.
The calling syntax and return values are defined (refer to the following table). This
interface definition allows the ISO 8583 Protocol Engine to correctly call the
communications routine, as well as return meaningful results on the success or
failure of the communications process.
Use #def i nes (listed in PROT8583.H) when writing the communications
function. This ensures that the proper values are used, makes the source code
more readable, and is easier to remember.
The function can have any name. The name of the function is placed in the
transceiver member of the COMM_8583_DATA structure. The function can also
be called directly by the application to complete other communication
requirements. The example provided is named mdm_ t r _8583( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 93

PIP E NGINE
In te grat in g the PIP En gine Into Your Appl ic at io n

The following syntax is used when calling the communications function:

i nt mdm_t r _8583 ( i nt h_devi ce, i nt mode, unsi gned char *r eq_buf , unsi gned
r eq_si ze, unsi gned char *r cv_buf , unsi gned rcv_l i mi t , unsi gned t i meout ,
unsi gned carr i er _t i meout ) ;

The mode parameter must be either TXRX or RX_ONLY (defined in

PROT8583.H). When mode is TXRX, the communications function sends the data
in the r eq_buf and waits for a response. RX_ONLY is used to request that the
communications function wait for an additional response message.
The AMEX host may send a “Please Wait” message in response to a request.
When this happens, the validation routine should request an additional response
packet with a 60 second time-out. Additionally, any message that fails validation
results in a request for another request packet.
The carrier time out may not be required, depending on the method used by the
application to establish the link to the host. It is highly recommended that the
application perform a pre-dial to initiate the connection with the host as early as
possible in the transaction. The following table lists the required return values for
the transceiver function.

Success: TR_SUCCESS (1): Request successful.

Failure: TR_BAD_PARM (-33): Incorrect parameter in call.

TR_TO_CARRIER (-34): Time out waiting for carrier (no reversal).

TR_WR_FAIL (-35): Write to port failed (no reversal).

TR_TO_RESPONSE (-36): Time out waiting for response (create reversal).

TR_RD_FAIL (-37): Read port failed (create reversal).

TR_LOST_CARRIER (-38): Connection to host lost after request was sent

(create reversal).

TR_CLR_KEY (-47): Clear key press (no reversal). This value should not
be returned once the request has been sent.

{
i nt r et _val = TR_SUCCESS;
unsi gned car r i er_ del ay;
unsi gned l ong r ecei ve_del ay;
char mdm_s t at us [ 5] ;
/ * Car r i er del ay i s i n seconds == 50 ms * 20 * del ay. */
car r i er _del ay = car r i er _t i meout * 20;
/ * Wai t f or car r i er t o be avai l abl e onl y i f t he mode i s TXRX. */
whi l e ( ( 0 == ( r et _val = mdm_check_ st at us ( h_devi ce, MDM_DCD) ) ) && TXRX ==
mode)
{

94 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
Inte gr atin g th e PI P En gi ne In to Your Ap pl ic at io n

/ * Do car r i er del ay i n 50- ms i ncr ement s. */

i f ( gu_ cl r _ s t at e)
{
r et _val = TR_CLR_KEY;
br eak;
}
el s e i f ( c ar r i er _ del ay- - > 0)
{
SVC_WAI T ( 50) ;
}
el s e
{
/ * Ti med out wai t i ng f or carr i er , set * r et _val and exi t . */
r et _val = TR_TO_CARRI ER;
br eak;
}
} / * End whi l e wai t c l r or c ar r i er . * /
/ * Cont i nue i f not t i med out f or car r i er and [CLEAR] key has not been *
pr essed. */

i f ( 0 < r et _ val )
{
/ * I f mode 0, t hen send r equest . */
i f ( TXRX == mode)
{
/ * Send t he r equest message. */
i f ( r eq_si ze ! = ( r et _val = wr i t e ( h_devi ce, r eq_buf , r eq_si ze) ) )
{
/ * Wr i t e f ai l t o devi c e, ei t her por t er r or , no buf f er s , or * not
enough char act er s wr i t t en */
err no = r et_ val ;
r et _val = TR_WR_FAI L;
}
}
/ * End t r ansmi t . */

/ * Begi n r ecei ve pr ocessi ng. */

i f ( 0 < r et _ val )
{
/ * Set wai t f or r esponse ti meout . */
r ecei ve_del ay = set _i t i meout ( gh_cl ock, t i meout , TM_SECONDS) ;
whi l e ( 0 >= mdm_i nput _pendi ng ( h_devi ce) )
{
i f ( 0 == mdm_check_ st at us ( h_devi ce, MDM_DCD) )
{

VERIX EVO ACT PROGRAMMERS GUIDE 95

PIP E NGINE
In te grat in g the PIP En gine Into Your Appl ic at io n

r et _val = TR_L OST_CARRI ER; br eak;

}
/ * Wai t f or t i meout or r ecei ved message packet */
i f ( TM_EXPI RED==CHK_TI MEOUT ( gh_cl ock, r ecei ve_del ay) )
{
r et _val = TR_TO_RESPONSE;
br eak;
}
} / * End whi l e. */

/ * I f r et _ val i s s t i l l pos i t i ve, we have a pac ket t o r e ad. * /

i f ( 0 < r e t _ v al )
{
/ * I nbound packet r eady, set r et _val t o er r or i f r ead f ai l s. */
i f ( 0 >= ( r et _val = r ead ( h_devi ce, r cv_buf , r cv_l i mi t ) ) )
{
er r no = r et _val ; r et _val = TR_RD_FAI L;
}
}
/ * End r ecei ve. */
}
/ * End wai t f or r esponse. */
}
/ * End i f car r i er and not [ CLEAR] key. */
/ * I f r e t _ v al i s s t i l l pos i t i ve, we s uc ceeded. I f not , one of * t he s t e ps
f ai l ed. The f i r s t er r or ends t he pr oc es s . * /
r et ur n( r et _ val ) ;
} / * End mdm_t r _8583( ) . */

Step 5 - Writ e the Validation refers to verifying that the response received for a request is
validation function appropriate. This, of course, varies from one host to host. The ISO 8583 Protocol
Engine always validates the TPDU and message ID, and passes the result of the
validation to the validation routine of the application for further processing. The
ISO 8583 Protocol Engine will not abort the transaction, even if the TPDU and
message ID are both invalid. The engine relies on the validation of the application
to determine if the response is to be accepted or rejected.
The results of the validation are application dependent. Several options are
possible. The value returned by the validation routine dictates the action to take. A
positive return value indicates that the ISO 8583 Protocol Engine should call the
communications routine to wait for another response packet using the return value
as the time out in seconds. The validation routine may also return the #def i ne
RETRY_CONTROL_TIMEOUT (-15) to request another response message using
the time out in the ISO 8583 Protocol Engine data structure. The validation routine
may also return CREATE_REVERSAL.

96 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
Inte gr atin g th e PI P En gi ne In to Your Ap pl ic at io n

These values are defined in PROT8583. H. Returning CREATE_REVERSAL

instructs the ISO 8583 Protocol Engine to create a reversal record. This record is
sent to the host (as a separate transaction) preceding the next transaction. The
reversal message informs the host to eliminate the transaction identified (as
though the transaction did not occur). When validating AMEX responses, any
invalid response should cause the application to continue to wait for an additional
response.

AMEX Validat io n The ISO 8583 Protocol Engine provides two example validation functions that
Functions properly validate AMEX host transactions: amex_val i dat i on_l ow( ) and
amex_val i dat i on_hi gh( ) .

Since these functions are provided on the distribution diskette in source form, they
must be modified to support additional hosts. The functions can be used as is for
AMEX transaction processing. If the application is interfacing to other hosts, write
validation function(s) for each host.

amex_validation_low() Function

AMEX can respond with one of two special messages: The “Please Wait”
message means that the host is processing the request and the terminal should
allow another time period (usually 60 seconds) for the response. The “Hang Up”
message means that there is a problem processing the request (the host is not
available) and the terminal should abort the transaction request.
amex_val i dat i on_l ow( ) is responsible for detecting each of these response
messages. This function, called from amex_val i dat i on_hi gh( ) , either
processes one of these two messages as indicated or continues to validate the
response.

amex_validation_high() Function

The second validation routine is amex_val i dat i on_hi gh( ) . This function is used
as the validation routine in the ISO 8583 Protocol Engine data structure. This
function calls the amex_val i dat i on_l ow( ) function. If the response is “Please
Wait” or “Hang UP”, it is processed accordingly. Validation continues for all other
responses.

The Validation The next step in the validation process is to determine the proper validation
Process parameters. Reversals are processed prior to actual transactions. When a
reversal exists, two transactions are pending when the validation routine is called.
The validation routine tests the state in the COMM_8583_DATA structure to
determine if the validation is for a transaction request or a reversal. If the request
is for a reversal, the reversal parameters are copied from the beginning of the
reversal buffer to the local validation structure; otherwise, the transaction
validation parameters are used.

VERIX EVO ACT PROGRAMMERS GUIDE 97

PIP E NGINE
In te grat in g the PIP En gine Into Your Appl ic at io n

The transaction amount, systems trace number, and terminal ID are now
compared. The transmitted and received values must match. The
amex_val i dat i on_hi gh( ) routine pads the amounts to a minimum of three
characters to ensure proper comparison. The validation routine expects the
systems trace number to be a global long, and it expects the terminal ID and
amounts to be strings. If other data types are used, change the comparisons in
amex_val i dat i on_hi gh( ) accordingly.

Another special case occurs if a DCP response is received for a reversal request.
The PIP Engine must create an advice message that is forwarded to the AMEX
host at a later time. The amex_val i dat i on_hi gh( ) function tests for this by
comparing the message ID to 0400, the reversal message ID. If the response is
for a reversal, then the value of field 44 is tested. If this field is 02, then a DCP
response was received for the reversal and the validation routine returns
AMEX_DCP_REVERSAL. Upon receiving this return code, the advice is created.
The validation routine returns a 0 if the response is valid for the request. This is
accepted by the ISO 8583 Protocol Engine, and the value either returns to the
caller, or processes the transaction request. This scenario varies with previous
transaction activity.
The ISO 8583 Protocol Engine includes a validation structure used with the
provided validation routines. Again, this structure may be modified as needed.
You are responsible for ensuring that the application meets AMEX validation
criteria.
The validation structure is listed below, followed by an explanation of its members.
t ypedef st r uct
{
unsi gned char b_amount [ 13] ;
unsi gned char b_t i d[ 9] ;
l ong i nt b_t r ace;
unsi gned char b_r r n[ 13] ;
unsi gned char *p_amount ;
unsi gned char *p_t i d;
l ong i nt *p_t r ace;
unsi gned char *cur r _key;
COMM_8583_DATA *comm_st r uct ;
} VALI DATI ON_STRUCT;

unsi gned char b_amount [ 13] ;

unsi gned char b_t i d[ 9] ;
l ong i nt b_t r ace;
unsi gned char [ 13] ;

These parameters are loaded with the data for the current transaction. This
amounts to a backup of the transaction data, since an inbound message must be
disassembled and the original transaction data is overwritten.

98 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
PIP Functions

unsi gned char *p_amount ;

unsi gned char *p_t i d;
l ong i nt *p_t r ace;

The pointers in the validation structure are there to simplify the references to the
data in the field table. The same addresses could be accessed using the pointer
to the field table in the COMM_8583_DATA structure.
unsi gned char *cur r _key;

Pointer to the application variable containing the key used for the advice file. This
should be the ROC for AMEX host transactions.
COMM_8583_DATA *c omm_st r uct ;

Pointer to simplify referencing the COMM_8583_DATA structure for the validation

routine.

Step 6 - Writ e the After completing the required table and functions described in steps one through
application five, integrate the PIP Engine into the application. Refer to the \TONLINE and
functions to call the \TPRO8583 subdirectories on the installation diskettes for examples of how to call
PIP Engin e
the ISO 8583 and PIP functions.

PIP Func tio ns The PIP functions are described in PIP Engine Function Calls.

VERIX EVO ACT PROGRAMMERS GUIDE 99

PIP E NGINE
Troubleshooting PIP Application Modules

Troubleshooting This section presents problem scenarios and possible solutions.

PIP Appli cation The terminal sends a request, a response is received, but the
Modules Problem
terminal appears to be stuck during receive. The terminal is still
connected to the host.
Solution • The response packet failed the validation routine. Ensure that the
validation structure (see page 98 for example) is loaded with the
correct values. The returned response amount is padded with
leading zeroes. Ensure that these characters are not included in
the validation comparison.
• The terminal may have received a 0820 message (“Please Wait”).
The terminal should wait for the next response packet.
Problem The request packet is not transmitted and the PIP module returns an
error.
Solution • The packet being built exceeds the size of the buffer. Increase the
size of the transmit buffer.
• A variant field table is not set up correctly. The packet assembler
could not find a matching message ID/ processing code pair in
one of the variant tables. Check the variable f n_8583 to
determine which field failed.
Problem The terminal receives a valid response packet, but the PIP module
returns an error.
Solution • The transaction may have been denied by the host. Check the
request packet for errors.
• A destination field is too small to hold the response data. Check
the fn_8583 variable to determine which field failed. Increase the
size of this field.
• The variant field table is not correctly set up. The packet
disassembler may not have found a matching message ID/
processing code pair in one of the variant tables. Check the
variable f n_8583 to determine which field failed.
Problem The request packet has missing or extra fields.

Solution • Additional or missing fields in the response packet can usually be

traced to the bitmap used to build the packet. Extra fields are
caused by the setting (on) of extra bits, while missing fields are
caused by bits not being turned on. Other causes of missing fields
are missing application variable data or an incorrect field table
conversion.
Problem Advice, reversals, TPDUs, and/or bitmap overwritten by the RRN
field.
Solutions • Set v_par m_s i ze in the comm structure to include b _ r r n [ ] in
the validation structure.
Problem The RRN field is not being set on advice and/or reversals.

Solution • The application must set the bitmap of the RRN field even though
RRN does not exist.

100 VERIX EVO ACT PROGRAMMERS GUIDE

PIP E NGINE
PIP/ISO 8583 Glossary

PIP/ISO 8583 Table 5 PIP Term Definitions

Glossary Term Definition
Advice A transaction sent to the host to inform it of some previous action
or offline transaction. On occasion, AMEX uses a stand-in host.
All transactions approved by the stand-in must be forwarded to
the capture host in the form of an advice message.
Bitmap 64 bits numbered from 1 to 64, left to right. One or more
bitmap(s) are required before each ISO 8583 message to
indicate the individual fields that occur in the data packet. Bit one
is an extension bit. If this bit is set, another 64 bitmaps follows.
Bit 64 is reserved as a Message Authenticator Code (MAC). The
MAC field is not used for AMEX transactions.
Closed Batch A batch that is no longer used to store new transactions, but still
contains details of previous transactions. For AMEX batches, a
batch is closed when it is settled with the host. Closed AMEX
batches are deleted and are no longer available.
Conversion Index A reference to an entry in the conver t _t abl e[ ] . Each field
required for the ISO 8583 Message Engine requires a
conversion routine to convert the data from the application data
type format to that used in the ISO 8583 message, and vice
versa. The conversion index is entered into the field table and
the pr ocess_ 8583( ) call uses this index to access the proper
conversion routine for each field as required.
Conversion Table An array containing pointers to routines that convert application
data to the appropriate ISO 8583 fields. This table is required
when using the ISO 8583 Message Engine.
DCP Distributed Credit Authorization System (CAS) Processor. This is
a "stand-in" host used by AMEX when the primary host is
unavailable.
Descriptor Code A set of two-digit numbers assigned to a terminal to describe the
purchases for transactions.
Field Table An array containing information for every field that is either to be
assembled or disassembled during communications with an ISO
8583 host. This field is required by the ISO 8583 Message
Engine. The first two array elements are always reserved for the
TPDU and message ID. The array elements indicate the field
number, packet field size, conversion table index, pointer to the
application variable or variant field table, and the size of the
application variable.
Message Definition A table illustrating the various fields used when communicating
Table with an ISO 8583 host. This table indicates the required and
optional fields, the format for the data, and the length of the data
field. This table generally includes a description of the use of
each of the fields.
Offline Transaction A transaction completed without communication with the host. A
variety of transactions can be completed offline, such as a
transaction that is less that the designated minimum transaction
amount (floor limit).

VERIX EVO ACT PROGRAMMERS GUIDE 101

PIP E NGINE
PIP/ISO 8583 Glossary

Table 5 PIP Term Definitions (continued)

Term Definition
On line Transaction A transaction completed by sending the details of the transaction
to the host and waiting for a host response to determine if the
transaction is approved or denied.
Open Batch The current batch file used to store the details of new
transactions.
Reversal A transaction sent to the host to eliminate or “reverse” the last
Transaction sent transaction. This is usually to correct a problem that
occurred during the transaction such as a time out or loss of
connection.
ROC Record of charge. A physical record of a transaction or receipt. A
ROC can be printed from a terminal with a printer either external
or internal. The ROC is usually signed by the cardholder.
ROC Number A number assigned to a transaction and printed on a receipt for
the cardholder to sign. This number can be preprinted at the
bottom of some AMEX credit or credit forms.
RRN Retrieval Reference Number (field 37). A 12-character unique
reference number assigned to a transaction by the host. This
number references a transaction when further processing is
needed. This field is returned from the host in the response
message.

102 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 9

Data Captur e Engine

The Data Capture Engine provides programmers working in the Verix eVo
operating environment an easy way to manage the transfer of application data to
and from keyed data files. By using the Data Capture Engine, the programmer
eliminates the need to design, code, and test the functionality provided by this
engine.
Using a standard engine also provides the benefit of application maintenance.
Programming with the Data Capture Engine requires less time to implement
enhancements and make other required changes to the application.
The Data Capture Engine relies on the functionality provided by the Verix eVo
standard C Library and the ACL. By making use of these two library sources,
further leverage is gained by reusing functions, thereby further reducing test
efforts and application size.

Keyed File The design of the Data Capture Engine is based on the use of the keyed file
System system provided by Verix eVo. Keyed files contain records identified by a
programmer-specified name or key. This key writes and reads data to and from
the file allowing random access to the individual data records. The Verix eVo
operating system uses compressed variable length records (CVLR) for keyed
files. This introduces two limitations:
• Keyed files employ a data compression mechanism. This limits the type of
data that can be stored in the file. The compression technique converts any
lowercase alphabetic character to its uppercase equivalent, and packs ASCII
digits “0” through “9” into four bits. This limits the data being stored to bytes of
0x5F or less. Bytes greater than 0x5F return a different character when read
from a keyed file.
• The second limitation pertains to the length of the record. The data portion of
each record contains a byte indicating the length of the data as its first byte.
This length includes the length byte. This limits the number of characters that
can be written to a maximum of 254 characters (254 data characters + length
byte = 255); however, these are compressed bytes. Depending on the number
of consecutive numeric character pairs in the data portion of the record, up to
508 characters can be stored (if all characters are numeric).

VERIX EVO ACT PROGRAMMERS GUIDE 103

D A TA C A PTU RE E NGINE

Ap pl ic at ion Da ta

Keyed files can be opened by the application prior to their use, but this is not
required. The file must exist, however. If a specified file is not open at the time
access is required, the file is opened, the requested operation completed, and the
file is closed. There must be a file handle available for the operation to proceed. If
the file does not exist or a file handle is not available, an error value returns.

Applicat ion Most application data is integer, long integer, character, or string data types. This
Data data, residing in RAM, must be stored and retrieved from data files to ensure that
it is not lost in the event of a power failure or similar event. The access of this data
is also random in nature.
The keyed file mechanism provides random access, but the data must be
converted to a compatible format (ASCII) for storage and converted again when
retrieved. These required conversions are accomplished by the Data Capture
Engine.

Data Capt ur e The data capture functions are described in Data Capture Engine Function Calls.
Functions

Example A data capture example program can be found in the Data Capture Engine
Program Example Program section.

104 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 10

Modem Engine

The Application Construction Modem Engine provides programmers an easy way

to manage the modem device. By using the Modem Engine, the need to design,
code, and test the functionality provided by this engine is eliminated.
The Modem Engine relies on the functionality provided by the Standard C Library
and the ACL. By making use of these two library sources, further leverage is
gained by reusing functions, thereby further reducing testing efforts and
application size.

Modem Engi ne The Modem Engine is made up of 27 functions and five macros. These functions
Functions and and macros are general-purpose routines that ease the use and management of
Macros the modem device. Function prototypes, macro definitions, structure declarations,
and #def i nes for many return and error codes are contained in the XMODEM. H
header file (see XMODEM. H Li st i ngs).

Macros The Modem Engine comprises the following macros:

• MDM_READ_BLK(): Obtains the communications parameters.
• MDM_RESET_ERROR(): Resets latched error conditions.
• MDM_STATUS(): Obtains the status of the modem.
• MDM_WRITE_BLK(): Sets the communications parameters.

VERIX EVO ACT PROGRAMMERS GUIDE 105

M ODEM E NGINE
MD M_ READ_B LK()

MDM_READ_BLK()

Reads opened modem device communication parameters into a Modem Opn_Blk

structure. This function can saves the current modem settings to allow single
parameter changes or to restore the modem state at a later time.

Prototype #i ncl ude <XMODEM. H>

i nt MDM_READ_BLK( i nt h_modem, st r uct Opn_Bl k mdm_bl k) ;

Parameters
h_ modem Opened modem device handle.
Opn_Bl k mdm_bl k Communication parameters.

Return Values
Success: SUCCESS: No errors occurred.

Failure: FAILURE: The error type can be determined by checking errno.

NOTE Opn_Blk is a structure of type struct Opn_Blk containing communications

parameters (refer to the target terminals programmers manual for Opn_Blk

structure definition).

Example The linked example code file demonstrates use of MDM_READ_BLK( ) .

MDM_RESET_ERROR()

Resets the latched error conditions of parity, framing, and data overrun. These
conditions remain active until the modem device is reset. This function clears
errors that sometimes occur during connection or resets an error that occurs
during communication.

Prototype #i ncl ude <XMODEM. H>

i nt MDM_RESET_ERROR( h_modem) ;

Parameters
h_ modem Opened modem device handle.

Return Values
Success: SUCCESS: No errors occurred.

Failure: FAILURE: The error type can be determined by checking errno.

Example The linked example code file demonstrates use of MDM_RESET_ERROR( ) .

106 VERIX EVO ACT PROGRAMMERS GUIDE

M ODEM E NGINE
MDM_ STATU S()

MDM_STATUS()

Obtains the opened modem device communication status and copies it to the
global structure s t at us _ i nf o.

Prototype #i ncl ude <XMODEM. H>

i nt MDM_STATUS( i nt h_modem) ;

Parameters
h_ modem Device handle for opened modem.

Retur n Values

Success: SUCCESS: No errors occurred.

Failure: FAILURE: Cannot access modem status.

NOTE
If 0 returns, the modem status is copied to the global structure s t a t us _ i nf o.

The last element of the status array m_st at and contains the current signal
information bit settings set up as follows:

• 0x80: break/abort detected

• 0x40: always zero

• 0x20: CTS detected (not connected, always zero)

• 0x10: RI present (not connected, always zero)

• 0x08: DCD present

• 0x04: frame error detected – latched error

• 0x02: overrun error detected – latched error

• 0x01: parity error detected – latched error

Example The linked example code file demonstrates use of MDM_STATUS( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 107

M ODEM E NGINE
MD M_ WRITE_ BLK()

MDM_WRITE_BLK()

Initializes or resets the modem device communication parameters. The modem

must be initialized after opening before access is allowed.

Prototype #i ncl ude <XMODEM. H>

i nt MDM_WRI TE_BLK( i nt h_modem, st r uct Opn_Bl k mdm_bl k) ;

Parameters
h_ modem Opened modem device handle.
Opn_Bl k mdm_bl k Structure containing communications parameters.

Return Values
Success: SUCCESS: No errors occurred.

Failure: FAILURE: The error type can be determined by checking errno.

NOTE
For Opn_Blk parameters, refer to the target terminals programmers manual.

Example The linked example code file demonstrates use of MDM_WRI TE_ BLK( ) .

108 VERIX EVO ACT PROGRAMMERS GUIDE

M ODEM E NGINE
XMOD EM .H Li stin gs

XMODEM.H Table 6 lists the descriptions of return codes, function parameter constants,
Listings unions, and structures found in XMODEM.H.
Table 6 XMODEM.H Err or Ret urn Codes
#define Value Meaning
E_LATCH -5 Check latched error.
E_ READ_CMD -6 read() function failed.
E_ FW_READ_CMD -6 Modem is opened, read() firmware error
occurred at modem device initialization.
E_ FW_ONLY_ CR -7 Modem opened, firmware status initialize
reply is only <CR>.
E_ONLY_ CR -7 Hayes response returned only a <CR>.
E_HR_TI MEOUT -8 Hayes response function timed out.
E_ FW_TI MEOUT -8 Hayes response firmware time expired.
E_ FW_STATUS -9 Modem opened, Hayes “ERROR” returned
on firmware initialization.
E_WRI TE_ CMD -10 Unsuccessful write(); write() returned -1.
E_NOCARRI ER -11 DCD not present.
E_MI _READ_CMD -14 Modem opened; CONFIG.SYS *MI variable
contains an invalid Hayes command causing
read() to return -1.
E_MI _ONLY_ CR -15 Modem opened; *MI = <CR> as the only
Hayes response during the open.
E_MI _TI MEOUT -16 Hayes response *MI wait timed out during
modem open.
E_MI _STATUS -17 Modem opened; Hayes “ERROR” response
to *MI initialize during the open; invalid
Hayes command in *MI.
E_I NVALI D_RESP -18 Invalid modem response received during
read().
E_ STATUS_CMD -19 Get modem device status failed; ioctl()
returned -1.
E_READ -23 Error reading modem buffer; read() returned
-1.
E_I NPUT_PENDI NG -24 Input waiting at modem.
E_OUTPUT_FAI LED -25 Closing modem device failed due to output
pending from a previous write() to modem.
E_READ_BLK -26 Error reading modem parameters; ioctl()
returned -1.
E_WRI TE_BLK -27 Error writing modem parameters; ioctl()
returned -1.
E_H_FLUSH -28 Error trying to flush Hayes command path.
E_M_FLUSH -29 Error trying to flush modem data path before
the close() device call.
E_CLOSE -31 Failure to close modem device; close()
returned -1.

VERIX EVO ACT PROGRAMMERS GUIDE 109

M ODEM E NGINE
XM OD EM.H Li stin gs

Table 6 XMODEM.H Er ror Ret ur n Codes (continued)

#define Value Meaning
E_OPEN -32 Failure to open modem device, open()
returned -1.
E_PARTI AL -33 Modem sent only part of the buffer.
E_I NVALI D_PARM -34 Invalid parameter passed.
FAI LURE -1 Generic unsuccessful function execution.
E_X_FEATURE_NOT_ SUPPORTED -45 Terminal does not support the feature.
E_ USBMDM_REMOVED -46 USB modem removed.
E_USBMDM_SETSRLFAI LED -47 USB modem set serial failed.
E_WRI TE -35 Failure in writing to the modem.
E_X_OUT_ PEND -36 External modem has output pending.
E_X_I N_SESSN -37 External modem is in data mode.
E_X_MI _TI MEOUT -38 External modem MI response.
E_X_MI _STATUS -39 External modem MI bad response.
E_X_HR_TI MEOUT -40 External modem timeout.
E_X_BAD_RESP -41 External modem bad dial response.
E_X_NOCARRI ER -42 External modem no carrier.
E_X_PARTI AL -43 External modem partial send.
E_X_LATCH -44 External modem latch error.

Tabl e 7 No n-er ro r XMODEM.H Ret ur n Co des

#define Value Meaning
OUTPUT_PENDI NG 1 Output waiting at modem; device is not closed.
I NPUT_PENDI NG 2 Modem not closed; input pending at modem; modem
status byte for input pending is greater than zero.
OUTPUT_FAI LED 3 Modem not closed; failed output records exist from
modem status information.
X_OUTPUT_PEND 4 Modem output pending.
X_I NPUT_PEND 5 Modem input pending.
SUCCESS 0 Successful modem function execution.

Tab le 8 Val id Hay es Nu mer ic Res po ns e Cod es

#define Value Meaning
HAYES_OK 0 Hayes “OK” status returned from read() request.
CONNECT 1 Hayes “CONNECT” (300 baud).
CONNECT_ 300 1 Hayes “CONNECT” 300 baud alternate.
RI NG_DETECT 2 Hayes “RING” status.
NO_CARRI ER 3 Hayes “NO CARRIER” status.
HAYES_ERROR 4 Hayes “ERROR” status.
CONNECT_ 1200 5 Hayes “CONNECT” 1200 status.
NO_DI ALTONE 6 Hayes no dial tone status.

110 VERIX EVO ACT PROGRAMMERS GUIDE

M ODEM E NGINE
XMOD EM .H Li stin gs

Tab le 8 Val id Hay es Nu mer ic Res po ns e Co des (continued)

#define Value Meaning
BUSY_ DETECT 7 Hayes “BUSY” busy detect.
NO_ANSWER 8 Hayes silence not detected.
CONNECT_ 2400 10 Hayes “CONNECT” 2400 status.
CONNECT_ 4800 11 Hayes “CONNECT” 4800 status.
CONNECT_ 9600 12 Hayes “CONNECT” 9600 status.
CONNECT_ 7200 13 Hayes “CONNECT” 7200 status.
CONNECT_ 12000 14 Hayes “CONNECT” 12000 status.
CONNECT_ 14000 15 Hayes “CONNECT” 14000 status.
CONNECT_ 19200 16 Hayes “CONNECT” 19200 status.
CONNECT_ 38400 17 Hayes “CONNECT” 38400 status.
CONNECT_ 57600 18 Hayes “CONNECT” 57600 status.
CONNECT_ 115200 19 Hayes ‘CONNECT” 115200 status.
CONNECT_ 75TX_ 22 Hayes “V.23 originate connection establish” status.
1200RX
CONNECT_ 1200TX_ 23 Hayes “V.23 answer connection establish” status.
75RX
DELAYED 24 Hayes “COUNTRY SPECFIC BLACKLIST” status.
BLACKLI STED 32 Hayes “number dialed is blacklisted” status.
DATA 35 Hayes “data modem connection” status.
CARRI ER_300 40 Hayes “0-300 data rate” status.
CARRI ER_1200_75 44 Hayes “V.23 backward channel carrier” status.
CARRI ER_75_1200 45 Hayes “V.23 forward channel carrier” status.
CARRI ER_1200 46 Hayes “1200 data rate” status.
CARRI ER_2400 47 Hayes “2400 data rate” status.
CARRI ER_4800 48 Hayes “4800 data rate” status.
CARRI ER_7200 49 Hayes “7200 data rate” status.
CARRI ER_9600 50 Hayes “9600 data rate” status.
CARRI ER_12000 51 Hayes “12000 data rate” status.
CARRI ER_14400 52 Hayes “14400 data rate” status.
COMPRESSI ON_ 66 Hayes “MNP CLASS 5 COMPRESSION 2400” status.
CLASS5
COMPRESSI ON_ 67 Hayes “MODEM CONNECT AT V42BIS” status.
V42BI S
COMPRESSI ON_ 69 Hayes “MODEM CONNECT WITH NO DATA
NONE COMPRESSION” status.
PROTOCOL_NONE 70 Hayes “NO ERROR CORRECTION PROTOCOL”
status.
PROTOCOL_LAPM 77 Hayes “PROTOCOL LAPM” status.
PROTOCOL_ALT 80 Hayes “PROTOCOL ALT” status.
VFI _NO_LI NE 90 VeriFone-defined “NO PHONE LINE” status.
VFI _DI ALDONE 91 VeriFone dial done; dialing completed.

VERIX EVO ACT PROGRAMMERS GUIDE 111

M ODEM E NGINE
XM OD EM.H Li stin gs

Table 9 Valid Silicon Laboratories USB Modem Numeric Response

Code
#define Value Meaning
SLABS_OK 0 Silicon Labs Modem "OK" status.
SLABS_CONNECT_300 1 Silicon Labs Modem "CONNECT" (300)
baud.
SLABS_RI NG_DETECT 2 Silicon Labs Modem "INCOMINGRING"
status.
SLABS_NO_CARRI ER 3 Silicon Labs Modem "NO CARRIER" status.
SLABS_SLABS_ERROR 4 Silicon Labs Modem "ERROR" status.
SLABS_CONNECT_1200 5 Silicon Labs Modem "CONNECT 1200"
Status.
SLABS_NO_DI ALTONE 6 Silicon Labs Modem “No dialtone” status.
SLABS_BUSY_ DETECT 7 Silicon Labs Modem “Busy detect”.
SLABS_ NO_ANSWER 8 Silicon Labs Modem “Silence not detected “.
SLABS_RI NGI NG 9 Silicon Labs Modem "RINGING detected”.
SLABS_CONNECT_2400 10 Silicon Labs Modem "CONNECT 2400"
Status.
SLABS_CONNECT_4800 11 Silicon Labs Modem "CONNECT 4800"
Status.
SLABS_CONNECT_9600 12 Silicon Labs Modem "CONNECT 9600"
Status.
SLABS_CONNECT_19200 14 Silicon Labs Modem "CONNECT 19200"
Status.
SLABS_CONNECT_7200 15 Silicon Labs Modem "CONNECT 7200"
Status.
SLABS_CONNECT_12000 16 Silicon Labs Modem "CONNECT 12000"
Status.
SLABS_CONNECT_14400 17 Silicon Labs Modem "CONNECT 14400"
Status.
SLABS_CONNECT_16800 18 Silicon Labs Modem "CONNECT 16800"
Status.
SLABS_CONNECT_21600 19 Silicon Labs Modem "CONNECT 21600"
Status.
SLABS_CONNECT_24000 20 Silicon Labs Modem "CONNECT 24000"
Status.
SLABS_CONNECT_26400 21 Silicon Labs Modem "CONNECT 26400"
Status.
SLABS_CONNECT_28800 22 Silicon Labs Modem "CONNECT 28800"
Status.
SLABS_CONNECT_31200 23 Silicon Labs Modem "CONNECT 31200"
Status.
SLABS_CONNECT_33600 24 Silicon Labs Modem "CONNECT 33600"
Status.

112 VERIX EVO ACT PROGRAMMERS GUIDE

M ODEM E NGINE
XMOD EM .H Li stin gs

Table 9 Valid Silicon Laboratories USB Modem Numeric Response

Code (continued)
#define Value Meaning
SLABS_CI DM 30 Silicon Labs Modem “Caller ID mark
detected”.
SLABS_FLASH 31 Silicon Labs Modem “Hook switch flash”.
SLABS_STAS 32 Silicon Labs Modem “UK CID state tone alert
signal detected”.
SLABS_OVERCURRENT 33 Silicon Labs Modem “Over current condition”.
SLABS_BLACKLI STFULL 40 Silicon Labs Modem “Black list is full”.
SLABS_BLACKLI STED 41 Silicon Labs Modem “Attempted number is
black listed”.
SLABS_NOLI NE 42 Silicon Labs Modem “No phone line is
present”.
SLABS_LI NEI NUSE 43 Silicon Labs Modem “Telephone line in use”.
SLABS_POLARI TYREVERSAL 44 Silicon Labs Modem “Polarity reversals was
detected “.
SLABS_NOPOLARI TYREVERS 45 Silicon Labs Modem “Polarity reversals was
AL not detected”.
SLABS_CONNECT_ 56000 52 Silicon Labs Modem "CONNECT 56000"
Status.
SLABS_CONNECT_ 32000 60 Silicon Labs Modem "CONNECT 32000"
Status.
SLABS_CONNECT_ 48000 61 Silicon Labs Modem "CONNECT 48000"
Status.
SLABS_CONNECT_ 28000 63 Silicon Labs Modem "CONNECT 28000"
Status.
SLABS_CONNECT_ 29333 64 Silicon Labs Modem "CONNECT 29333"
Status.
SLABS_CONNECT_ 30666 65 Silicon Labs Modem "CONNECT 30666"
Status.
SLABS_CONNECT_ 33333 66 Silicon Labs Modem "CONNECT 33333"
Status.
SLABS_CONNECT_ 34666 67 Silicon Labs Modem "CONNECT 34666"
Status.
SLABS_CONNECT_ 36000 68 Silicon Labs Modem "CONNECT 36000"
Status.
SLABS_CONNECT_ 37333 69 Silicon Labs Modem "CONNECT 37333"
Status.
SLABS_ PROTOCOLNONE 70 Silicon Labs Modem “No protocol”.
SLABS_CONNECT_ 75 75 Silicon Labs Modem "CONNECT 75" Status.
SLABS_PROTOCOLV42 77 Silicon Labs Modem “V.42 protocol“.
SLABS_PROTOCOLV42BI S 79 Silicon Labs Modem “V.42bis protocol”.
SLABS_ MNP2PROTOCOL 80 Silicon Labs Modem “MNP2 protocol”.
SLABS_MNP3PROTOCOL 81 Silicon Labs Modem “MNP3 protocol“.

VERIX EVO ACT PROGRAMMERS GUIDE 113

M ODEM E NGINE
XM OD EM.H Li stin gs

Table 9 Valid Silicon Laboratories USB Modem Numeric Response

Code (continued)
#define Value Meaning
SLABS_ MNP4PROTOCOL 82 Silicon Labs Modem “MNP4 protocol”.
SLABS_MNP5PROTOCOL 83 Silicon Labs Modem“MNP5 protocol“.
SLABS_CONNECT_38666 90 Silicon Labs Modem "CONNECT 38666"
Status.
SLABS_CONNECT_40000 91 Silicon Labs Modem "CONNECT 40000"
Status.
SLABS_CONNECT_41333 92 Silicon Labs Modem "CONNECT 41333"
Status.
SLABS_CONNECT_42666 93 Silicon Labs Modem "CONNECT 42666"
Status.
SLABS_CONNECT_44000 94 Silicon Labs Modem "CONNECT 44000"
Status.
SLABS_CONNECT_45333 95 Silicon Labs Modem "CONNECT 45333"
Status.
SLABS_CONNECT_46666 96 Silicon Labs Modem "CONNECT 46666"
Status.
SLABS_CONNECT_49333 97 Silicon Labs Modem "CONNECT 49333"
Status.
SLABS_CONNECT_50666 98 Silicon Labs Modem "CONNECT 50666"
Status.
SLABS_CONNECT_52000 99 Silicon Labs Modem "CONNECT 52000"
Status.
SLABS_CONNECT_53333 100 Silicon Labs Modem "CONNECT 53333"
Status.
SLABS_CONNECT_54666 101 Silicon Labs Modem "CONNECT 54666"
Status.
SLABS_UNOBTAI NABLENUM 102 Silicon Labs Modem “Unobtainable number “.

NOTE
This is applicable only for Vx670 terminal. For more information, refer to the
Silicon Laboratories Reference Manual.

Table 10
z
Latched Modem Device Data Error Conditions
#define Value Meaning
E_PARI TY 1 Parity error on data received.
E_ OVERRUN 2 Data overrun error on data received.
E_PARI TY_ OVERRUN 3 Parity and data overrun error on data received.
E_FRAMI NG 4 Framing error on data received.
E_PARI TY_FRAME 5 Parity and framing error on data received.

114 VERIX EVO ACT PROGRAMMERS GUIDE

M ODEM E NGINE
XMOD EM.H Str uc tu res an d Un io ns

Table 10 Latched Modem Device Data Error Conditions (continued)

#define Value Meaning
E_ FRAME_ OVERRUN 6 Framing and data overrun error on data
received.
E_PARI TY_ FRAME_OVERRUN 7 Parity, framing, and data overrun errors
received.

Table 11 XMODEM.H Valid Communication Protocol Attribute

Requests
#define Value Meaning
MDM_BAUD_RATE 1 All request to change the opened modem device baud rate.
MDM_FORMAT 2 All request to change the opened modem device data
format.
MDM_PROTOCOL 3 All request to change the opened modem device protocol.
MDM_SDLC_TYPE 4 SDLC request to change the opened modem device SDLC
parameter.
MDM_STX_ CHAR 5 Packet request to set the opened modem device STX
character flag.
MDM_ETX_ CHAR 6 Packet request to set the opened modem device ETX
character flag.
MDM_COUNT 7 Packet request to set the opened modem device packet
count.
P_ CUSTOM 15 N/A custom protocol contained in application-defined
function while setting protocol.

XMODEM.H The following structures and unions are used by functions and macros to set or
Structures and retrieve mode device parameters.
Unions

union all_protocols Used by xmdm_init() and xmdm_set_protocol() to change or set the modem

device parameters. all_protocols is a union of the possible structures of each
protocol type.
uni on al l _pr ot ocol s
{
st r uct s_char / * Charact er mode pr otocol */
{
i nt r at e; / * Baud r at e * /
i nt f or mat ; / * Dat a f or mat ( par i t y, # dat a bi t s, #st opbi t s) */
} char _mode;
st r uct s_packet / * Packet mode pr otocol */
{
i nt r at e; / * Baud r at e * /
i nt f or mat ; / * Dat a f or mat */
i nt stx_char ; / * Packet start of t r ansmi ssi on char acter */

VERIX EVO ACT PROGRAMMERS GUIDE 115

M ODEM E NGINE
Mo de m Func ti on s

i nt et x_char ; / * Packet end of t r ansmi ssi on char act er */

i nt count ; / * Packet checksum used: 0, 1, or 2*/
} pkt _mode;
st r uct s_sdl c / * SDLC Pr ot ocol */
{
i nt r ate; / * SDLC connect baud r ate */
i nt f ormat; / * SDLC data f ormat */
} sdl c_ mode;
st r uct cust om / * Cust om Pr ot ocol */
{
i nt cust var A; / * Cust om pr ot ocol var i abl es*/ i nt cust var B;
i nt cust var C;
i nt cust var D;
i nt ( * cust om_i ni t ) ( ) ; / * Cust om pr ot ocol f uncti on addr ess */
} cus t om_mode;
};

struct reject_struct The reject record structure used by MDM_RESET_ERROR() macro while calling
ioctl().
s t r uc t r e j ec t _ s t r uc t
{
char *buf _addr ;
/ * Locat i on t o stor e rej ect queue recor d */
i nt buf _ s i z e;
/ * Si ze of r ej ect queue r ecor d st or age l ocat i on */
};

struct stat_struct The modem status structure used by ioctl() during xmdm_check_status(),
xmdm_input_pending(), xmdm_failed_output_pending() and
xmdm_output_pending() to store the current modem status.
struct stat_struct
{
unsi gned char m_st at [ 4] ;
unsi gned char max_sl ot s;
};

Modem The modem functions are described in Modem Engine Function Calls.
Functions

Example A Modem Engine example program can be found in the Modem Engine Example
Program Program section.

116 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 11

Report Formatter

Most VeriFone applications are required to send formatted data to a printer or

display. The most common examples of formatted data are sales receipts and
batch reports. The AC report engine simplifies the task of formatting data for
display or printer output.
The AC report conversion utility, FORMCVT. EXE, is a PC-based program that
generates a binary template file from an ASCII report format file. The ASCII report
format file contains information defining the layout, variables, and print
characteristics that define a report; it can be created using any ASCII text editor.
Based on the information stored in the binary template file, the report engine
formatter handles all formatting of data, buffer positioning, and sending of lines
and special commands to a device driver. This approach to report generation
reduces and even eliminates the need to modify application code when report
formats change, since all of the formatting information is stored in a file
independent of the application code.
This section discusses the usage of the report formatter functions. These
functions are called in a C application to generate reports. Design of an ASCII
report format file and generation of a binary template file is also discussed.
The report formatter consists of a set of general functions that format and output
data. To use the formatter, the application must specify:
• what data to format,
• how to format the data, and
• where to output the formatted data.
The report conversion utility, FORMCVT. EXE, assists in answering the first two
questions. FORMCVT uses a file (GVARS. H) that defines report global variables
and an ASCII report format file (APPLI C. H) to generate a variable index file and a
binary template file for the report.
The FORMCVT header files GVARS. H (provided by the programmer) and
APPLIC.H (produced by FORMCVT) files are used by the application and the
report formatter to define variables used in the report. The binary template file is
used by the report formatter to determine how to format the variable data.
The report formatter determines where to send the formatted data based on an
output initializer function. This function name is provided to the formatter at the
start of the report.

VERIX EVO ACT PROGRAMMERS GUIDE 117

R EPORT F ORMATTER
In co rpor at in g th e Re po rt En gi ne in an Appl icat io n

The output initializer function (called by f or mat er _open( ) ) accepts a pointer to

a FORMATER structure, defined in <FORMATER. H>, as an input parameter. The
output initializer function is responsible for initializing the following members of the
FORMATER structure:
di r ec t If 1, there is a direct interface to the output device and the
report formatter should monitor system buffer usage.
Otherwise, a spooled interface is used.
h_comm_por t Handle for the communications port.
( *out put _cl ose) ( ) Device close function.
( * out put _ pr i nt ) ( ) Device output line function.
( *out put _mode) ( ) Driver-dependent codes conversion function.

In addition, the output initializer function should perform any device initialization.
Sample output initializer functions are provided with the report engine. These
sample functions initialize direct output through an Application Construction
printer driver to the ITP of the terminal.

Incorporating The following steps show how to use the report conversion utility and report
the Repor t formatter.
Engine in an 1 Create an ASCII report format file and corresponding GVARS.H file.
Applicat ion
All variables referenced in the report format file must be defined in GVARS. H.
GVARS. H may also contain other variables not referenced in the report
format file. See the global variables declaration file.
2 Run the report engine conversion utility, FORMCVT, to convert the ASCII
Report Format file to a binary template file.
FORMCVT generates a variable index file, APPLI C. H.

FORMCVT command line syntax is as follows:

f or mcvt TEMPLATE[ . TXT] [ - f TEMPLATE. FRM] [ - hAPPLI C. H]

3 Determine the output initializer function(s).

An output initializer function initializes the variables that specify functions
interfacing with the output device; it also opens and initializes the output
device. The output initializer functions listed in step four are provided with the
report engine for a direct interface to the following printers: P150DIR.C,
P250DIR.C, and so on.
4 Use the following functions to generate a report from the application:

• f or mat er _open( ) : Initializes the report by opening the specified binary

template file and calling the specified output initializer function.
• f or mat er _set _f l ags( ) : Builds an unsigned long bitmap flag for report
templates that contain conditional lines.

118 VERIX EVO ACT PROGRAMMERS GUIDE

R EPORT F ORMATTER
Conditional Printing

• f or mat er _l i ne( ) : Outputs one or more report lines.

• f or mat er _cl ose( ) : Closes the binary template file and output device.
5 Compile the application modules.

These modules include GVARS. H and APPLI C. H.

6 Link the application modules with the report engine formatter module
FORMATR3. G or FORMATR4. G and any device driver module, such asDR3. G
or DR4. G, to create a downloadable file.
7 Download this file along with the binary template file(s) to the terminal.

For instance, an application can consist of one . OUT file and four template
files. To download this application:
a Create an ASCII text file called DOWNLD. SYS. The contents of the file can
be:
I AMEX001. OUT
I SPOT. FRM
I EOD. FRM
I EOF. FRM
I RECEI PT. FRM

In this example, AMEX001. OUT is the downloadable application, the rest are
report template files.
b Type the following command at DOS prompt:
DDL - FDOWNLD. SYS

Conditional The AC report engine supports conditional printing. At report generation, the
Printing report engine formatter determines which lines are printed by comparing a user-
defined condition variable (see Report Formatter Example Program) with
corresponding conditional codes in the template file. If the conditions evaluate to a
Boolean true value, the line prints. This allows a variety of reports to be generated
using a single template.

Report This utility is a stand-alone program running under the DOS operating system.
Conversion The command line FORMCVT syntax is as follows:
Utility FORMCVT I NPUT_FI LE[ . TXT] [ - f TEMPLATE. FRM] [ - hTEMPLATE. H]
• I NPUT_FI LE is the ASCII report format file that contains the report format. If
the extension is omitted, it defaults to . TXT.
• - f specifies an alternate binary output filename. If this option is omitted, the
template filename is the same as the input file name with a . FRMextension.
• - h specifies an alternate output variable index filename. If this option is
omitted, FORMCVT generates an index filename APPLI C. H. This file is used
by the report engine functions; do not change these functions.

VERIX EVO ACT PROGRAMMERS GUIDE 119

R EPORT F ORMATTER
Re po rt Form at File Gu id el in es

FORMCVT also requires the input variable definition file GVARS. H. FORMCVT
assumes this file exists in the current directory. GVARS. H contains the definitions
of all variables referenced in the report format file. If an application uses multiple
binary template files, GVARS. H contains the cumulative definitions for all the
global variables used in these reports.

NOTE
GVARS. H and APPLI C. H must be included the application at compile time.

Repor t Format A report format file is a FORMCVT ASCII input file that defines the layout,
Files variables and print characteristics for a report. FORMCVT then generates the
corresponding binary file used by the report engine formatter during report
generation.
Some examples of report layout commands are “center a literal string” and “left
justify a variable”. Examples of print characteristic commands are “print in red”
and “print in compressed mode”. All commands supported by FORMCVT are
listed in Report Format File Guidelines.
To include global variable values in a report, the variable names must be
referenced in the report format file. These variables must also be provided to
FORMCVT in GVARS. H. At report generation, the report engine formatter formats
these variable values in the report.
The report format file and GVARS.H can include the following types of variables:
• character (char)
• string (character array)
• integer
• long integer
• structure elements (the structure path must be provided)
• array (of any type)
Floating point and double types are not supported. To include floating point values
in a report, declare the report variable as a string and format the floating point
value in the string before calling the report engine formatter.

Repor t Form at The following rules apply to the format and content of each line of the ASCII report
File Guidelines format file. References are made to the example format file.
1 Start each report line with a line number.

Valid line numbers range from 1 to 127. Leading zeros are not required, but
can be added for text alignment.

Line numbers do not have to be sequential, but each must be greater than or
equal to previous line number. Skipped line numbers can be printed as blank
lines or simply ignored.

120 VERIX EVO ACT PROGRAMMERS GUIDE

R EPORT F ORMATTER
Re po rt Form at File Gu id el ines

In the Example Format File, note that line 3 has been skipped. A parameter
in the call to f or mat er _l i ne( ) within the application specifies how lines 3,
9, 14, and 17 are printed: either as blank lines or skipped.

At report generation, the report engine formatter can be instructed to print
one line or a number of lines. Lines can also be reprinted any number of
times.
2 The character immediately following the line number must be a colon (:), an
ampersand (&), or an equal sign (=).
Both the ampersand and the equal sign indicate that the line is conditional,
and they are followed by a value defining this condition. The colon signals
the end of the conditional portion and the beginning of the text portion of the
line.

Conditional values can be specified in three forms: “B” (binary), “D”

(decimal), or “X” (hexadecimal). For example, the following values are
equivalent:

&X000A

&B1010
&D0010

All values are numerically right justified, making these values also equivalent
to:

&X00000001
&X000001

&X1

At report generation, a four-byte, bitmap-conditional flag is passed to the

report engine formatter. This value is logically ANDed with the conditional
value of lines with an ampersand conditional operator, or compared for a
match with the conditional value of lines with an equal sign conditional
operator. The line prints, if the ampersand/AND or the equal/MATCH is
TRUE.

When multiple conditionals are defined for a given line number, the first one
evaluating to true prints. At this point, the report engine formatter begins
processing the next sequential line number in the sequence.

NOTE
A line number followed only by a colon always evaluates to true.

VERIX EVO ACT PROGRAMMERS GUIDE 121

R EPORT F ORMATTER
Re po rt Form at File Gu id el in es

Example 01&X1: " ONE"

01: " TWO"
01&X2: " THREE"
02=X02000301: " FOUR"
02: " NEXT"

In this example, assume a conditional value of 0x02000301 is passed to the

report engine formatter.
The result of ANDing 0x02000301 and 0x00000001 (from the first line in the
example) evaluates to TRUE, and so the string constant “ONE” prints. The
formatter then skips to the line number 02. The result of matching
0x02000301 to 0x02000301 evaluates to TRUE, so the string constant
“FOUR” prints.

If a conditional value of 0x01000000 is passed to the report engine formatter,

the string constants “TWO” and “NEXT” print because the second and fifth
lines in the example are the first (and in this case, the only) lines in each line-
set to evaluate to TRUE.
It is important to note that the string constant “THREE” is never printed,
because the second line (TWO) always evaluates to TRUE.
3 Use standard C-style comments (/* */) in GVARS.H and the report format file.

In GVARS.H, the comments can appear anywhere in the file, except

preceding a variable on the same line.

Acceptable:
i nt i t em; / * I t em Pur chase Number * /

Unacceptable:
/ * I t em Pur chase Number * / i nt i t em;

In the report format file, a comment must occupy the entire line. Embedded
comments are not allowed.

Acceptable:
/ * The next l i ne i s l i ne one */
01&X0001: 1. 40, \ Cmer chant

Unacceptable:
01&X0001: 1. 40, \ Cmer chant / * l i ne 1 */

For ease of reading, white space characters (blank lines, spaces, tabs, and
so on) can be used in these files.

NOTE
In the GVARS. H file, variable declarations must start in column one.

122 VERIX EVO ACT PROGRAMMERS GUIDE

R EPORT F ORMATTER
Re po rt Form at File Gu id el ines

4 Each line in the report format file is composed of fields.

The first field begins immediately after the colon that terminates the
conditional value. Subsequent fields are separated by semicolons (;). Each
line can contain multiple fields.

In the example, Example Format File, line 2 uses only the first field, while line
10 uses the first and second fields.

Each field follows the following rules of syntax:

[ s t a r t . end, ] [ opt i ons ] {gl obal _ var }
{[ opt i ons ] s t r i ng}

start Represents the printer column where the field begins.

end Represents the printer column where the field ends.
opt i ons Represents any of the special print characteristics that can be used.

Only one data element can be specified per field. This can be either of the
global variables defined in GVARS. H or a string constant.

Example 01: 1. 13, \ Ct emp

The value of t emp is centered on the first line of the report starting in column
one and ending in column 13.
01: 1. 13, \ Ct emp; 20. 30, " \ W\ CTESTI NG"

The string TESTING prints double-wide (\W) and centered in the field (\C)
between columns 20 and 30.

NOTE The starting and ending column numbers must be separated by a period and must
be in range for the printer device used. A comma (,) must follow the ending
column number.

5 Starting and ending column numbers must be specified for every field.

This makes the template easier to maintain and eliminates positional

ambiguities. However, when printing a string constant, only the starting
column of the field must be specified. The formatter begins printing at the
fields starting column and continues until the end of the string is reached, or
to the maximum width allowed by the printer.

If the width of a field exceeds the width defined by the starting and ending
columns, the field is truncated.

The default justification for global variables is right justified.

The default justification for string constants is left justified.

VERIX EVO ACT PROGRAMMERS GUIDE 123

R EPORT F ORMATTER
Re po rt Form at File Gu id el in es

6 Special print characteristics and layout commands are expressed in the form
of a two-character string, “\X”, where X is any one of the following:
A: Print the following string or variable in Arabic.
B: Print the following string or variable in black.
C: Center the following string or variable in the specified column range
preceding this command.
D: Print the following string or variable in red.
E: Turn off printing in red.
F: Set the character size to 5 x 7 and enable underline printing.
G: Print logo file.
H: Print the following string or variable in double height.
I: Reinitialize the printer.
J : Set the character size to 7 x 7.
L: Left justify the following string or variable in the specified column
range preceding this command.
N: Restore the printer to normal printing mode.
P: Eject six blank lines in the printer.
R: Right justify the following variable or string in the specified column
range preceding this command.
S: Enable printing in compressed mode.
T: Select font size and font table.
W: Print the following string or variable in double width.
X: Hexadecimal printing using the selected font table.
Z: Use ASCII character set.

%(percent) Specifies the pad character to use when printing variables. The
default pad character is a space (ASCII 32). This character pads the
width of the field regardless of justification.

These special print characters can be specified in or out of the literal strings.
In the example, line 1 centers and prints the contents of the global variable
merchant in double width.

Line 13 of the example prints the literal string “TOTAL: $”, also in double
width.

Errors If FORMCVT detects any errors, it displays an error message and aborts the
parsing operation.

124 VERIX EVO ACT PROGRAMMERS GUIDE

R EPORT F ORMATTER
Ex am pl e Fo rmat Fi le

Example An example demonstrating the use of conditional lines is given in the sample
Format File format file.

Global All the variables shown in the Example Format File must be declared in the global
Variables variables declaration file GVARS.H.
Declaration Each line in this file should contain only one variable declaration, and each
File declaration must start in column 1. C-style comments are allowed in this file, with
the exception that comments cannot be placed in front of variables.
/ * decl ar at i ons f or gl obal var i abl es used i n t he repor t */
i nt i t em;
char amount [ 13] ;
char t i p[ 13] ;
char t ot al [ 13] ;
char mer chant [ 20] ;
char dat e_t i me[ 20] ;
char t _car d_acct[ 30] ;
char t _card_exp[ 5] ;
char t _aut h_code[9] ;
char t _i nvoi ce[ 7] ;

Data Structures The following Global #defines table, defines the global variables found in file
APPLIC.H.

Global #defines The following are defined in the file APPLIC.H:

Table 12 Global #defines
#Define Value Meaning
G_C 1 Indicates a variable of character type.
G_S 2 Indicates a string variable.
G_I 3 Indicates a variable of integer type.
G_L 4 Indicates a variable of long integer type.

Global Structures The following structure is used by the report formatter to store the information
about all global variables used in the report generation process.
t ypedef st r uct
{
voi d *addr ;
i nt t ype;
} g_dat a;
g_dat a data[ ] ;
The address of the variable is stored in the first element of this structure and the
type, as shown in the Global #defines section above, is stored in the second
element, t ype. The number of elements in dat a[ ] is application dependent.

VERIX EVO ACT PROGRAMMERS GUIDE 125

R EPORT F ORMATTER
Re po rt Form at te r Fu nc tion s

Sampl e Outp ut The following sample receipts demonstrate the use of conditional true and
conditional false output, and are based on the examples provided on the
preceding pages.

Report The report formatter functions are described in Report Formatter Function Calls.
Formatter
Functions

Example A report formatter example program can be found in the Report Formatter
Program Example Program section.

126 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 12

Database Libr ary

The Database Library supports database file operations (for example, open, read,
write, and delete) with key-based search of data records.
The Database Library provides function calls to create and manipulate a
database. This library is based on an index (keyed) file system to allow specified
search key(s) to access individual records in the database. These search keys
provide random access to the database. There are two major advantages in using
this keyed file system:
• A structure can be defined for an index (key) file. The structure contains the
list of search keys required to access the database records (for example, card
number and server ID). Utilization of search keys provides a fast access
method into the database.
• Database records can be compressed externally to save system memory.

Database The Database Library:

Features • allows random access to the database records through an index file,
• stores variable length records in database files,
• handles compressed records, and
• provides sequential access (in both the forward and backward directions) to
the data records.

File Formats Database and index file formats are discussed in this section.

Database Fil e The database contains variable length records. Each record is composed of a
Format forward length component, the actual data, and a backward length component.
This record format is referred to as Double Variable Length Record (DVLR). The
DVLR format allows searching the database in both directions, forward and
backward.

Figure 4 DVLR Format

Figure 4 shows the DVLR format of a data record. FLEN stands for forward length,
and BLEN for backward length. Both the FLEN and BLEN are two bytes. Data
Record indicates the actual data stored.

VERIX EVO ACT PROGRAMMERS GUIDE 127

D A TA B A SE L IBRARY
File Storage Structure

Index File Format Each time a database file is open (create) using the API call db_open(), a
corresponding index (keyed) file is created. Each index file record includes the
search keys used to access records in the database. The minimum requirement
for each index file record is a field of LONG used to store the offset address of the
associated database record. The index record format can be expanded by adding
fields to define each search key. The following example illustrates an index file
record structure:
t ypedef st r uct
{
l ong r ec_ num;
shor t whi ch_t r ack; / / 0 = Manual ent r y, 1 = Track 1, 2 =
Tr ack 2
char host no[ 3] ; / / Host number
c har s er ver [ 4] ; / / Ser ver I D
char t i cket [ 29] ; / / Ti cket number , aut o_downl oad f i el d
char Card_t ype[3] ; / / Two charact er car d t ype
}DB_I DX_KEY

When calling db_ open( ) , si zeof ( DB_I DX_KEY) should be used as the parameter
for key length.

File Storage Figure 5 shows the file storage structure. Header, Rec1, Rec2, and Rec3
Structure represent the index records. Data Rec 1, 2, and 3 represent the data portion of the
records. Each data record consists of FLEN, Data Rec, and BLEN. Each index
record stores the offset for a particular data record.
For example, Rec1 stores an offset value of 0. Assume the length of Data Rec 1 is
21, then,
FLEN+Length of Data Rec 1+BLEN = 25 or (2+21+2 = 25)
where, FLEN = BLEN = 2 bytes.
Now, Rec2 stores an offset value of 25. Similarly, if the length of Data Rec 2 is 50,
Rec3 stores an offset value of 25+(2+50+2) = 79. So, if a data record is deleted in
the database, the corresponding data and index records are removed and only
the offsets are recomputed.

Figure 5 File Storage Structure

128 VERIX EVO ACT PROGRAMMERS GUIDE

D A TA B AS E L IBRARY
Da taba se Li brary Fu nc ti on s

NOTE
The record numbers start at zero. The delete operation slows down the application
as the offsets must be updated.

File Compression Although the Database Library can read and write compressed records, a
compression function is not provided in this library. Compress or decompress
database records prior to calling any of the Database Library functions.

Database The Database Library functions are described in Database Library Function Calls.
Library
Functions

VERIX EVO ACT PROGRAMMERS GUIDE 129

D A TA B A SE L IBRARY
Da ta ba se Li brary Fu nc ti on s

130 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 13

Printer Drivers

The printer driver provides an easy way to manage printing and use various
printer attributes provided.
Various types of printing supported by the printer driver are as follows:
• LOGO type printing
• Printer Font Type printing (PFT)
• Printing monochrome bitmaps

Veri x eVo The ITP is a thermal array printer that communicates with the host terminal
Based Termin al through the RS-232 port. The data format of the ITP is fixed at 8 bits, no parity, 1
ITPs stop bit (8N1) at 19200 bps. It has 64 font tables used to download user-defined
fonts for printing.
The ITP has the following additional features:
• Downloadable user fonts
• Downloadable user logo

Downloadable Lists the sizes of the fonts that can be downloaded to the Verix eVo based
User Fonts terminal ITPs.
Table 13 Font Sizes
Bytes Per Font Tables
Font Resolution Font Size
Character Required
5X8 2 8 1
8X14, 42 column modea 3 14 2
8X14, 32 column mode 4 14 2
16X16 1 32 4
24X24 5 72 9
32X32 6 128 16
48X48 7 288 36
64X64 8 512 64
a. Indicates the default font when the printer is powered on.

VERIX EVO ACT PROGRAMMERS GUIDE 131

P RINTER D RIVERS
Do wn load ab le Pri nt er Lo go

Font Table 0 is reserved for built-in fonts, such as 5 x 8 in 24 column mode, 8 x 14

in 42 column mode, and 8 x 14 in 32 column mode. User font loads can start from
font table 1 through table 64. The user must specify where to load the different
font tables for use by the application. For example, if the user downloads a 16 x
16 font at font table 1, the next available font table for a new font download is 5
because the 16 x 16 font occupies four font tables.
As the fonts download into the flash of the printer, they are not erased from
memory even if the printer is switched off. However, fonts can be overwritten by
downloading new fonts to the same font table.

Downloadable The ITP can handle logos of various sizes, with a maximum dimension of 384
Printer Logo horizontal dots by 240 vertical dots (384X240). Only one image can be
downloaded at a time to the ITP.

NOTE
Downloading a new logo into the ITP erases the any other logo stored in flash.

The distinctive features of the ITP are:

• Selectable characters-per-line through the <ESC> F command; one of 42, 32,
or 24 lines.
• User-defined graphics download through the <ESC> g command.
• Remote self-test through the <ESC> s command.
• User-defined logo download.
• Printer firmware download.

NOTE
The printer ID for the Vx520 and Vx680 will be P.

Printing This feature enables printing of monochrome bitmaps independent of the printers.
Monochrome This feature is supported in Verix eVo terminals.
Bitmap • Printing Monochrome Bitmap

Printer Driver The printer driver functions are described in the following section:
Functions • Print Pak 3700 Function Calls

132 VERIX EVO ACT PROGRAMMERS GUIDE

P RINTER D RIVERS
Ex ampl e Program

Example The following is the example program of printer driver:

Program • P3700 Example Program

VERIX EVO ACT PROGRAMMERS GUIDE 133

P RINTER D RIVERS
Ex am pl e Progr am

134 VERIX EVO ACT PROGRAMMERS GUIDE

CHAPTER 14

Function Calls

This chapter discusses the AC Library Function Categories and provides function

call descriptions for the following modules:
• AC Library Function Calls
• DVLR Function Calls
• IVLR Function Calls
• SVC Function Calls
• Application Idle Engine Function Calls
• Message/Data Entry Engine Function Calls
• ISO 8583 Message Interface Engine Function Calls
• PIP Engine Function Calls
• Data Capture Engine Function Calls
• Modem Engine Function Calls
• Report Formatter Function Calls
• Database Library Function Calls
• Print Pak 3700 Function Calls

VERIX EVO ACT PROGRAMMERS GUIDE 135

F UNCTION C A L L S
AC Librar y Fu nc ti on Cate go ries

AC L ibrar y The functions in this library are organized into one of four functional groups:
Function • string,
Categories
• console I/O,
• device, and
• utility.
The level for each group indicated in the following table, refers to the functional
level of the routine. The AC Library is self-referencing, meaning that some
functions in the library depend on other functions also in the library. Understanding
function levels helps to show the relationship of one function to others in the
library. The four groups are as follows:

Level Description
0 Macros that do not depend on any ACL function.
1 Compiled C functions that can use level 0 macros.
2 Functions that use at least one function from level 1.
3 The most complex functions in the ACL — can use ACL functions from any
level.

Each function in the AC Library is listed by category and level in Table 14.
Table 14 Verix eVo ACT Library Functions by Category
Function Level Function Level Function Level

Consol e I/O
File Functi ons
Functions
delete_dvlr/ivlr 3 scroll_buffer 2
do_compression 3
insert_dvlr/ivlr 3 beep 1
read_dvlr/ivlr 3 bitfun 1 str2dsp_len 1
seek_dvlr/ivlr 3
write_dvlr/idvlr 3 display 1 view_buffer 3
Device
Functions
card_parse 3 display_at 2 String
Functions
chk_card_rdr 1 append_char 1
CHK_TIMEOUT 0 display_new 2 atox1
clock2int 3 2 chars2int 1
clock_data 3 dsp_strs 2 chk_luhn 2
ERR_BEEP 0 ctons1 1
p_set_baudformat 1 getkbd_entry 3 delete_char 1
3 f_dollar 2
set_itimeout 2 1 fieldcnt 1

136 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
AC Libr ary Fu nc tion Cate go ries

Table 14 Verix eVo ACT Library Functions by Category (continued)

Function Level Function Level Function Level
SLEEP 0 getxy 1 fieldfix 1
track_parse 2 1 fieldray 1
KBHIT 0 fieldvar 2
Utility KBHIT_ALT 0 insert_char 1
Functions
cvt_ym 3 keyin_amt_range 3 insert_decimal 3
julian_date 2 keyin_mapped 1 int2str 2
LEAP_YR 0 long2money 3
load_bmp 3 NORM_BEEP 0 long2str 3
MAX 0 pause 1 mult_strcat 1
MEMCLR 0 ntocs 1
MIN 0 prompt 3 pad 2
month_end 2 purge_char 1
range_vlr 3 prompt_at 3 range 3

VERIX EVO ACT PROGRAMMERS GUIDE 137

F UNCTION C A L L S
AC Librar y Func ti on Call s

AC L ibrar y This section describes the following AC library function calls:
Function Calls
• act_kbd_pending_test() • fieldfix() • NORM_BEEP()

• append_char() • fieldray() • ntocs()

• atox() • fieldvar() • p_set_baudformat()

• beep() • getkbd_entry() • pad()

• bitfun() • getxy() • pause()

• card_parse() • insert_char() • prompt()

• chars2int() • insert_decimal() • prompt_at()

• chk_card_rdr() • int2str() • purge_char()

• chk_luhn() • julian_date() • range()

• CHK_TIMEOUT() • KBHIT() • range_vlr()

• clock_data() • key_card_entry() • scroll_buffer()

• clock2int() • keyin_amt_range() • set_itimeout()

• ctons1() • keyin_mapped() • sgetf()

• cvt_ym() • LEAP_YR() • SLEEP()

• delete_char() • load_bmp() • sputf()

• display() • long2str() • strn2int()

• display_at() • MAX() • str2digit()

• display_new() • MEMCLR() • str2dsp_len()

• do_compression() • msg_display_at() • str2int()

• dsp_strs() • msg_display_new() • str2long()

• ERR_BEEP() • MIN() • set_chars_per_key_value()

• f_dollar() • month_end() • track_parse()

• fieldcnt() • mult_strcat() • view_buffer()

138 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
act_kbd_pending_test()

act_kbd_pending_test()

Checks if the target character is present in the keyboard buffer.

Prototype #i ncl ude <act ut i l . h>

i nt act _kbd_pendi ng_t est ( i nt t ar get code) ;

Parameters
t arget code Character key code to be checked by the function. Valid values are:
• KEY_ CANCEL
• KEY0 to KEY9
• KEY_a to KEY_g

Retur n Values
Success: 1: The target character is present in the keyboard buffer.

Failure: 0: Target character is not present in the keyboard buffer.

append_char()

Accepts a pointer to a null-terminated string specified by string, and appends a

character specified by c .
If the buffer passed is an empty string, the character is inserted as the first
character of the string. The buffer is unaffected if the passed character is null.

Prototype #i ncl ude <acl st r . h>

i nt append_char ( char *st r i ng, char c) ;

Parameters
s t r i ng Buffer with null-terminated string.
c Character to append.

Retur n Values Length of the string, including the appended character.

Dependencies Verix eVo SDK

NOTE
Bounds checking are not performed. The calling routine is responsible for
ensuring that space is available for the additional character.

See Als o insert_char(), delete_char(), purge_char(), pad()

Example The linked example code file demonstrates use of append_char(). Also see the
example in the EXTRANS.C section.

VERIX EVO ACT PROGRAMMERS GUIDE 139

F UNCTION C A L L S
atox()

atox()

Converts an ASCII hex character to a binary byte value.

Prototype #i ncl ude <acl st r . h>

BYTE at ox ( BYTE char act er ) ;

Parameters
charact er Character to convert.

Return Values
Success: 0–15: Successful operation.

Failure: 0xFF: Error (invalid character).

Example The linked example code file demonstrates use of atox().

beep()

Activates the beep feature of the terminal. Based on thet ype parameter, beep( )
produces one of two types of beeps, both can occur on a conditional or
unconditional basis.
A conditional beep is based on the value of the *BP parameter in the system
CONFI G. SYS file. If the *BP value is zero or empty, the beep executes, therefore,
default allows a conditional beep. A non-zero value prevents a conditional beep.

Prototype #i ncl ude <acl coni o. h>

voi d beep( i nt t ype) ;

Parameters The following are valid type values defined in ACLCONIO.H:

t ype Normal, Error, or Conditional.
• NORML: Normal beep
• ERROR: Error beep
• C_NORML: Conditional
normal beep
• C_ERROR: Conditional
error beep

Return Values The function returns on completion of the beep. No value is returned.

Dependencies Verix eVo SDK

See Als o NORM_BEEP(), ERR_BEEP()

Example The linked example code file demonstrates use of beep().

140 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
bitfun()

bitfun()

Performs bit manipulation on an unsigned integer.

Prototype #i ncl ude <acl coni o. h>

i nt bi t f un ( UI NT *map, BYTE bi t , BYTE set ) ;

Parameters
map Pointer to an unsigned integer bitmap.
bi t Bit to manipulate: 0–15, counting from the right.
set Action to take on bit:

• 0 clears the bit

• 1 sets the bit
• 2 checks the bit

Retur n Values Defined for CHECK_BIT only.

Success: 1: Bit is set.

Failure: 0: Bit is clear.

Example The linked example code file demonstrates use of bitfun().

VERIX EVO ACT PROGRAMMERS GUIDE 141

F UNCTION C A L L S
card_parse()

card_parse()

Accepts data from the card reader and parses it to the selected track data.

Prototype #i ncl ude <acl dev. h>

i nt car d_parse( char *t r ack, st r uct TRACK *parsed, char *or der) ;

Parameters
track Card reader data.
par sed Parsed output.
or der Track selection order.

Return Values
Success: 1,2,3: Track number that was read (successful).
Failure: TK_NOT_FOUND (-1): None of the tracks specified in or der contained a
valid data status byte.
INVLD_ORDER (-2): The order contains a character that is not 1, 2, or 3.
BAD_READ (-3): An attempt to parse a track field in the card read data
fails.
INVLD_FORMAT (-4): Invalid format.
ACT_FRAMING_ERROR (-6): Track status byte from card read is 2, 3, or
4. Parsed track is still stored in structure TRACK , and errno contains the
parsed track.

The individual tracks returned from read() are formatted as:

[C][S][track data]

where,
• [ C] is a single byte representing the length of the string containing the track
data, including the count byte.
• [ S] is a one byte status of the read for the track.
• [ t r ack dat a] is the complete track read of the track (if available). This field
is omitted for tracks not available on the terminal; however, the count byte and
status are provided for all three tracks.
Three of these fields are read from the card device regardless of how many
physical tracks are read by the terminal. The tracks appear in order from track 1 to
track 3, for example,
[ C1] [ S1] [ t r ack1] [ C2] [ S2] [ t r ack2] [ C3] [ S3] [ t r ack3]

142 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
card_parse()

The supported tracks comply with standard specifications as follows:

Track 1 format IATA track 1 format consisting of a maximum of 79 alphanumeric
characters. The track format is:
[ s s] [ f c ] [ PAN] [ f s ] [ name] [ f s ] [ ot her ] [ es ] [ l r c ]
where,
[ss] Start sentinel of “%” (0x25) [fc]: one-byte format code.
[ PAN] Primary account number; maximum 19 digits.
[fs] Field separator of “{” (0x7B) [name]: Name of the card
holder; maximum 26 characters
[other] Can contain the following:
• 4-digit expiration datea
• 3-byte restriction or type a
• 5-byte offset of PVNa
• 16 bytes of discretionary data

[es] End sentinel of “?” (0x3F).

[ l r c] 1-byte longitudinal redundancy check value
Track 2 format ABA track 2 format consists of a maximum of 40 numeric
characters. The track format is:
[ s s] [ PAN] [ f s ] [ ot her ] [ es ] [ l r c ]
where,
[ss] Start sentinel of “;” (0x3B).
[ PAN] Primary account number; maximum 19 digits.
[fs] Field separator of “=” (0x3D).
[other] Can contain the following:
• 4-digit expiration dateb
• 3-byte restriction or type b
• 5-byte offset of PVNb
• 5 bytes of discretionary data

[es] End sentinel of “?” (0x3F).

[ l r c] 1-byte longitudinal redundancy check value.
a. Required by VISA and MasterCard Track 2 format.
b. Required by VISA and MasterCard Track 3 format.

Track Format 3 ISO 4909 track 3 format consisting of a maximum of 107

alphanumeric characters. This standard was published in October,
1973; other formats are now in use. The track format is:
[ s s] [ f c ] [ PAN] [ f s ] [ s ec ur e ] [ ot her ] [ es ] [ l r c ]
where,
[ss] Start sentinel of “%” (0x25) [fc]; Two-byte format code.
[ PAN] Primary account number; maximum 19 digits.
[fs] Field separator of “=” (0x3D).

VERIX EVO ACT PROGRAMMERS GUIDE 143

F UNCTION C A L L S
card_parse()

[ secur e] Name of the card holder, 26 characters max

Can contain the following:
• 3-byte country code
• 1-byte field separator of “=” (0x3D)
• 3-byte currency code
• 1-byte currency exponent
• 4-byte amount authorized per cycle
• 4-byte amount remaining this cycle
• 4-byte cycle begin
• 2-byte cycle length
• 1-byte re-entry count
• 6-byte PIN control parameters
or
• 1-byte field separator of “=” (0x3D)
• 1-byte interchange control
• 2-byte PAN service restriction
• 2-byte SAN-1 service restriction
• 2-byte SAN-2 service restriction
• 4-byte expiration date
• 1-byte field separator of “=” (0x3D)
• 1-byte card sequence number
• 9-byte card security number
or
• 1-byte field separator of “=” (0x3D)

[other] Can contain the following:

• Optional first secondary account number
• Optional second secondary account number
• 1-byte relay marker
• 6-byte cryptographic check
or
• 1-byte field separator of “=” (0x3D)
• Discretionary data

[es] End sentinel of “?” (0x3F).

[ l r c] 1-byte longitudinal redundancy check value.

card_parse() processes tracks based on the or der parameter. On terminals that

read multiple tracks on a single pass, the application can select which is the
preferred track. For example, a terminal can read both track 1 and track 2 on a
card swipe.
The information on track 1 provides information not available on track 2, and the
track 1 information is preferred. If the data in track 1 is invalid or missing, then
track 2 data is read and returned. By specifying the order for processing as “12”,
card_parse() always attempts to obtain track 1, but returns track 2 if track 1 fails.

144 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
card_parse()

If a non-existent track is specified in the or der parameter, card_parse()

processes as though the track existed but was invalid.
card_parse() places the track information in a caller-supplied structure TRACK
(defined in ACLDEV. H). This structure contains the following data elements and
sizes:
st r uct TRACK
{
char acct [ 23] ; / * account number * /
char exp [ 5] ; / * expi r at i on dat e */
char name [ 27] ; / * name f or t r ack 2 */
char t ype [ 4] ; / * r equi r ed by VI SA/ MC */
char PVN [ 6] ; / * r equi r ed by VI SA/ MC */
char di sc [ 17] ; / * t r acks 1 and 2 onl y */
char t r ack [ 108] ; / * r aw t r ack dat a */

Not all fields are available on all tracks; the following table indicates the fields
available after parsing. This function clears all fields in the structure prior to
parsing. Any fields not used for a particular track are zero-filled.

Track1 Track2 Track3

acct X XX
exp X XX
name X ––
t ype X X–
PVN X X–
di s c X X–
track X XX

The track field is an exact copy of the data portion of the track field of the card
read. This can be used for inclusion in packets or additional parsing, if required.
The actual parsing of the track field is accomplished by calling the ACL routine
track_parse().
For tracks 1 and 2, if discretionary data is not available, card_parse() returns
success and the discretionary field is null.

Dependencies ACL MEMCLR(), track_parse()

NOTE
Data must be formatted as read from card reader.

Example The linked example code file demonstrates use of card_parse.

VERIX EVO ACT PROGRAMMERS GUIDE 145

F UNCTION C A L L S
chars2int()

chars2int()

Converts a string of up to five (ASCII) numeric characters to its integer equivalent.

Prototype #i ncl ude <acl ut i l . h>

i nt char s2i nt ( char *s_buf f er , i nt i _num) ;

Parameters
s_buf f er Pointer to a buffer containing the string to convert.
i _num Number of characters in the buffer.

Return Values
Success: Converted integer.

See Als o str2int()

Example The linked example code file demonstrates use of chars2int().

CAUTION This is an integer function. Be sure to convert values in the correct range. If the
string exceeds five characters, it is truncated on the right. For example, -12345
convert to -1234.
Any invalid string character is ignored. For example, 1A2B3 converts to 123.

146 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
chk_card_rdr()

chk_card_rdr()

Checks if data is available from the card reader port. This function is similar to the
keyboard function KBHIT().

NOTE
Use of this function on platforms where no magnetic card device exists will always
return 0.

Prototype #i ncl ude <acl dev. h>

i nt chk_car d_r dr ( i nt h_car d) ;

Parameters
h_car d Handle of card reader port.

Retur n Values
Success:  0: Data is available.

Failure: 0: No card data is available.

-1: An error related to the card reader occurred, see errno.

Dependencies Verix eVo SDK

NOTE This function reads the card data and writes the data back to the card reader. So
the complete data read from the card can not exceed the value of CARD_SI ZE as
defined in ACLDEV. H (the amount of space allocated for the read). If the bytes
read are less than one, no write to the card reader is executed. The card reader
device must be open.

Example The linked example code file demonstrates use of chk_card_rdr() .

VERIX EVO ACT PROGRAMMERS GUIDE 147

F UNCTION C A L L S
chk_luhn()

chk_luhn()

Accepts a null-terminated string containing digits, and verifies that the last digit in
the string is the correct MOD 10 check digit for the preceding digits in the string.

Prototype #i ncl ude <acl st r . h>

i nt chk_l uhn( char *buf f er ) ;

Parameters
buf f er String to check.

Return Values
Success: 1: The MOD 10 check digit is valid.

Failure: 0: The MOD 10 check digit is invalid.

-1: The string has no character, more than 25 characters, or less than 2
characters.

Calls SVC_MOD_CK( ) to complete the check and returns the result of
SVC_MOD_CK( ) .

Dependencies Verix eVo SDK

NOTE
String limits are 25 maximum and 2 minimum.

Example The linked example code file demonstrates use of chk_l uhn( ) .

148 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
CHK_TIMEOUT()

CHK_TIMEOUT()

Uses the i oct l ( ) function to compare a value specified by t i me_val to the
current clock tick value. CHK_TIMEOUT() returns TRUE(1) if the comparison
value is greater than the current clock tick value.

Prototype #i ncl ude <acl dev. h>

i nt CHK_TI MEOUT( i nt h_cl ock, unsi gned l ong t i me_val ) ;

Parameters
h_cl ock Clock handle.
t i me_val Time value in ticks.

Retur n Values
Success: 1: Time out not expired.

Failure: 0: Time out expired.

See Als o set_itimeout()

Example The linked example code file demonstrates use of CHK_TI MEOUT( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 149

F UNCTION C A L L S
clock_data()

clock_data()

Provides access to the terminal system clock.

Prototype #i ncl ude <acl dev. h>

i nt c l oc k_ dat a ( i nt c l oc k, i nt i _ t ype, c har * c l oc k_ buf f er ,
char * s _des t _buf r ) ;

Parameters
c l oc k Clock handle.
i _ t y pe Type of action to perform with clock:

• 1 = set clock
• 0 = get clock data

cl ock_buf f er Command string defining the desired clock output string. Only
used on get clock data operations ( i _ t y pe = 0). The
command should have a combination of punctuation (spaces,
commas, slashes, and so on) and command codes from the
following table.

Clock

Code Data Examples

A 2-digit year 1988 = 88

B 2-digit month July = 07

C 2-digit date 1 through 31

D 2-digit hours 12 hour clock

(that is, 10 A.M. = 10,
1 P.M. = 01)

E 2-digit minutes 00 through 59

F 2-digit seconds 00 through 59

G A or P A.M. = A
P.M. = P

H 4-digit year 1987 = 1987

I 3-letter month January = JAN

J Full month name January = JANUARY

K 2-digit hours 24-hour clock

10 A.M. = 10
1 P.M. = 13

L 3-letter day Monday = MON

M M adds M to a.m. and p.m. (see

N Full day Monday = MONDAY

150 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
clock_data()

O colon(:) colon for time (8:30 or

14:22:13)

P equal sign (=) equal sign instead of colon

(8=30 or 14=22=13)

Q numeric day Sunday = 0

Monday = 1
...
Saturday = 6
s_dest _buf r Destination buffer for the clock set string or clock output string.
On a clock set operation this buffer should contain a string
with the desired date/time to set the system clock in
yyyymmddhhmmss format. On get clock data operations, this
buffer is the destination for the formatted clock output string.

Retur n Values
Success: 1: No problems.

Failure: -1: Could not access clock.

VERIX EVO ACT PROGRAMMERS GUIDE 151

F UNCTION C A L L S
clock2int()

clock2int()

Converts a date-time string to the equivalent integer values. The date-time string
can be provided to the function or obtained by reading the clock device.

Prototype #i ncl ude <acl dev. h>

i nt cl ock2i nt ( i nt h_cl ock, unsi gned char *buf f er , i nt *year , i nt *mont h,
i nt *day, i nt *hour , i nt *mi n, i nt *sec, i nt *wday) ;

Parameters
h_cl ock Clock handle, used only when buffer is null.
buf f er Date-time string to convert. If null, current time is read.
If date-time is provided in buffer, it must be in the format yyyymoddhhmissw,
• where, yyyy is the year,
• mo is the month,
• dd is the day,
• hh is the hour,
• mi is the minutes,
• ss is the seconds, and
• w is the day of week.
Day-of-week values range from 0 to 6, with Sunday being 0. If the date
value provided in buf f er is not properly formatted, the results are
unpredictable.
year Converted year.
mont h Converted month.
day Converted day.
hour Converted hour.
mi n Converted minutes.
sec Converted seconds.
wday Converted weekday.

Return Values
Success: > 0: Success.

Failure: -1: Error reading clock.

Dependencies ACL, strn2int().

Example The linked example code file demonstrates use of c l oc k2i nt ( ) .

152 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
ctons1()

ctons1()

Converts a counted string to standard C-type null-terminated string. A counted

string consists of a count byte followed by the string data. The count bytes value is
the number of data characters in the string, including the count byte. For example,
the word COUNT contains five characters. To create a counted string, a single
byte of 6 is inserted in front of the C in COUNT making the total length of the string
6 bytes. This would be the equivalent of \006COUNT.
The resulting null-terminated string occupies the same space as the original
counted string.

NOTE It is important to remember that the length of a counted string is indicated by the
length byte rather than a null at the end. One advantage of the counted string is
that it contains data that can contain nulls. When using counted strings, be
extremely careful about using C functions designed to operate on null-terminated
strings.

The memory space for a counted string and a null-terminated string are the same.
Allocate one byte for each data character, plus one byte for either the null or the
count byte.

Prototype #i ncl ude <acl st r . h>

char *ct ons( unsi gned char *st r i ng) ;

Parameters
s t r i ng String to convert.
Zero in string[0] is invalid. ctons1() treats this condition as an empty null-
terminated string and does not modify the string.
If s t r i ng[ 0] is 1, the counted string contains only the count byte. In this
case, s t r i ng[ 0] is set to 0 creating an empty null-terminated string.

Retur n Values This function returns a pointer to the converted null-terminated string.
A counted string must have a minimum length of one (the count byte).

Dependencies Verix eVo SDK

See Als o ntocs()

Example The linked example code file demonstrates use of ct ons1( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 153

F UNCTION C A L L S
cvt_ym()

cvt_ym()

Computes the total number of months from the year 0000 A.D. to the time given in
a buffer in yyyymm format.

NOTE
The year must be between 1969 and 2068.

Prototype #i ncl ude <act ut i l . h>

i nt cvt _ym( char * ym) ;

Parameters
ym Year and month for conversion in yyyymm format.

Return Values
Success: Positive: Number of months.

Failure: Negative: -1 if date or year out of bounds.

delete_char()

Deletes a single character from a null-terminated string. The length of the string is
decremented by one. The del _pos parameter specifies the characters offset into
the string, with zero being the beginning of the string.

Prototype #i ncl ude <acl st r . h>

i nt del et e_char ( char *st r i ng, i nt del _pos) ;

Parameters
s t r i ng String from which to delete a character.
del _pos Zero-based position of the character to delete.

Return Values
Success:  0: Length of the modified string.

Failure: -1: pos was larger than the allowable string length or the position value was
negative.

Dependencies Verix eVo SDK

See Als o insert_char(), DVLR Function Calls, pad(), purge_char()

Example The linked example code file demonstrates use of del et e_char ( ) .

154 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
display()

display()

Accepts a pointer to a null-terminated string and writes it to the display without

repositioning the cursor prior to the write, or clearing any portion of the display. At
completion, the cursor is positioned after the last written character.
This is the equivalent of:
wr i t e( STDOUT, di spl ay_st r i ng, st r l en ( di spl ay_st r i ng) )

Prototype #i ncl ude <acl coni o. h>

i nt di s pl ay( c har * di s pl ay_ s t r i ng) ;

Parameters
di s pl ay_ s t r i ng Null-terminated string.

Retur n Values
Success:  0: Number of characters actually written to the display. This return
value is the actual return value from wr i t e( ) .

Failure: -1: An error occurred in the wr i t e( ) function.

Dependencies Verix eVo SDK

See Als o display_at()

Example The linked example code file demonstrates use of di s pl ay( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 155

F UNCTION C A L L S
display_at()

display_at()

Repositions the cursor by column and line number before displaying a string and
optionally, clears the display.
The cursor is repositioned using the got oxy( ) function. Applications written for
single-line displays should always specify line 1 as the line number; however, the
col umn parameter can be useful to position displays.
Multiline applications should provide a line number appropriate for the intended
platform. Refer to the programmers manual for the target terminal.

Prototype #i ncl ude <acl coni o. h>

i nt di spl ay_at ( unsi gned i nt col umn, unsi gned i nt l i ne, char
*di spl ay_st r i ng, unsi gned i nt cl ear ) ;

Parameters
col umn Display column.
l i ne Display line position.
di s pl ay_ s t r i ng Null-terminated string.
cl ear Clear display option.
The following three cl r options are available and are defined in
ACLCONIO.H:
• CLR_LINE: Clears the entire line selected for the display
operation.
• CLR_EOL: Writes the display message, and then clears to the
end of the line.
• NO_CLEAR: Does not clear any portion of the display or any
other value.

Return Values
Success:  0: Number of characters actually written to the display. This return
value is the actual return value from wr i t e( ) .

Failure: -1: An error occurred in the wr i t e( ) function.

Dependencies ACL display()

NOTE
Column and line values are not checked to ensure they are appropriate for the
terminal.

See Als o display()

Example The linked example code file demonstrates use of di spl ay_at ( ) .

156 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
display_new()

display_new()

Displays the message in column one of the current line, then clears the display to
the end of the line. The message must be null-terminated.

Prototype #i ncl ude <acl coni o. h>

i nt di spl ay_new ( char *message) ;

Parameters
mes sage Pointer to the buffer containing the null-terminated message to display.

Retur n Values Positive number indicates the number of characters actually written to the display.
This is the value returned from wr i t e( ) .

Success: 0:

Failure: -1: Indicates an error.

See Als o display(), display_at()

Example The linked example code file demonstrates use of di spl ay_new( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 157

F UNCTION C A L L S
do_compression()

do_compression()

Compresses or uncompresses a record using one of the following compression

types: no compression, 6BIT, VFI, or BCD.

Prototype #i ncl ude <acl f i l e. h>

i nt do_compr essi on ( i nt mode, i nt compr ess_t ype, char * i n_buf ,
c har * out _ buf , i nt i n_ l en) ;

Parameters
mode Mode to execute:
• COMPRESS_RECORD; Size of compressed data.
• UNCOMPRESS_RECORD; Size of uncompressed data.

compr ess _t ype Type of compression:

NO_COMPRESSI ON Copies i n_buf to out _buf .
COMPRESS_6BI T Data compression operates on a subset of
the ASCII character set (0x20–0x60).
Lowercase characters are replaced with
uppercase equivalents. Control characters
(ASCII values less than 32 or greater than
127) are not preserved. This type of
compression is not completely reversible.
COMPRESS_VFI Only digits 0–9 are compressed. Any non-
numeric value is not compressed. Non-
numeric values can be expanded (8-to-4
COMPRESSION); lowercase characters are
replaced with uppercase equivalents.
COMPRESS_BCD Compresses (Binary Coded Decimal) digits
8-to-4. Non-numeric data is not
compressed.
i n_buf Pointer to the record to compress or uncompress.
• mode = COMPRESS_RECORD, the buffer contains the record to
compress
• mode = UNCOMPRESS_RECORD, the buffer contains the record
to uncompress
out _buf Pointer to the buffer storing the compressed or uncompressed
record.
i n_ l en Length of the input record to compress or uncompress.

Return Values
Success: 0:

Failure: -1: Invalid input length.

Calling do_compr essi on( ) with NO_COMPRESSI ON is the equivalent of

memcpy().

158 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
do_compression()

Ensure that out _buf is large enough to contain the compressed/uncompressed

record. In both cases, out_buf is updated with the compressed/uncompressed
record.
Using the COMPRESS_ VFI compression type on character records results in a
compressed record larger than the original (uncompressed) record (for example,
"ABCD" = F41F42F43F44 compressed).
COMPRESS_ BCD inserts a length count ahead of a compressed numeric string.
Any alpha character remains the same.

Example The linked example code file demonstrates use of do_compr essi on( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 159

F UNCTION C A L L S
dsp_strs()

dsp_strs()

Accepts one or more null-terminated strings and displays the string on the
STDOUT device.
This routine calls the write() function once for each string parameter. The display is
not cleared and the function uses the current line and column for the start of the
display.

Prototype #i ncl ude <acl coni o. h>

i nt ds p_ st r s ( c har * va_ al i s t , . . . ) ;

Parameters
va_ al i s t Argument prototype for display string(s).

Return Values
Success:  0: Number of characters actually written to the display for the last string.
This return value is the actual return value from the wr i t e( ) function.

Failure: -1: An error occurred in the wr i t e( ) function.

Dependencies Verix eVo ACT Library wr i t e( ) , (see page 155 for wr i t e( ) example).

CAUTION
The final argument must be a null. The behavior of the function is undefined if the
parameters are not null-terminated strings or the trailing null is omitted.

Example The linked example code file demonstrates use of dsp_strs() .

ERR_BEEP()

Activates the beep feature of the terminal. The function produces an error beep,
that is lower in pitch than a normal beep.

Prototype #i ncl ude <acl coni o. h>

voi d ERR_BEEP( ) ;

Retur n Values The function returns before completion of the beep. No value is returned.
This function is implemented as a macro.

Dependencies error_tone() , nor mal _t one( ) .

See Als o beep(), NORM_BEEP()

Example The linked example code file demonstrates use of ERR_BEEP( ) .

160 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
f_ doll ar()

f_dollar()

Formats a null-terminated string as a dollar amount. Options include insertion of

the dollar sign ($), specification of decimal places, and separator characters.

NOTE f _ dol l ar ( ) is not bound by an internally allocated buffer. The only string size
limitation is that the data buffer must be large enough to accommodate the input
data with all format characters.

On input, data is the null-terminated string to be formatted. On output, data is

the corresponding dollar formatted string.

Prototype #i ncl ude <acl st r . h>

voi d f _ dol l ar ( c har * dat a_ pt r , i nt p r ec , i nt d ol _ f l ag, i nt dol _ f or mat ) ;

Parameters
data_pt r Pointer to the I/O buffer.
pr ec Number of decimal digits.
dol _ f l ag $ format flag. Valid values are defined in ACLSTR.H as follows:

Value Define Explanation

• 0 DOLLAR_FMT_OFF Input string unchanged; no formatting.

• 1 DOLLAR_FMT Format without leading $.

• 2 DOLLAR_IN_FMT Format with leading $.

dol _f or mat Radix and separator format. Valid values are defined in ACLSTR.H as
follows:
Value Define Radix Separator

• 0 DOL_RDXPSEPN period none

• 1 DOL_RDXNSEPN none none

• 2 DOL_RDXPSEPC period comma

• 4 DOL_RDXCSEPN comma none

• 6 DOL_RDXCSEPP comma period

If dol_format is not equal to a valid equate, the default of

DOL_RDXPSEPN is used.

Retur n Values None

Dependencies Verix eVo SDK

Verix eVo ACT Library insert_char().

See Als o sputf()

Example The linked example code file demonstrates use of f _ dol l ar ( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 161

F UNCTION C A L L S
fi el dc nt ()

fieldcnt()

Copies the nth counted field from a source buffer specified in buf . f i el dcnt ( )
starts the first counted field at the position specified by s t a r t and moves down to
the field specified by count . The string is then copied to the destination buffer.
Counted fields are defined by a count byte and a series of data bytes. The value
of the count byte is the length of the data string plus the count byte. Counted fields
can contain null characters.
Offset values begin at 0 for the first position in the source string. If the return value
is 0 or -1, a null character is returned in the destination buffer.

Prototype #i ncl ude <acl st r . h>

i nt f i el dc nt ( c har * buf , i nt s t ar t , i nt c ount , c har * des t ) ;

Parameters
buf Pointer to source buffer.
start Offset of counted fields.
count Field number to copy.
dest Destination buffer.

Return Values
Success:  0: Actual number of characters copied.

Failure: -1: The field does not exist, a parameter was out of range, or a count byte
was zero.

Dependencies Verix eVo SDK

NOTE IA null character is appended to the destination buffer. Since the counted field can
also contain null bytes, the first null byte is not necessarily the end of the data.
Verify the return value by the actual number of characters in the field.

If the source buffer is not properly formatted, the result is unpredictable.

See Als o fieldfix(), fieldvar(), fieldray()

Example The linked example code file demonstrates use of f i el dcnt ( ) .

162 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
fi el df ix ()

fieldfix()

Copies a data string from a source buffer to a destination buffer starting at an

offset specified by s t a r t up to a fixed length specified by si ze, or to end of the
source buffer.
If the function reaches the end of the buffer before copying all the characters
indicated by si ze, the function performs a partial copy and returns a value less
than the specified size value.
The function returns the actual number of characters being copied or an error
code (-1). If the return value is minus one or zero, a null character is returned to
the destination buffer; otherwise, a null character is added at the end of the
destination buffer.

Prototype #i ncl ude <acl st r . h>

i nt f i el df i x( c har * buf , i nt s t ar t , i nt s i z e, char * des t ) ;

Parameters
buf Source buffer.
start Starting offset (0-based).
s i ze Number of characters to copy (1-based).
dest Destination buffer.

Retur n Values
Success:  0: Number of characters in destination buffer; zero if no characters were
copied.

Failure: -1: Start offset was beyond the data string length or the offset was negative.

Dependencies Verix eVo SDK

NOTE
This function does not perform error checking. The destination buffer must be
large enough to contain the field data to copy and a null character.

See Als o fieldfix(), fieldvar(), fieldcnt()

Example The linked example code file demonstrates use of f i el df i x( ) . Also see the
EXFIELD.C example program.

VERIX EVO ACT PROGRAMMERS GUIDE 163

F UNCTION C A L L S
fi el dray ()

fieldray()

Copies a data string from a source buffer to a destination buffer. It starts at a fixed
offset specified in s t a r t and copies up to a stop character specified in stop, or
the end of the buffer. If the end of the buffer is reached before copying all the
characters indicated by the delimiter, a partial copy is performed.
The function returns the actual number of characters being copied or an error
code (-1). If the return value is -1 or zero, a null character is returned to the
destination buffer. Otherwise, a null character is appended to the data in the
destination buffer.

Prototype #i ncl ude <acl st r . h>

i nt f i el dr ay( c har * buf , i nt s t a r t , c har s t o p, c har * des t ) ;

Parameters
buf Source buffer.
start Starting offset (0-based).
stop Stop character at which copying terminates (this character is not copied
to the destination buffer).
dest Destination buffer.

Return Values
Success:  0: Number of characters being copied.

Failure: -1: Start offset was beyond or before the data string length.

Dependencies Verix eVo SDK

NOTE
This function does not perform error checking. The destination buffer must be
large enough to accommodate the data.

See Als o fieldfix(), fieldvar(), fieldcnt()

Example The linked example code file demonstrates use of f i el dr ay( ) .

164 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
fi el dv ar()

fieldvar()

Copies nth variable data field separated by a field delimiter. The first variable data
field starts at the beginning of the source buffer and ends at the first encountered
delimiter. If the end of the buffer is reached before copying all the characters
indicated by the delimiter, a partial copy is performed.
The function returns the actual number of characters copied or an error code (-1).
If the return value is minus one or zero, a null character is returned in the
destination buffer. Otherwise, a null character is appended to the end of the
destination buffer.

Prototype #i ncl ude <acl st r . h>

i nt f i el dvar ( char *buf , i nt f l dnum, unsi gned char sep, char *dest ) ;

Parameters
buf Buffer with message to scroll.
f l dnum Field number to copy (1-based).
sep Field separator.
dest Destination buffer.
i nc Scroll increments.
val i d_keys Valid key map (Refer Table 15 for valid keys)

Retur n Values
Success:  0: Number of characters being copied; zero if no characters were copied.

Failure: -1: The field does not exist.

Dependencies Verix eVo SDK

Verix eVo ACT Library fieldray()

NOTE
This function does not perform error checking. The destination buffer must be
large enough to contain the field data to copy, plus one null character.

See Als o fieldfix(), fieldvar(), fieldcnt()

Example The linked example code file demonstrates use of f i el dvar ( ) .

NOTE
When the parameter ending with a delimiter is passed to fieldvar() API, it assumes
that there is another variable present and returns zero.

VERIX EVO ACT PROGRAMMERS GUIDE 165

F UNCTION C A L L S
set_chars_per_key_value()

set_chars_per_key_value()

Gets the number of characters per key map from the user and sets the new value
in the library.
User needs to call this API if the default characters per key (Five) provided by
library does not suit their requirement. User needs to call this API before calling
getkbd_entry(), key_card_entry(), and SVC_KEY_TXT().
Once this API is called, the new value is retained for the life of the application. If
the user wants to change to a different value or default value, this API needs to be
called with a new value.
If the user calls this API with a value 7, the key map buffer should be as shown
below:
char sz KeyMap[ MAX_ALPNUM_KEYS] [ 7] ={"0- +%_" , " 1QZ. \ / " , " 2ABC&a" ,
" 3DEF%d", " 4GHI *g" , " 5J KL/ j " , " 6MNO~m" , " 7PRS^p", " 8TUV[ t " , " 9WXY] w" ,
" * , ' \ " : " , " #=: $? ! " };

Users can define their own characters set in each array element. If the value for
character per key is set to 7, an array char
szKeyMap[ MAX_ALPNUM_KEYS] [ 7] has to be defined. Only 6 chars can be
provided and one char is used for NULL.
It is the responsibility of the application to provide the array szKeyMap[][CHAR
PER KEY] passed to the Verix eVo ACT library functions. The value of CHAR
PER KEY can be modified, but the array should be in accordance with the
modified value of CHAR PER KEY. If the value and the array size mismatches,
then the results are unpredictable.

NOTE
set _char s_per _key_val ue( ) function allows the user to set any positive
value. It gets set to default value (6), when 0 or any negative value is given.

Prototype #i ncl ude <acl coni o. h>

voi d set _char s_per _key_val ue ( shor t shChar Per Key)

Parameters
short shCharPerKey Application-defined number of chars per key

Return Values None.

166 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
getkbd_entry()

getkbd_entry()

Provides display and keyboard entry functions for a variety of input applications.
This function combines the display, delay, key detection, data input, and data
validation routines.

Prototype #i ncl ude <acl coni o. h>

i nt get kbd_ent r y(i nt h_cl ock, char *msg, char *out buf , unsi gned wai t ,
unsi gned t ype, char sz KeyMap[ ] [ CHAR_PER_KEY] ,
i nt KeyMapSi z e, i nt va_ al i s t , . . . ) ;

Parameters
h_cl ock Clock device handle.
msg Message to display.
out buf Where to hold the return data.
wai t Wait time, in 10-ms increments.
t ype Type of data entry desired, valid values are:
• NUMERI C
• ALPHANUM
• NUMERI C| PASSWORD
• ALPHANUM| PASSWORD
• AMOUNT
• KEYMAP l ong va_al i st
Variable arguments that depend on t ype:
• If t ype is NUMERI C, ALPHANUM, NUMERI C| PASSWORD or
ALPHANUM_PASSWORD:
getkbd_ent r y(h_cl ock, msg, out _buf , wai t , t ype, char
SzKeyMap[ ] [ CHAR_PER_KEY] , i nt KeyMapSi ze, i nt max, i nt
mi n) ,
i nt max maxi mum number of di gi t s ( max= 9)
i nt mi n mi ni mum number of di gi t s ( mi n=0)
• If t ype is KEYMAP:
get kbd_ent r y( h_cl ock, msg, out _buf , wai t , t ype,
SzKeyMap, KeyMapSi ze, er r _wai t , er r _msg, keys)
i nt er r _ wai t = length of time to display er r _msg, in half-
second increments.
char *er r _msg = error message displayed for invalid entries
long keys bitmap of the keys that can be entered.
• If t ype is AMOUNT:
get kbd_ent r y( h_cl ock, msg, out _buf , wai t , t ype,
sz KeyMap[ ] [ CHAR_PER_KEY] , KeyMapSi ze, f r ac, max, mi n)
l ong max = maximum value allowed.
l ong mi n = minimum value allowed.
i nt f r ac =number of decimal places desired.

VERIX EVO ACT PROGRAMMERS GUIDE 167

F UNCTION C A L L S
getkbd_entry()

sz KeyMap [ ] Key map specifying the mapping of the logical alphanumeric keys
{CHAR_PER_KEY] to the physical keys on the keypad.
char szKeyMap[ MAX_ALPNUM_KEYS] [ CHAR_PER_KEY] =
{" 0- +%" , " 1QZ. \ \ " , "2ABC&", " 3DEF%" , " 4GHI *" ,
"5J KL/ ", "6MNO~", "7PRS^", "8TUV[ ", "9WXY] ", "* , ' \ ": ",
" #=: $?" };
For Vx680 terminal, the key map specifying the mapping of the
logical alphanumeric keys to the physical keys on the keypad is:
char szKeyMap[ MAX_ALPNUM_KEYS] [ CHAR_PER_KEY_VX680] =
{"0- +%" , " 1QZqz. \ \ " , " 2ABCabc&" , " 3DEFdef %" ,
" 4GHI ghi *" ,
" 5J KLj kl / " , " 6MNOmno~", " 7PRSpr s^" , " 8TUVt uv[ " ,
"9WXYwxy] ", "*, ' \ ": ",
" #=: $?" }
By default, in the Verix eVo ACT library, CHAR_PER_KEY is
defined as 6 and for V x680 terminals, the
CHAR_PER_KEY_VX680 is defined as 8. Hence the application
can have five chars per key in the key-mapping array. User can
modify this value by calling set_chars_per_key_value(). Based on
the value set by the user, the szKeyMap array should be passed to
the library APIs. There is no validation done on the array size by
the library.
KeyMapSi ze Size of the specified key map.
va_ al i s t One or more null-terminated strings to concatenate. The argument
list is null-terminated (defined in STDIO.H).

Retur n Values
Success: > 0: Length of string stored in out _ buf .
Failure: 0: Time out occurred.
-1: Device read error.
-2: Parameter out of range.
-3: clear key pressed (not provided for mapped entry type).
-4: Invalid entry type specified.
-5: User pressed enter key when null data entry is permitted.

NOTE All five input parameters are required. No parameter can be omitted from any call.
The prompt can be suppressed by supplying a null message parameter.
get kbd_ent r y( ) will wait for the data entry without updating the display.

The display capability of this function uses prompt() to display an optional

message for n number of 10-ms increments, as specified by the wai t parameter.
During this display time, any keypress terminates the display and begins the data
entry. Should the user fail to enter the data during the display period, the function

168 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
getkbd_entry()

ends and returns zero. If the data entry fails, the content of the output buffer is
unchanged. If an out-of-range amount is entered, getkbd_entry() beeps and an
invalid value remains displayed. The user can edit the entry using the backspace
key. All data is returned as a null-terminated string.

NOTE
If the value of outbuf is F1-F4 or ALPHA key, a blank pixel is displayed when
printed on the screen.

Data entry can be divided into three categories: standard entry, mapped key entry,
and amount entry. The data entry category is specified by the t ype parameter
and determines the syntax of the getkbd_entry() call. #def i nes for the type
options are supplied in ACLCONI O. H.

Standard Mode Data

Standard mode data entry is selected when type is NUMERI C, ALPHANUM,
NUMERI C| PASSWORD, and ALPHANUM| PASSWORD.
This mode entry is suitable for entering account numbers, expiration dates,
passwords, sequence numbers, and so on.
Standard entry options permit ALPHANUMand NUMERI C data entry in either clear
mode—where each character is echoed to the screen as it is entered—or
PASSWORD mode—where an asterisk (*) character is written to the screen for each
character entered at the keyboard. This option uses SVC_KEY_TXT().
Password type selection is accomplished by ORing either the ALPHANUMor
NUMERI C options with the PASSWORD option. If the mi n parameter is zero, null
data entry is permitted and the user can only press the enter key. If the mi n
parameter is not zero and the user presses the enter key,getkbd_entry() error
beeps and starts another data entry time out.
Cell Phone Mode

The cell phone mode is specific to Vx680 terminals. This feature enables the user
to key in the alpha numeric text without using the alpha keys, which are
traditionally used in other terminals. Each key has the corresponding key value
and alphabets. The user can click once to display the numeric value and click
twice, thrice and four times to display capital letter of the respective keys. Fifth,
sixth and seventh click displays those respective keys in small letters. The ninth
click will display the special character. Refer to the get kbd_ent r y( ) API for
more details on key mapping.

VERIX EVO ACT PROGRAMMERS GUIDE 169

F UNCTION C A L L S
getkbd_entry()

The time out value for displaying the character simultaneously is set by
#KEY_TI MER environmental variable. If the value of the environmental variable is
greater than 20, then the variable value is set as 20. If the value of the
environmental variable is less than 0, then 2 is set as the default value.

NOTE
Cell phone mode for keying in characters is supported only in Vx680 terminal.

Mapped Key Entry

Mapped key entry accepts a bitmapped long integer indicating the valid keys for
the entry. This is useful to prompt the user with a display and restricting input to a
limited number of keystrokes, such as Y/N entries.
The key map is created by ORing the values of the valid keys. #def i nes are
provided in ACLCONIO.H for all standard Verix eVo terminal keys, as well as the
screen-addressable keys.
Mapped key entry returns after the time out specified expires or a key contained in
the key map is entered. A single key is accepted and its null-terminated value is
placed in the output buffer.
Mapped key entry also accepts an error message and error display time. If an
error message is supplied, a prompt message should also be provided. The error
message is displayed for the specified number of half seconds after any invalid
keypress. If data entry starts while the error message is displayed, the routine
immediately reads and processes the new input. If no entry occurs during the
error message display, the prompt message redisplays. This display restarts the
time out, providing another timed entry period. The error message can also
provide a secondary prompt, such as:
Pr ompt Msg = ABORT TRANS?
Er r or Msg = 9= YES OR 6= NO

The following table lists the defines for the individual key definitions.
Table 15 Key Definitions
Key Define
[0] KM_0
[1] KM_1
[2] KM_2
[3] KM_3
[4] KM_4
[5] KM_5
[6] KM_6
[7] KM_7
[8] KM_8
[9] KM_9

170 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
getkbd_entry()

Table 15 Key Definitions (continued)

Key Define
[*] KM_STR
[#] KM_PND
[CANCEL] KM_ESC
[CLEAR] KM_CLR
[BACKSPACE] KM_BS
[ALPHA] KM_AL
[FUNC/ ENTER] KM_CR
[a] KM_a: leftmost screen-addressable key
[b] KM_b: second from the left screen-addressable key
[c] KM_c: third from the left screen-addressable key
[d] KM_d: fourth from the left screen-addressable key (additional
screen-addressable keys)
[e] KM_e: fifth screen-addressable key
[f] KM_f: sixth screen-addressable key
[g] KM_g: seventh screen-addressable key
[h] KM_h: eighth screen-addressable key
[f0] KM_f0:ninth screen-addressable key
[f5] KM_f5:tenth screen-addressable key
All keys KM_ALL
No keys KM_NONE
Up Arrow key KM_DOWN
Down Arrow key KM_UP

Am ou nt Mode Data

The entry amount is selected by AMOUNT type. Amount entry uses
SVC_KEY_NUM() to accept numeric entries suitable for use in monetary-
formatted amounts. SVC_KEY_NUM() restricts the maximum number of input
characters to 15, and the maximum number of decimal places to 10. This routine
further restricts input to those values that can be represented by a signed long
value (-2147483648 to 2147483648), including decimal places. For example,
1000000 may represent:
• $1,000,000: 0 decimal places
• $100,000.0: 1 decimal place
• $1.000000: 6 decimal places
Positive and negative values are permitted. The alpha key (if present) can toggle
a “-” sign at the beginning of the data input. No checks are provided and
overrange conditions are undefined.

VERIX EVO ACT PROGRAMMERS GUIDE 171

F UNCTION C A L L S
getkbd_entry()

The f r a c parameter allows the user to specify the number of decimal places
included in formatting the input. max and mi n parameters must provide enough
digits to permit the use of a specified number of decimal places. This is useful in
international monetary environments and in applications using tax tables, gasoline
prices, and so on.
When specifying negative max or mi n parameters, it is not possible to specify a
negative value between 0 and -1. This is due to the inability to preserve leading
zeros.
Formatting the amount on the display can be controlled by ORing any of the
following values with the AMOUNT in the t ype parameter:
• RDXPSEPN radix decimal point and no separator: 1000000.00
• RDXPSEPC radix decimal point and comma separator: 1,000,000.00
• RDXCSEPN radix comma no separator: 1000000,00
• RDXCSEPP radix comma and decimal point separator: 1.000.000,00
If a format is not specified in the t ype, RDXSEPN is the default.

Example get kbd_ent r y( h_cl ock, msg, out put , 100, AMOUNT| RDXPSEPC,
sz KeyMap[ ] [ CHAR_PER_KEY] , KeyMapSi ze, 2, 100000L, 100L) ;

Displays msg for up to one second using the amount input, a decimal point as
radix, and a comma separator using two decimal places with 1,000.00, as the
maximum value, and 1.00 as the minimum value.
szKeyMap [ ] {CHAR_PER_KEY] The key map specifying the mapping of the logical
alphanumeric keys to the physical keys on the
keypad.

Example char s zKeyMap[ MAX_ALPNUM_KEYS] [ CHAR_PER_KEY] = {"0- +%" , " 1QZ. \ \ " ,
" 2ABC&" , " 3DEF%" , " 4GHI *" , " 5J KL/ " , " 6MNO~" , " 7PRS^" , " 8TUV[ " , " 9WXY] " ,
" * , ' \ " : " , " #=: $? " };
KeyMapSi ze Size of the specified key map.

Dependencies Verix eVo SDK

ACL prompt(), ctons1(), keyin_mapped(), ERR_BEEP(), keyin_amt_range(),
set_chars_per_key_value()

NOTE Only limited parameter verification is performed. If the wait parameter is zero, no
time-out value is used. For AMOUNT type entry, max cannot be less than min and
frac cannot be larger than the number of characters required to represent the
larger of max or min. For AMOUNT type, values between zero and minus one
cannot be specified, such as, 001 with a fractional value of 2.

A user entering mapped t ype data with a map passed with no bits set “on” (1), is
unable to register any keypress. The routine continues to loop each time a user
presses a key, and returns when the time out expires.

172 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
getxy()

For mapped key entry, if an error message is specified but the error time
parameter is zero, the message displays briefly and is then overwritten by the
prompt (if provided).

See Als o prompt(), prompt_at(), display(), display_at(), keyin_mapped(), keyin_amt_range()

Example The linked example code file demonstrates use of getkbd_entry(). Also see the
EXTRANS.C example program.

getxy()

Returns the x and y coordinate values of the cursor relative to the current window.
The upper-left corner of the window is position 1,1. The x and y values provided
by this function can be used in a got oxy( ) call to correctly position the cursor
within a window. This function differs from wher ecur ( ) , which returns the
physical position of the cursor. For example, if a window is defined using the
coordinates 3,1, 10,1 and the cursor is in the “home” position, getxy() returns 1,1,
and wher ecur ( ) returns 3,1.

Prototype #i ncl ude <acl coni o. h>

i nt getxy( unsi gned *x, unsi gned *y) ;

Parameters
x x coordinate.

y y coordinate.

Retur n Values
Success: 0: Success.

Failure: -1: The current cursor position is outside the boundaries of the current
window.

Dependencies Verix eVo SDK

See Als o window(), gotoxy(), wherecur()

Example The linked example code file demonstrates use of getxy().

VERIX EVO ACT PROGRAMMERS GUIDE 173

F UNCTION C A L L S
insert_char()

insert_char()

Inserts a character into a string at a specified position. This function permits

passing a null as the insert character, which can be used to truncate a null-
terminated string at specified position.

Prototype #i ncl ude <acl st r . h>

i nt i ns er t _ c har ( c har * s t r i ng, i nt pos , c har c ) ;

Parameters
s t r i ng Buffer containing the string.
pos Position to insert character.
c Character to insert.

Return Values
Success: > 0: Length of the modified string.

Failure: -1: Position was larger than string length, or position was negative or buffer
is NULL.

NOTE
Bounds checking are not performed. The calling routine must ensure space is
available for the inserted character(s).

See Als o DVLR Function Calls, delete_char(), purge_char(), pad(), sputf()

Example The linked example code file demonstrates use of insert_char().

insert_decimal()

Inserts a decimal point at the third character from the right in a dollar amount
string. The string is left padded with zeros if the length is less than three (for
example, 1 is converted to 0.01).

Prototype #i ncl ude <acl st r . h>

i nt i nser t _deci mal ( char *buf ) ;

Parameters
buf Buffer to store the string to convert. String buffer must be large enough to hold
result.

Return Values
Success: 0: Length of the converted string (positive number).

Failure: -1: If the input buffer is null, the first character is not “-” or a numeric, or if
any character is not numeric.

Example The linked example code file demonstrates use of insert_decimal().

174 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
int2str()

int2str()

Converts an integer value to an ASCII null-terminated string. This function

assumes base 10 and does not support a radix, but does allows negative input
values.
This function is based on the SVC_INT2 function in the C Standard library. The
function converts the resulting counted string to a null-terminated string.

Prototype #i ncl ude <acl st r . h>

voi d i nt 2s t r ( c har * des t , i nt val ) ;

Parameters
dest Output buffer. The destination buffer must be large enough to hold the resulting
characters and the null terminator (destination buffer plus two bytes).
val Value to convert.

Retur n Values None.

Dependencies Verix eVo SDK

Verix eVo ACT Library ctons1(), insert_char()

NOTE
Overflow is undefined.

See Als o strn2int(), long2str(), str2long()

Example The linked example code file demonstrates use of int2str().

VERIX EVO ACT PROGRAMMERS GUIDE 175

F UNCTION C A L L S
ju li an _dat e( )

julian _d at e()

Converts a specified date to a Julian calendar value. The Julian date is the day
number with reference to January 1 of the specified year. This is useful in
determining the number of days between one date entry and another. The macro
LEAP_YR() determines if the specified year is a leap year.

Prototype #i ncl ude <acl dev. h>

#i ncl ude <acl ut i l . h>
i nt j ul i an_dat e( unsi gned year, unsi gned mont h, unsi gned day) ;

Parameters
year Year number to convert.
mont h Month number to convert.
day Day number to convert.

Return Values
Success: > 0: Julian date for the specified month, day and year.

Failure: INVALID_TIME: month or day is invalid.

Dependencies Verix eVo SDK, Verix eVo ACT Library LEAP_YR()

See Als o LEAP_YR(), month_end()

Example The linked example code file demonstrates use of julian_date().

KBHIT()

Uses kbd_pendi ng_c ount ( ) to determine the number of unprocessed key
entries in the keyboard buffer. Key data is not read from the keyboard buffer. This
function is implemented as a macro.

Prototype #i ncl ude <acl coni o. h>

i nt KBHI T( voi d) ;

Retur n Values
Success: > 0: Number of keys in
buffer.

Failure: 0: No keys in buffer.

See Als o kbd_pending_count()

Example The linked example code file demonstrates use of KBHIT().

176 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
key_card_entry()

key_card_entry()

Accepts the card-type data from either the keyboard or card reader. The following
are conditions that must be met before calling key_car d_ent r y( ) :
• The message file must be open.
• Limited parameter verification is performed.
• The input buffer must be large enough to hold the data.

Prototype #i ncl ude <mess age. h>

i nt key_car d_ent r y(i nt h_cl ock, i nt h_car d, char *dat a, unsi gned i nt t ype,
unsi gned i nt wai t , unsi gned i nt max, unsi gned i nt mi n,
char *buf f er , unsi gned i nt message_num, char
sz KeyMap[ ] [ CHAR_PER_KEY] , i nt i nKeyMapSi ze) ;

Parameters
h_cl ock Clock handle.
h_car d Card reader handle.
dat a Buffer for entered data.
t ype Numeric or alphanumeric.
wai t Number of increments (10-ms increments).
max Maximum keyboard entry allowed.
mi n Minimum keyboard entry allowed.
buf f er Retrieved message or message to display.
message_ num Message number to display or 0 if there is a message in the buffer.
sz KeyMap [ ] The key map specifying the mapping of the logical alphanumeric
[ CHAR_PER_KEY] keys to the physical keys on the keypad. For example:
sz KeyMap[ MAX_ALPNUM_KEYS] [ CHAR_PER_KEY] = {"0- +%" , " 1QZ. \ \ " , " 2ABC&" ,
" 3DEF%" , " 4GHI *" , " 5J KL/ " , " 6MNO~" , " 7PRS^" , " 8TUV[ " , " 9WXY] " ,
" * , ' \ " : " , " #=: $? " };
By default, in Verix eVo ACT library, CHAR_PER_KEY is defined as 6. Hence the
application can have five chars per key in the key-mapping array. User can modify this
value by calling set_chars_per_key_value(). Based on the value set by the user, the
szKeyMap array should be passed to the library APIs. There is no validation done on
the array size by the library.
KeyMapSi ze Size of the key map specified.

VERIX EVO ACT PROGRAMMERS GUIDE 177

F UNCTION C A L L S
key_card_entry()

Retur n Values
Success: Positive: Source of entry as indicated:
• 0x31 = keyboard
• 0x32 = swipe

Input is in the data buffer. If swiped, full track data returns. If manual entry,
the user entry returns null-terminated. max and mi n parameters are not
verified. For more details on MSR data format refer to the r ead( ) API,
under Magnetic Card Reader section in Verix eVo OS Programmers
Manual.

Failure Negative: • 0 = time out • -1 = device read error

• -2 = parameter out of range • -3 = clear key pressed
or invalid prompt number • -5 = the user pressed the
• -4 = invalid entry type enter key when null data
specified entry is permitted

See Als o set_chars_per_key_value()

178 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
keyin_amt_range()

keyin_amt_range()

Uses the SVC_KEY_NUM() routine to accept numeric entries suitable for use in

monetary formatted amounts. Returns a null-terminated string to the callers buffer.
The SVC_KEY_NUM( ) routine restricts the maximum number of input characters
to 15 and the maximum number of decimal places to 10. This routine further
restricts input to values that can be represented by a signed long value
(2147483647 to -2147483648), including decimal places. For example, 1000000
can represent:
• $1,000,000: 0 decimal places
• $100,000.0: 1 decimal place
• $1.000000: 6 decimal places.
Positive and negative values are permitted. The alpha key on the terminal can
toggle a - sign at the beginning of the data input. No checks are provided and
overrange conditions are undefined.
The f r a c parameter allows the caller to specify the number of decimal places
included in formatting the input. The max and mi n parameters must provide
enough digits to permit the use of a specified number of decimal places. This is
useful in international monetary environments and in applications using tax tables,
gasoline prices, and so on.
When specifying negative max or mi n parameters, it is not possible to specify a
negative value between zero and minus one. This is due to the inability to
preserve leading zeros.
#def i nes are provided for the formatting of the data as follows:
• RDXPSEPN radix decimal point and no separator: 1000000.00
• RDXPSEPC radix decimal point and comma separator: 1,000,000.00
• RDXCSEPN radix comma no separator: 1000000,00
• RDXCSEPP radix comma and decimal point separator: 1.000.000,00
For example,
keyi n_amt _r ange( out put , RDXPSEPC, 100000L, 100L, 2) ;

Uses the decimal point as the radix, a comma separator, with an 1,000.00
maximum value and 1.00 minimum value, and uses two decimal places. The
formatting selection applies to the data in the buffer after data entry. The user only
sees the radix during data entry not the separator.
If a zero value is selected for the f r a c parameter, the radix is still displayed, but
with no trailing characters.

VERIX EVO ACT PROGRAMMERS GUIDE 179

F UNCTION C A L L S
keyin_amt_range()

keyi n_amt _r ange( ) requires the user to press at least one numeric key and
never returns a null string in out _buf .

NOTE Only limited parameter verification is performed. max cannot be less than min,
and frac cannot be larger than the number of characters required to represent the
larger of max or min. Values between zero and minus one cannot be specified,
such as, 001 with a fractional value of 2.

Prototype #i ncl ude <acl coni o. h>

i nt keyi n_amt _r ange(char *out _buf , i nt amt _f mt , l ong max, l ong mi n,
i nt f r ac) ;

Parameters
out _buf Buffer to store the return data.
amt _f mt Formatting specifier.
max Maximum amount value allowed.
mi n Minimum amount value allowed.
frac Decimal places allowed.

Return Values
Success: > 0: The length of the result buffer, including format characters.

Failure: -1: Device read error.

-2: Parameter out of range.

-3: clear key pressed.

Dependencies Verix eVo SDK, ACL: prompt(), ctons1(), keyin_mapped(), ERR_BEEP()

See Als o prompt(), prompt_at(), display(), display_at(), keyin_mapped()

Example The linked example code file demonstrates use of keyin_amt_range(). See also
the EXTRANS.C example program.

180 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
keyin_mapped()

keyin_mapped()

Accepts a bitmapped long integer indicating valid keys for data entry. This is
useful when prompting the user with a display and restricting input to a limited
number of keystrokes, for example, Y/N entries. The key map is created by ORing
the values of all the allowed keys. #def i nes are provided in ACLCONIO.H for all
standard Verix eVo keys, as well as the screen-addressable keys.

Prototype #i ncl ude <acl coni o. h>

char keyi n_mapped( unsi gned l ong key_map) ;

Parameters
key_ map Keys allowed for entry.

Retur n Values
Success: > 0: Key code value of valid key entered.

Failure: 255: Error reading keyboard.

251: Key press was not in the map.

This routine returns after each keypress, allowing the caller to take appropriate
error processing actions as required by the application.

Dependencies Standard TXO C Library

See Als o keyin_amt_range()

Example The linked example code file demonstrates use of keyi n_mapped( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 181

F UNCTION C A L L S
LE AP_YR()

LEAP_YR()

Determines if the specified year is a leap year. A leap year is defined as:
"Years evenly divisible by four but not evenly divisible by 100, or years evenly
divisible by 400."

Prototype #i ncl ude <acl ut i l . h>

i nt LEAP_YR( i nt year ) ;

Parameters
year Year to check.

Return Values
Success: 1: Leap year.

Failure: 0: Not a leap year.

Dependencies Verix eVo SDK

See Als o month_end()

Example The linked example code file demonstrates use of LEAP_YR().

182 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
load_bmp()

load_bmp()

Assists in building the ISO 8583 message packets (required in PIP applications)
by loading a bitmap, message ID, and processing code from a formatted file. The
file must be created using the TXOFILE utility (see TXOFILE Utility). Table 16 lists
the record, transaction code, transaction bitmap defines, message IDs, and
processing codes.
Each line in the bitmap file is a VLR record.
h_f i l e must be the handle to an open and properly formatted VLR file.
ISO 8583 hosts normally require bitmaps to be 8 bytes in length. The message ID
and processing code are packed BCD values (where, “0200” converts to 0x02
0x00).
Table 16 Codes
Code Definition

Record
00–03 = Bitmap index, message ID index, and processing code index.
04–06 = ISO 8583 bitmaps.
07–08 = ISO message IDs.
09–12 = ISO processing codes.
Tran Codes
00 Tran Code 0 = “04,07,09” authorization only.
01 Tran Code 1 = “05,08,09” sale/void.
02 Tran Code 2 = “06,08,09” force online.
03 Tran Code 3 = “06,08,11” refund.
Transaction Bitmap Defines
04 Bitmap 1 = “\x30\x20\x05\x80\x00\xc0\x00\x00” authorization only.
05 Bitmap 2 = “\x30\x20\x05\x80\x00\xc0\x00\x00” sale.
06 Bitmap 3 = “\x30\x38\x05\x80\x00\xc0\x00\x00” refund/force online.
Message IDs
07 Message Id 1 = “\x01\x00” authorization only.
08 Message Id 2 = “\x02\x00” financial transaction.
Processing Codes
09 Proc Code 1 = “\x00\x40\x00” sale, offline sale, authorization.
10 Proc Code 2 = “\x02\x40\x00” void DB, DB adjust.
11 Proc Code 3 = “\x20\x40\x00” refund, offline refund.

Prototype #i ncl ude <acl ut i l . h>

i nt l oad_bmp ( i nt h_f i l e, UI NT t r an_code, BYTE *b_map, BYTE *msg_i d, BYTE
*p_code) ;

VERIX EVO ACT PROGRAMMERS GUIDE 183

F UNCTION C A L L S
load_bmp()

Parameters
h_f i l e Bitmap file handle.
t r an_code Transaction code. This is the index to the record that contains the
record numbers for the bitmap, message ID, and processing code.
b_ map Pointer to the bitmap buffer.
msg_i d Pointer to the message ID buffer.
p_code Pointer to the processing code buffer.

Return Values
Success:  0

Failure: -1: File with errno containing the error code.

-2: Bad index format.

Example The linked example code file demonstrates use of load_bmp().

184 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
long2str()

long2str()

Converts a signed long integer to a string. If the long value is negative, a minus
sign is placed at the beginning of the string. The function converts 2147483647 as
the largest possible positive integer before it goes negative (four bytes). For
example, the large positive integer 21234567890 is converted to a corresponding
negative string as -2103731502. The large negative integer 11234567890 is
converted to a corresponding string as 1650333998.

Prototype #i ncl ude <acl st r . h>

voi d l ong2st r ( char *dest , l ong val ) ;

Parameters
dest Destination buffer address.
val Long integer to convert.

Retur n Values None.

NOTE
No error checking is performed. This function assumes a long val of four bytes.
The value 0x80000000 is forced to -2147483648.

See Als o strn2int(), str2long()

Example The linked example code file demonstrates use of long2str().

VERIX EVO ACT PROGRAMMERS GUIDE 185

F UNCTION C A L L S
MA X()

MAX()

Returns the greater of two values. This function is implemented as a macro, and
as such, the data types of val1 and val2 are determined by the caller. The caller
must ensure that val1 and val2 are compatible data types. The macro expands to:
( ( ( v al 1) > ( val 2) ) ? ( v al 1) : ( val 2) )

Because of the implementation as a macro, take care when passing parameters

that are actually expressions that modify variables (for example, i++). These
expressions may be evaluated twice.

Prototype #i ncl ude <acl ut i l . h>

MAX( val 1, val 2) ;

Parameters
val 1 First value to compare.
val 2 Second value to compare.

Return Values
Success: The larger of the two values.

Dependencies Verix eVo SDK

See Als o act_kbd_pending_test()

Example The linked example code file demonstrates use of MAX().

186 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
MEMCLR()

MEMCLR()

Prototype #i ncl ude <acl ut i l . h>

char *MEMCLR( char *buf , unsi gned si ze) ;

Parameters
buf Area to clear.
s i ze Size of the buffer.

Retur n Values Void pointer to the memory block cleared.

Dependencies Verix eVo SDK

See Als o memset ( )

Example The linked example code file demonstrates use of MEMCLR(). See also the
EXTRANS.C example program.

VERIX EVO ACT PROGRAMMERS GUIDE 187

F UNCTION C A L L S
msg_display_at()

msg_display_at()

Retrieves the specified message from the message file, repositions the cursor by
column and line number prior to displaying the string, and optionally clears the
display. The following are conditions that must be met before calling
msg_display_at():
• The message file must be open.
• The buffer must be large enough to hold the retrieved message.
• Column and line values are not verified to ensure they are appropriate for the
terminal.

Prototype #i ncl ude <mess age. h>

i nt msg_di spl ay_at ( unsi gned i nt col umn, unsi gned i nt l i ne, unsi gned i nt
message_num, char *buf f er, unsi gned i nt cl r ) ;

Parameters
col umn The column to display at.
l i ne The line to display on.
message_ num The message number to display.

buf f er Buffer to store retrieved message.

cl r Valid values are:
• CLR_LINE
• CLR_EOL
• NO_CLEAR

Return Values
Success: Positive: The number of characters actually written to the display. This is
the value returned from wr i t e( ) .

Failure: Negative: -1 on error; -2 message file not open or message not found

See Als o display_at()

188 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
msg_display_new()

msg_display_new()

Retrieves the specified message from the message file, repositions the cursor by
column and line number prior to displaying the string, and optionally clears the
display. The following are conditions that must be met before calling
msg_display_new():
• The message file must be open.
• The buffer must be large enough to hold the retrieved message.
• Uses msg_di spl ay_at ( ) .
msg_display_new() is prototyped in message.h

Prototype #i ncl ude <mess age. h>

i nt msg_di spl ay_new( unsi gned i nt message_num, char *buf f er ) ;

Parameters
message_ num The message number to display.

buf f er Buffer to store retrieved message.

Retur n Values
Success: Positive: The number of characters actually written to the display. This is
the value returned from wr i t e( ) .

Failure: Negative: -1 on write error; -2 message file not open.

VERIX EVO ACT PROGRAMMERS GUIDE 189

F UNCTION C A L L S
MI N()

MIN()

Returns the lesser of two values. This function is implemented as a macro and, as
such, the data types of val1 and val2 are determined by the caller. The caller must
ensure that val1 and val2 are compatible data types. The macro expands to:
( ( ( v al 1) < ( val 2) ) ? ( v al 1) : ( val 2) )

Because of the implementation as a macro, take care when passing parameters

that are actually expressions that modify variables (for example, i ++). These
expressions may be evaluated twice.

Prototype #i ncl ude <acl ut i l . h>

MI N( val 1, val 2) ;

Parameters
val 1 First value to compare.
val 2 Second value to compare.

Return Values The lesser of the two values.

Dependencies Verix eVo SDK

See Als o MAX()

Example The linked example code file demonstrates use of MIN().

190 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
month_end()

month_end()

Returns the number of days in the month for the specified year. Use the macro
LEAP_YR() to determine if the specified year is a leap year.

Prototype #i ncl ude <acl ut i l . h>

i nt mont h_end( i nt mont h, i nt year) ;

Parameters
mont h Requested month.
year Requested year.

Retur n Values
Success: The number of days in the month for the indicated year.

Failure: -1 = Invalid mont h value (out of range).

Dependencies Verix eVo ACT Library LEAP_YR()

See Als o LEAP_YR()

Example The linked example code file demonstrates use of month_end().

mult_strcat()

Concatenates multiple strings of text in the destination buffer.

NOTE
The destination buffer must be large enough to hold the result.

Prototype #i ncl ude <acl st r . h>

i nt mul t _ s t r c at ( BYTE * out buf , c har va_ al i s t , . . . ) ;

Parameters
out buf Pointer to the destination buffer storing the concatenated string.
va_ al i s t One or more null-terminated strings to concatenate. The argument list is
null-terminated (defined in STDIO.H).

Retur n Values
Success: Number of characters stored in the destination buffer.

0: No strings concatenated.

Example The linked example code file demonstrates use of mult_strcat().

VERIX EVO ACT PROGRAMMERS GUIDE 191

F UNCTION C A L L S
NO RM_BEEP()

NORM_BEEP()

Activates the beep feature of the system. This produces a beep higher in tone
than an error beep.
This function is implemented as a macro; it returns before completion of the beep.

Prototype #i ncl ude <acl coni o. h>

voi d NORM_BEEP( voi d) ;

Retur n Values None.

Dependencies normal_tone()

See Als o beep(), ERR_BEEP()

Example The linked example code file demonstrates use of NORM_BEEP().

ntocs()

Converts standard C-type null-terminated strings to counted strings commonly

used in C.

NOTE A counted string cannot contain more than 254 characters. This restriction is
required since, the count must be the first byte of the string and the maximum
value for a single byte is 255. The count byte is included in the count. The
destination buffer must be at least as long as the source buffer.

Prototype #i ncl ude <acl st r . h>

i nt nt ocs(char *dest _buf , char *sr c_buf ) ;

Parameters
dest _buf Address to store counted string.
sr c_buf Null-terminated string address.

Return Values
Success: String converted.

Failure: -1: The source or destination buffer is null.

Dependencies Verix eVo SDK

See Als o ctons1()

Example The linked example code file demonstrates use of ntocs().

192 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
p_ set_ ba ud fo rmat ()

p_set_baudformat()

Initializes the specified communications port for printing at a specified baud rate
and data format. Accepts a device handle to the printer port, the baud rate, and
the data format as parameters. Printer characteristics automatically initialized
include: character mode, auto-enable, flow control, and RTS assertion. The
following are conditions that must be met before calling p_set_baudformat:
• The caller must open( ) the communications port.
• Valid baud rates are: 300, 600, 1200, 2400, 4800, 9600, 19200, 38400, 57600
and 115200.

If an invalid rate is specified, the rate defaults to 9600.

• Valid data formats are: 7E1 7N1, 7O1, 8E1, 8N1 and 8O1.

If an invalid format is specified, format defaults to 7E1.

Prototype #i ncl ude <acl dev. h>

i nt p_set _baudf ormat( i nt h_comm_port , i nt baud_r ate, char *dat a_f ormat) ;

Parameters
h_comm_por t Handle for printer port.
baud_r at e Baud rate.
dat a_f or mat Data format.

Retur n Values
Success: 0

Failure: -1 on error.

Dependencies Verix eVo SDK

Example The linked example code file demonstrates use of p_set_baudformat().

VERIX EVO ACT PROGRAMMERS GUIDE 193

F UNCTION C A L L S
pa d( )

pad()

Accepts a null-terminated string (source) and adds characters as required to

produce a null-terminated destination string of the length specified by the call. The
location of the source in the destination (left, center, or right) is controlled through
the al i gn parameter. The pad character is specified by the caller, and can be any
value, including null.
The destination string is an exact duplicate of the source string if the source string
is equal to or longer than the desired length, or the length specified is negative or
zero. pad( ) does not truncate the source string to the specified pad length.
The source and destination buffers can be the same buffer. In this case, the
source contents are altered; otherwise, the source buffer contents are unchanged.

NOTE The caller must ensure that the destination buffer is the greatest of the two pad
length or source buffer. No bounds checking is performed. Passing null as the
pad_char parameter results in the destination buffer being filled with pad_size null
characters. The previous contents of the destination buffer are destroyed.

Prototype #i ncl ude <acl st r . h>

i nt pad( char *pdest _buf , char *psr c_buf , char pad_char , i nt pad_si ze,
i nt al i gn) ;

Parameters
pdest _buf Stores the padded string.
psr c_buf Source string to pad.
pad_char Pad with this character.
pad_si ze Size of the padded string.
al i gn Indicates the position of the source data in the destination string. Valid
values are:
Align at: Effect #define (ACLSTR.H)
• 0x00 Source at the beginning LEFT or LEFTJUSTIFY
• 0x80 Source at the end RIGHT or RIGHTJUSTIFY
• 0x88 Source centered CENTER or
CENTERJUSTIFY
• other value Source at the beginning

Return Values
Success: > 0: The number of characters added to the source string to produce the
destination string.
Failure: 0: The source length was greater than or equal to the pad length, or the pad
length was negative.

Dependencies Verix eVo SDK

See Als o DVLR Function Calls, insert_char(), delete_char()

Example The linked example code file demonstrates use of pad().
194 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
pa use()

pause()

Waits a designated number of 10-ms intervals. A keypress terminates the

function. If the t i me parameter is zero, the function does not pause and returns
immediately with a zero return value. pause( ) runs until either the time interval
has expired or a keypress is detected. If a keypress interrupts pause( ) , the key
value is read and discarded.

Prototype #i ncl ude <acl coni o. h>

i nt pause( unsi gned t i me) ;

Parameters
t i me Number of 10-ms intervals to pause.

Retur n Values
Success: 0: Pause interval successfully expired.

Failure: 1: Keypress occurred before designated pause interval expired.

-1: Keypress error condition.

Dependencies Verix eVo SDK

See Als o SLEEP()

Example The linked example code file demonstrates use of pause().

VERIX EVO ACT PROGRAMMERS GUIDE 195

F UNCTION C A L L S
pro mp t()

prompt()

Displays a null-terminated string at the current line, column 1, for a specified

duration or until a key is pressed, whichever occurs first. The key pressed remains
in the keyboard buffer and can be read on return from pr ompt ( ) .
The opt parameter determines how the display is cleared before writing the
di s pl ay_ s t r i ng on the display. The wai t parameter specifies the number of
10-ms increments to display the prompt message.

Prototype #i ncl ude <acl coni o. h>

i nt pr ompt ( i nt h_cl k, char *di spl ay_st r i ng, unsi gned i nt wai t ,
uns i gned i nt opt ) ;

Parameters
h_ c l k Handle to clock.
di s pl ay_ s t r i ng String to display.
wai t Wait time in 10-ms increments.
opt Clear display option. The clear options, defined in ACLCONIO.H,
determine how the display clears before writing the prompt message.
Valid clear options are:
• CLR_LINE: Completely clears the current line, but does not change
the cursor position.
• CLR_EOL: Clears from the end of message to the end of the line.
• NO_CLEAR: Writes to the display without clearing.

Return Values
Success: 0: Time expired without a keypress.

Failure: 1: A key was pressed before the time out.

Dependencies Verix eVo SDK

ACL prompt_at()

See Als o prompt_at(), display(), display_at()

Example The linked example code file demonstrates use of prompt().

196 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
pro mp t_at ()

prompt_at()

Displays a null-terminated string at the specified column and line for a specified
duration or until a key is pressed, whichever occurs first. The key pressed remains
in the keyboard buffer and can be read on return from pr ompt _at ( ) .
The opt parameter determines how the display is cleared before writing the msg
string to the display. The wai t parameter specifies the number of 10-ms
increments to display the prompt message.

Prototype #i ncl ude <acl coni o. h>

i nt pr ompt _at ( i nt h_cl ock, unsi gned col , unsi gned l i n, char *msg,
unsi gned wai t , unsi gned opt ) ;

Parameters
h_cl ock Clock handle.
col Display column location.
lin Display line location.
msg Message to display.
wai t Display time in 10-ms increments.
opt Clear display option. The clear options, defined in ACLCONIO.H, determine
how the display will clear before writing the prompt message. Valid clear
options are:
• CLR_LINE: Completely clears the line specified.
• CLR_EOL: Clears from the end of message to the end of the line.
• NO_CLEAR: Writes to the display without clearing.

Retur n Values
Success: 0: Time expired without a keypress.

Failure: 1: A key was pressed before the time out occurred.

Dependencies Verix eVo SDK

Verix eVo ACT Library display_at()

See Als o prompt(), display(), display_at()

Example See also the EXTRANS.C example program. The linked example code file
demonstrates use of prompt_at().

VERIX EVO ACT PROGRAMMERS GUIDE 197

F UNCTION C A L L S
pu rge _c ha r()

purge_char()

Removes all occurrences of a specified character from a null-terminated string.

The target string is not modified if it is empty, contains no purge characters, or the
purge character is null.

NOTE
This function does not purge null characters.

Prototype #i ncl ude <acl st r . h>

i nt pur ge_char( char *buf f er, char r em_char) ;

Parameters
buf f er Buffer to remove character from.
r em_char Character to remove.

Return Values
Success: Number of characters deleted from the target string.

Dependencies Verix eVo SDK

See Als o DVLR Function Calls, insert_char(), pad()

Example The linked example code file demonstrates use of purge_char().

198 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
range()

range()

Searches a table stored in a keyed file. r ange( ) operates on a specified file

passed as an input parameter. This file is assumed to be a keyed file, stored as
compressed records. Each record consists of a key value and associated key
data.
Each record within the file can be uniquely identified by a key value. The key
value is created from the concatenation of up to four characters, plus a one- or
two-digit integer corresponding to a record number.
r ange( ) assumes the associated key value data within the file is formatted to
create a range table as follows:
<mi ni mum r ange> <maxi mum r ange> <r ange dat a>

Each record of the file has a minimum and maximum range field, and associated
range data, separated with blanks. The maximum length of each cannot exceed
20 characters.
r ange( ) provides access into the range table. The programmer specifies a value
to be ranged or compared. The range function accesses the range table and
compares the minimum and maximum range fields in search of a matching
record. Should the value fall within the minimum and maximum ranges, the
associated range data is stored and the record in which the match is found
returns.

NOTE The file consists of CVLRs. Compression is intended to operate on a subset of the
ASCII character set. All numeric characters (range 30h–39h) are stored using only
four bits. All supported non-numeric characters (ranges 00h–02Fh and 3Ah–5Fh)
are stored using eight bits (that is, without compression). All other characters
(range 60h–FFh) are stored in eight bits and corrupted. Ensure that such data is
not included in the file records.

Prototype #i ncl ude <acl st r . h>

i nt r ange( RANGE_PARMS * r ange_dat a) ;

Parameters
r ange_dat a Range parameters defining the table and search criteria.

Retur n Values
Success: 0: The label length is greater than 4 or less than 1, or the start record is
greater than 99 or less than 1.

> 0: The record accessed in which a range match was found.

Failure: -1: Last record accessed at the time in which processing is complete and a
match has not been found— this is the equivalent of one greater than the last
record number of the file if the entire file is searched.

VERIX EVO ACT PROGRAMMERS GUIDE 199

F UNCTION C A L L S
range()

RANGE_PARMS Structure

All input parameters are passed in a structure of type RANGE_ PARMS, as defined
in ACLSTR. H.
t ypedef st r uct
{
char *acc t _num;
/ * ’ r ange’ or ’ account number ’ sear chi ng f or */
char *l abel ;
/ * Tabl e r ecor d l abel i dent i f i er ; Maxi mum of 4 char acters. Thi s st r i ng i s
concat enat ed wi t h the of f set r ecord number t o a uni que recor d i dent i f i er
i nt o t he t abl e ( l abel _ ent r y_ i d) . * /
char *dat a_f l d;
/ * Pl ace i n whi ch t o st ore f ound r ange data. Passed as nul l i f no data i s
t o be stored. */

i nt s t ar t ;
/ * Of f set r ecor d number i n whi ch t o begi n r ange search. Thi s i nt eger i s
concat enat ed wi t h t he l abel t o cr eat e a uni que recor d i dent i f i er i nt o the
t abl e ( l abel _ ent r y _ i d) . * /
char *f i l e_name;
/ * Fi l e i n whi ch t he r ange t abl e exi st s. */
} RANGE_ PARMS;

Dependencies Verix eVo SDK, getkey(), strcmp(), strncmp(), strcpy()

Example The linked example code file demonstrates use of range().

200 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
range_vlr()

range_vlr()

Searches a VLR file for a record that bounds the given account number.
range_vlr() operates on the specified file passed as an input parameter. This
parameter is assumed to be a VLR file, and each record consists of data as
follows:

NOTE
r ange_vl r ( ) does not perform error checking and the lengths of the range
numbers in the records become the lengths of the comparison.

Prototype #i ncl ude <acl f i l e. h>

i nt r ange_vl r ( char *accnt , i nt st ar t , char *dat a, char *f i l e_name) ;

Parameters
acct Range or account number being searching for.
start Offset record number at which to begin the range search.
dat a Buffer to store found range data. This is passed as null if there is no data
to store.
f i l e_name File where the range table exists.

Retur n Values
Success: 0: Range not found.

Failure: -1: Start record number is < 1 or the account is null.

-2: File cannot be opened; errno is intact.

> 0: The positive value of the record accessed in which a range match was
found.

VERIX EVO ACT PROGRAMMERS GUIDE 201

F UNCTION C A L L S
scroll_buffer()

scroll_buffer()

Displays a message in the current display window allowing the user to scroll
through the message using application-defined keys. Scrolling occurs at
increments specified by the calling function.
The initial display position of the message is specified in the s cr ol l _ of f s et
parameter. The amount of text to scroll is specified in the i nc parameter.
Use the calling routine to specify the key(s) to terminate the display. One of these
keys can be specified as a special exit key.
#def i nes for constructing the key map are included in ACLCONIO.H. To accept
one or more keys to terminate the display, OR the desired key values together. If
the exit key is selected, set key_buf [ 0] .

NOTE
If the value of key_buf is F1-F4 or ALPHA key, a blank pixel is displayed when
printed on the screen.

Prototype #i ncl ude <acl coni o. h>

i nt s cr ol l _ buf f er ( c har * buf , i nt i nc , uns i gned l ong val i d_ keys ,
uns i gned s cr ol l _ of f s et , char s c r ol l _ l ef t ,
c har s cr ol l _ r i ght , c har exi t _ key, c har * key_ buf ) ;

Parameters
buf Buffer with message to scroll.
i nc Scroll increments.
val i d_keys Valid key map. (Refer Table 15 for valid keys.)
s cr ol l _ of f s et Initial display position in scroll increments (1 based).
scr ol l _ l ef t Scroll left key.
s cr ol l _ r i ght Scroll right key.
exi t _key Exit key.
key_buf Buffer to hold key used to terminate the display.

Return Values
Success: Message position, based on i nc, when the user terminated the display.

Example The linked example code file demonstrates use of scroll_buffer().

202 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
set_itimeout()

set_itimeout()

Sets an interval timer based on the 1/64-second system tick clock. Used in
conjunction with CHK_TIMEOUT(). The time values are approximate.
Rollover is not processed by this routine. The system tick count is reset each time
the system powers up or on exit from system mode. This results in a rollover after
more than two years of continuous operation.

Prototype #i ncl ude <al cdev. h>

unsi gned l ong set _i t i meout ( i nt h_cl ock, unsi gned i nt t i me,
uns i gned l ong gr adi ent ) ;

Parameters
h_cl ock Clock device handle.
t i me Number intervals for time out.
gr adi ent Timeout units.

Retur n Values
Success: > 0: Current system tick value + (time *interval), where, interval is
TM_TICKS, TM_SECONDS, or TM_MINUTES, as defined in ACLDEV.H.

Failure: INVALID_TIME (0): Invalid interval.

See Als o CHK_TIMEOUT()

Example See also the EXTMOUT.C programming example. The linked example code file
demonstrates use of set_itimeout().

VERIX EVO ACT PROGRAMMERS GUIDE 203

F UNCTION C A L L S
sgetf()

sgetf()

Compares characters of an input string to a control string. sgetf() is the modified

version of the standard C routine sscanf ( ) . The s get f ( ) version offers
advantages of being much smaller than its standard C counterpart. s get f ( )
does not however, support floating point and some unsigned options.
Parsing terminates if any of the following occurs:
• the end of the control string is reached,
• the end of the input string is reached, or
• a conversion mismatch of the input and control strings.

Prototype #i ncl ude <acl st r . h>

c har s get f ( c har * s s , c har * cs , c har * ar gs , . . . ) ;

Parameters
ss Pointer input string.
cs Pointer control string. The control string can contain format directives or literals
as follows:

Flags Flags act as modifiers to the format directive and control how the
data is extracted. All flags are optional.
• *: Overrides storage assignment of this value. Without the “ * ”
option, data extracted from the input string is stored in the
corresponding address parameter. If the “ * ” is included in the
control string, data extracted from the input string is not stored in
an address in the parameter list.
• $: Applies only to integer and long conversions. This flag causes
the parser to ignore a single instance of “ . ” or “ , ” in the input
string. Example: If the input string is “65.11” and the control
string is “%$i”, then 6511 is stored.

Width Numeric value that specifies the maximum field width to extract.
This can be used in conjunction with the i, l, b, c, s types. Note that
if zero is specified as the maximum field width, at least one
character of the input string is extracted.

Literals Literals can be intermixed with directives in the control string.

There is a one-to-one correlation of a literal in the control string to a
literal in the input string, with one exception, the space character. A
single space character as a literal in the control string corresponds
to any number of blank spaces in the data string.

Directives All format directives are preceded by a percent (“%”) sign.

Directives are handled serially, so that the first directive starts at
the beginning of the string and the second immediately following it.
Standard directives follow the format:
%[ f l ags] [ wi dt h] <t ype>

204 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
sgetf()

Type This mandatory field specifies what kind of data is expected in the
input string and how it should be assigned. Supported values are:
• i = Decimal integer: Parsing begins at the first character of the
input string and ends on the first non-numeric. Exception: the “$”
flag allows a single radix (“.” or “,”) to be included in the numeric
string.
• l = Decimal long integer: Parsing begins at the first character of
input string and ends on the first non-numeric. Exception: the “$”
flag allows inclusion of a single radix (“.” or “,”) in the numeric
string.
• c = Character: Parsing begins at the first character in the input
string. Example: If the input string is “987”, then “ ” is stored.
• s = String: Parsing begins at the first non-space character of the
input string and ends at the first space or null character.
Example: If the input string is “987”, then “987” is stored as a
string (null-terminated).
• [ ] = String: Characters specified between brackets in the control
string describe the set of characters in the input string to be
assigned as a string (null-terminated). The first character found
in the data string that is not part of the bracketed set terminates
the string. This option differs from the s option in that the string
parsing is not terminated by a space.
• [1–9] A range of characters can be specified within the brackets
by putting a hyphen (“-”) character between the lower and upper
limits. (The first character must have a lower ASCII value than
the second.)
• [^]: Alternatively, bracketed characters can be used as a set of
exclusion characters to terminate the string. This is specified by
placing a carat (“^”) in the first position following the open
bracket. All characters are copied from the input string to the
assigned string-up until the point at which one of these exclusion
characters or null terminator is encountered.

Examples • If the input string is “123AB45,” then the control string “%[1-8]”
extracts the string “123”. Parsing terminates at the character “A”.
• If the input string is “123AB45,” then the control string “%[A-Z]”
extracts the string “AB”.
• If the input string is “<STX>12AB78<ETX> <LRC>,” then the
control string “%\002%[^\003]” assigns “12AB78” to a string.
ar gs Variable number of pointers to results of format conversion.

VERIX EVO ACT PROGRAMMERS GUIDE 205

F UNCTION C A L L S
sgetf()

Retur n Values
Success: Pointer to the last character parsed in the input string. The return value can
be used as the input string pointer for a subsequent call.

NOTE errno is initialized to zero at beginning of routine and set to EINVAL if:
• a syntax error occurs
• input the string does not match control string, or
• the end of the input string is reached and is not finished parsing the control string.

Dependencies Verix eVo SDK

See Als o sprintf()
Example The linked example code file demonstrates use of sgetf().

206 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
SLEEP()

SLEEP()

Causes program execution to be suspended by the specified number of 10-ms

increments. This function is implemented as a macro utilizing the SVC_WAI T( )
function.
The maximum time value allowed is one minute. Program suspension is not
interrupted by a keypress or other event. To perform program suspension use
pause(), which is terminated by a keypress.
SVC_WAI T( ) executes a foreground loop until the approximate number of
milliseconds specified in t i me elapse.

Prototype #i ncl ude <acl dev. h>

voi d SLEEP( unsi gned i nt t i me) ;

Parameters
t i me Sleep time in 10-ms increments.

Retur n Values None.

Dependencies Verix eVo SDK

See Als o SVC_WAIT(), pause()

Example The linked example code file demonstrates use of SLEEP().

VERIX EVO ACT PROGRAMMERS GUIDE 207

F UNCTION C A L L S
sputf()

sputf()

Modified version of the standard C routine spr i nt f ( ) . However, it does not

support all standard spr i nt f ( ) directives.
Control strings and control string literals are handled in a similar manner as the
standard spr i nt f ( ) .

NOTE s put f ( ) is not bound by an internally allocated buffer. The only string size
limitation is that the result buffer must be large enough to accommodate all
expanded format characters.

The following directives are supported:

• i integer
• u unsigned
• c character
• s string
Flags are also handled in the same manner as spr i nt f ( ) , with the exception of
the zero flag.
The standard spr i nt f ( ) function uses the zero flag to specify that a 0 is used as
the pad character should the output value contain fewer digits than the minimum
field width. This zero flag is not supported in the ACL s put f ( ) . s put f ( ) does,
however, support the same functionality through the standard minimum field width
parameter. If the minimum field width parameter contains a leading zero, it is
interpreted as the 0 flag, wherein zero is used as the pad character should the
output value contain fewer digits than the minimum field width.

= Center justify flag can be used in addition to left justify. For example,
sput f ( r esul t , "%=10s", "hel l o") ; accomplishes the following:
r es ul t : " hel l o "

+ Sign flag. This flag immediately follows the justification flag (-, =), and proceeds
- the minimum field width indicator. The + flag causes the output to contain a + if
the input value is positive and a - if the input value is negative.
Examples:
l ong l = 1234567L;
sput f ( buf f , "%- +10. 2l $$0i ", ( char *) &l ) ; or
sput f ( buf f , "%=+10. 2l $$0i ", ( char *) &l ) ;
r esul t : $+1234. 56
change l ong l = - 1234567L;
sput f ( r esul t , "%- +10. 2l $$0i ", ( char *) &l ) ; or
sput f ( buf f , "%=+10. 2l $$0i ", ( char *) &l ) ;
r esul t : $- 1234. 56

208 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
sputf()

$[$] n Dollar formatting. The position of the $ flag within the control string is important.
Dollar formatting must immediately proceed the i, u, c, or s directive. * can be
used in place of the n format value; the next parameter in the input list is then
used as the n format value, as follows:

n Format Values

Value Define Radix Separator

0 DOL_RDXPSEPN period none

1 DOL_RDXNSEPN none none

2 DOL_RDXCSEPP comma period

4 DOL_RDXCSEPN comma none

6 DOL_RDXPSEPC period comma

Definition: n specifies type of separator formatting.

Radix refers to the character separating whole numbers from decimal
digits.
Separator refers to the character separating thousands digits.
As with standard s pr i nt f , “ * ” designates the next parameter in the
input list as the format variable. s put f ( ) uses the same convention
when specifying minimum field width, precision, and dollar format.

Prototype #i ncl ude <acl st r . h>

char sput f ( char *r esul t _st or e, char *next _cs, char *args, . . . ) ;

Parameters
r e sul t _ s t or e Control string specifying formatting to occur.
next _cs Variable length list of pointers to control string.
ar gs Parameters and input data.

Retur n Values
Success: The length of the result buffer.

Failure: Unpredictable value if error encountered.

Dependencies Verix eVo SDK, STDIO.H, CTYPE.H, ACL: pad(), ctons1(), long2str(),
insert_char(), int2str(), f_dollar()

See Als o sprintf(), printf(), f_dollar()

Example The linked example code file demonstrates use of sputf().

VERIX EVO ACT PROGRAMMERS GUIDE 209

F UNCTION C A L L S
strn2int()

strn2int()

Converts cnt bytes of buffer to an integer value. Non-numeric characters in

buf f er are included in the count of bytes to convert, but are ignored during the
conversion.

Prototype #i ncl ude <acl st r . h>

i nt s t r n2i nt ( char * buf f er , i nt c nt ) ;

Parameters
buf f er Data to convert to an integer value; maximum 40 characters.
cnt Number of bytes to convert.

Return Values Equivalent integer value of the string. If cnt is greater than 40 or less than 0,
s t r n2i nt ( ) returns 0.

Failure: 0: cnt > 40 or no numeric characters in cnt bytes of buffer.

Dependencies Verix eVo SDK, ACL str2int()

Example The linked example code file demonstrates use of strn2int().

210 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
str2digit()

str2digit()

Accepts a string and purges all characters that are not digits. If a minus sign (“-”) is
found in the first character position of the string, it is retained in the resulting
string.

NOTE
The original string passed is destroyed; all non-digit characters are purged.

This routine is used in the st r 2l ong( ) function.

Prototype #i ncl ude <acl st r . h>

i nt s t r 2di gi t ( c har * s our c e) ;

Parameters
sour ce Pointer to null-terminated string to process.

Retur n Values
Success: Number of digit characters in the converted string not including the optional
“-” sign flag.

Failure: -1: String is empty.

Dependencies Verix eVo SDK

See Als o purge_char()

Example The linked example code file demonstrates use of str2digit().

VERIX EVO ACT PROGRAMMERS GUIDE 211

F UNCTION C A L L S
str2dsp_len()

str2dsp_len()

Calculates the number of characters required to fill a specified number of display

positions. Characters are counted in the source buffer, starting at a specified
offset in the given direction (FORWARD or REVERSE).

Prototype #i ncl ude <acl coni o. h>

i nt st r 2dsp_l en( char * sour ce, unsi gned of f set , shor t dsp_wi d, char di r ) ;

Parameters
source String to count.
of f s et Starting offset.
dsp_wi d Display width.
di r Count direction. Valid values are:
• FORWARD
• REVERSE

Return Values
Success:  0: Number of characters that can fit in dsp_wi d.

Failure: -1: Source buffer is null.

-2: Offset was greater than the string length.

Example The linked example code file demonstrates use of str2dsp_len().

212 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
str2int()

str2int()

Accepts a null-terminated string and returns an equivalent integer value. Except

for a leading minus sign (“-”), non-numeric characters in the string are ignored.
The basis for this function is SVC_2I NT( ) , which converts the null-terminated
string to a counted string.

NOTE The input string cannot be longer than 40 characters. Overflow and underflow is
undefined. st r 2i nt ( ) returns the same value for a string containing only ASCII
zeros, and a string with more than 40 characters.

Prototype #i ncl ude <acl st r . h>

i nt s t r 2i nt ( c har * buf f er ) ;

Parameters
buf f er Buffer containing string to convert; cannot exceed 40 characters.

Retur n Values
Success: Equivalent integer value of string.

Failure: 0: The input string is greater than 40 characters.

Dependencies Verix eVo SDK, ACL ntocs()

See Als o long2str(), int2str(), str2long()

Example The linked example code file demonstrates use of str2int().

VERIX EVO ACT PROGRAMMERS GUIDE 213

F UNCTION C A L L S
str2long()

str2long()

Converts string data containing ASCII decimal digits (0 to 9) into a long integer
number. The string is parsed from the beginning to the end of the buffer, or until a
null is encountered.
This function ignores all non-digit characters, except a minus sign (“-”). The minus
sign is interpreted as a sign flag and must be located in the first character position
of the string. A sign flag occurring in any other position in the string is ignored.

NOTE The module does not perform error checking. Overflow and underflow conditions
are undefined. st r 2l ong( ) returns the same result for a string containing only
ASCII zeros and a string with more than 40 characters.

This routine is the inverse of l ong2st r ( ) . This routine differs from the standard
atol() routine in that it ignores non-numeric characters (except for a sign flag in the
first byte).

Prototype #i ncl ude <acl st r . h>

l ong st r 2l ong( char *st r i ng) ;

Parameters
s t r i ng Null-terminated string to convert.

Return Values Long integer converted value.

Success: Long integer converted value.

Failure: -1: Buffer is NULL.

Dependencies Verix eVo SDK

See Als o long2str(), int2str(), str2int()

Example See also the EXTRANS.C example program. The linked example code file
demonstrates use of str2long().

214 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
track_parse()

track_parse()

Parses track data. The TRACK structure inputs the unformatted data in to the

function, and also holds the results of the parsing. The t k_opt i on parameter
specifies the track number to parse.
Track data is passed to the function in field track of structure parsed. For
information on the format of individual tracks, see car d_par se( ) . See
ACLDEV. H for I/O structure definitions.

Prototype #i ncl ude <acl dev. h>

i nt t r ack_par se( st r uct TRACK *par sed, unsi gned char t k_opt i on) ;

Parameters
par sed I/O structure.
t k_opt i on Track to parse.

Retur n Values
Success: 1

Failure: TK_NOT_FOUND: Tracks specified in t k_ opt i on contained an invalid data

status byte.

INVLD_FORMAT: Data could not be parsed.

TRACK Structu re
st r uct TRACK
{
char acct [ 23] ; / * account */
char exp [ 5] ; / * expi r at i on dat e */
char name [ 27] ; / * name */
char t ype [ 4] ; / *
t ype r eq’ d by VI SA & MC */
char PVN [ 6] ; / * PVN r eq’ d by VI SA & MC */
char di sc [ 17] ; / * t r ack 1 and 2 onl y */
char t r ack [ 108] ; / * r aw t r ack dat a */
}

Example The linked example code file demonstrates use of track_parse().

VERIX EVO ACT PROGRAMMERS GUIDE 215

F UNCTION C A L L S
view_buffer()

view_buffer()

Displays a string in the current display window and allows the user to use the [*]
and [#] keys to scroll to the right and left, respectively, when viewing strings larger
than the current display.
view_buffer() also allows the calling routine to specify the key or keys allowed to
terminate viewing the string. Pressing any key other than [*], [#], and the specified
termination key produces an error beep, and the display does not change.
view_buffer() does not permit scrolling past the end of the message string and
does not scroll beyond the beginning of the string. A scroll increment is specified
in the call. This is the number of characters to move either right or left for each
press of the [*] or [#] key.
#defines are included in ACLCONIO.H for constructing maps for the termination
key map. To accept one or more keys to terminate the display, simply OR the
desired key values together. For example, KM_BS| KM_CR permits the enter or
backspace key to end the display.
If i nc is less than 1, 1 is used as the scroll increment. i nc cannot be greater than
the display window size.

NOTE
In Vx700 terminal, instead of [*] and [#] keys, down and up arrow keys are used to
scroll to the right and left, respectively.

Prototype #i ncl ude <acl coni o. h>

i nt vi ew_buf f er ( char *buf , i nt i nc, unsi gned l ong key_map) ;

Parameters
buf Buffer with message to scroll.
i nc Scroll increment.
key_ map Map of termination keys.

Return Values
Success: 1

Dependencies keyin_mapped(), ERR_BEEP()

See Als o keyin_mapped()

Example See also the EXTRANS.C example program. The linked example code file
demonstrates use of view_buffer().

216 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
DVLR Fu nc ti on Call s

DVLR Funct ion DVLR functions allows manipulation of double variable length (counted) records
Calls (DVLRs). The following DVLR function calls are described:

• delete_dvlr() • seek_dvlr()

• insert_dvlr() • write_dvlr()

• read_dvlr()

A file using DVLRs provides the ability to search both forward and backward
through a file. Each record is composed of a forward-length count, the data, and a
backward-length count.

Forward-length count = 2 + DATA LENGTH + 2.

Backward-length count = 2 + DATA LENGTH + 2.

In addition, you can use DVLR functions with compressed or
uncompressed records.

CAUTION To avoid file pointer positioning errors, do not mix file access methods. For
example, do not write a record using wr i t e_ dvl r ( ) one time and write() the
next time.

delete_dvlr()

Deletes one or more double variable length records from a DVLR file.

NOTE
The file position indicator should be positioned at the start of a record to
guarantee that the function deletes the correct amount of data.

Prototype #i ncl ude <acl f i l e. h>

i nt del et e_ dvl r ( i nt handl e, i nt c ount ) ;

Parameters
handl e File handle returned by open( ) .
count Number of records to delete, starting at the current file position.

Retur n Values Positive number indicates successful operation.

Value Description

0 Attempt was made to read at EOF or the record size is 0.

-1 Failure, with errno containing the error code.

VERIX EVO ACT PROGRAMMERS GUIDE 217

F UNCTION C A L L S
insert_dvlr()

insert_dvlr()

Inserts a double variable length record into a DVLR file.

NOTE
The file position indicator must be positioned at the beginning of the DVLR. If it is
not, the file may become corrupt.

Prototype #i ncl ude <acl f i l e. h>

i nt i ns er t _ dvl r ( i nt h andl e, c ons t c har * buf f er , i nt s i z e) ;

Parameters
handl e File handle returned by open( ) .
buf f er Pointer to the data to insert.
si ze Maximum number of bytes to insert into the file.

Return Values Number of bytes successfully inserted (positive number).

Success: 0: Attempt made to read at EOF or the record size is 0.

Failure: -1: Failure, with errno containing the error code.

read_dvlr()

Reads a double variable length record from a DVLR file.

NOTE
To read the record successfully, the file position indicator must be positioned at
the beginning of a normal DVLR.

After reading the record, the file position indicator is advanced to the start of the
next record, even if all of the bytes in the record are not copied to the buffer.

Prototype #i ncl ude <acl f i l e. h>

i nt r ead_ dvl r ( i nt handl e, c har * buf f er , i nt s i z e) ;

Parameters
handl e File handle returned by open( ) .
buf f er Pointer to buffer storing the incoming record.
si ze Maximum number of bytes to read from the file.

Return Values Number of bytes successfully read (positive number).

Success: 0: Attempt was made to read at EOF or the record size is 0.

Failure: -1: Failure, with errno containing the error code.

218 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
seek_dvlr()

seek_dvlr()

Seeks the specified number of records forward or backward in a DVLR file.

NOTE
To seek past the correct quantity of data, the file position indicator must be initially
positioned at the beginning of the DVLR.

Prototype #i ncl ude <acl f i l e. h>

l ong s eek_ dvl r ( i nt handl e, l ong of f s et , i nt or i gi n) ;

Parameters
handl e File handle returned by open( ) .
of f s et Number of records to seek forward or backward. Use a negative value to
seek backward.
or i gi n Position to offset from. Valid values are:

• SEEK_SET Searches the beginning of file.

• SEEK_CUR Searches the file pointer current position.

• SEEK_END Searches the end of the file.

The above functions are available in SVC.H.

Retur n Values A positive number indicates absolute offset (in bytes) into the file after performing
the seek.

Failure: -1: Indicates a failure, with errno containing the error code.

VERIX EVO ACT PROGRAMMERS GUIDE 219

F UNCTION C A L L S
write_dvlr()

write_dvlr()

Writes a double variable length record to a DVLR file.

NOTE
The file position indicator must be positioned at the beginning of the DVLR. If it is
not, the file may become corrupt.

If the file position indicator is positioned on an existing DVLR, that record is

replaced with the new data (as if a delete_dvlr()/insert_dvlr() was performed). If
the file position indicator is positioned at the end of the file, the data is appended
to the file.

Prototype #i ncl ude <acl f i l e. h>

i nt wr i t e_ dvl r ( i nt handl e, c ons t c har * buf f er , i nt s i z e) ;

Parameters
handl e File handle returned by open( ) .
buf f er Pointer to the data to write.
si ze Maximum number of bytes to write to the file.

Return Values Number of bytes successfully written (positive number).

Success: 0: Attempt was made to read at EOF or the record size is 0.

Failure: -1: Failure, with errno containing the error code.

220 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
IVLR Fu nc ti on Call s

IVLR Functi on IVLR functions allows manipulation of integer variable length records (counted).
Calls The following IVLR function calls are described:

• delete_ivlr() • replace_ivlr()

• insert_ivlr() • seek_ivlr()

• read_ivlr() • write_ivlr()

T
CAUTION
To avoid file pointer positioning errors, do not mix file access methods. For
example, do not write a record using write_ivlr() one time and write() the next time.

delete_ivlr()

Deletes one or more integer counted records from an IVLR file.

Prototype #i ncl ude <acl f i l e. h>

i nt del et e_ i vl r ( i nt h_ f i l e, uns i gned i nt c ount ) ;

Parameters
h_f i l e Handle returned by open( ) .
count Number of records to delete, starting at the current file position.

Retur n Values
Success: Positive: Number of integers deleted

Failure: -1: Failure with errno containing the error code as determined by

del et e( ) or r ead( ) .
-2: Attempt to delete data past the end of file.

insert_ivlr()

Inserts an integer counted record into an IVLR file.

Prototype #i ncl ude <acl f i l e. h>

i nt i ns er t _ i vl r ( i nt h_ f i l e, cons t c har * buf f er , i nt r ec_ si z e) ;

Parameters
h_f i l e Handle returned by open( ) .
buf f er Pointer to data to insert.
r ec _s i z e Maximum number of bytes to insert into the file.

Retur n Values
Success: Positive: Number of bytes inserted

Failure: -1: Indicates a failure, with errno containing the error code as determined by
i ns er t ( ) .

VERIX EVO ACT PROGRAMMERS GUIDE 221

F UNCTION C A L L S
read_ivlr()

read_ivlr()

Reads an integer counted record from an IVLR file.

Prototype #i ncl ude <acl f i l e. h>

i nt r ead_ i vl r ( i nt h_ f i l e, char * dat a, i nt s i z e) ;

Parameters
h_f i l e File handle returned by open( ) .
dat a Pointer to buffer storing the incoming data.
si ze Maximum number of bytes to read from the file.

Return Values
Success: Positive: Number of characters read.

Failure: -1: Indicates a failure, with errno containing the error code as determined
by read().

replace_ivlr()

Replaces a record at the current position in an IVLR file.

Prototype #i ncl ude <acl f i l e. h>

i nt r epl ace_ i vl r ( i nt h_ f i l e, char * buf f er , i nt r ec_ si z e) ;

Parameters
h_f i l e Handle returned by open( ) .
buf f er Pointer to data to insert.
r ec _s i z e Maximum number of bytes to insert into the file.

Return Values
Success: Positive: Number of bytes in the new record.

Failure: -1: Indicates a failure, with errno containing the error code as determined
by i ns er t ( ) or r ead( ) .

222 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
seek_ivlr()

seek_ivlr()

Moves the file pointer to the specified record in an IVLR file.

NOTE
To seek past the correct quantity of data, the file position indicator must be initially
positioned at the beginning of the IVLR.

Prototype #i ncl ude <acl f i l e. h>

l ong s eek_ i vl r ( i nt h_ f i l e, l ong r e c_ num, i nt or i gi n) ;

Parameters
h_f i l e Handle returned by open( ) .
r ec_num Record number to search. int origin; Position to offset from. Valid
values are:
• SEEK_SET: From the beginning of file.
• SEEK_CUR: From the current position of the file pointer.
• SEEK_END: From the end of the file.

or i gi n Position to offset from. Valid values are:

• SEEK_SET: From the beginning of file.
• SEEK_CUR: From the current position of the file pointer.
• SEEK_END: From the end of the file.

Retur n Values
Success: Positive: New value of the file position indicator (in total number of bytes
from the beginning of the file).

Failure: -1: Indicates that the specified record number was not found. Backward
seeking is not supported; a record number previous to the current record
number cannot be sought.

VERIX EVO ACT PROGRAMMERS GUIDE 223

F UNCTION C A L L S
write_ivlr()

write_ivlr()

Writes an integer counted record to an IVLR file.

Prototype #i ncl ude <acl f i l e. h>

i nt wr i t e_ i vl r ( i nt h_ f i l e, cons t c har * dat a, i nt s i z e) ;

Parameters
h_f i l e Handle returned by open( ) .
dat a Pointer to the data to write.
si ze Maximum number of bytes to write to the file.

Return Values
Success: Positive: Number of characters written.

Failure: -1: Indicates a failure, with errno containing the error code as determined
by wr i t e( ) .

224 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
SVC Function Calls

SVC Functi on This section discusses the following SVC function calls:
Calls
• SVC_CLOCK() • SVC_KEY_TXT()

• SVC_KEY_NUM() • SVC_TICKS()

SVC_CLOCK()

Allows the user to read or set the current time.

NOTE
This function is supported on EPROM version 10 and higher.

Prototype #i ncl ude <svct xo. h>

i nt SVC_CLOCK( i nt acti on, char *buf f er , i nt l i mi t ) ;

Parameters
ac t i on • 0 = places the current time into buf f er (reads clock).
• 1 = writes the contents of buf f er to the clock (sets clock).

buf f er Stores the time information.

l i mi t Indicates the maximum number of characters:
• 15 when reading the clock.
• 14 when writing to the clock.

Retur n Values
Success: byt es: The number of bytes read or written.
Failure: -1: Failure

Example The linked example code file demonstrates use of SVC_CLOCK().

VERIX EVO ACT PROGRAMMERS GUIDE 225

F UNCTION C A L L S
SVC_KEY_NUM()

SVC_KEY_NUM()

Uses keyboard, display, and beeper input to retrieve a formatted decimal number
(counted string). The following are used for key presses:
• The alpha key is used to toggle between positive and negative numbers. A
negative number is displayed with leading-minus sign (-).
• The backspace key is used to delete the last character entered.
• The clear key is used to abort the read.

Prototype i ncl ude <svct xo. h>

i nt SVC_KEY_NUM( i nt dest _buf f , i nt max_di gi t s, i nt f r acti on, i nt
punct uat e) ;

Parameters
dest_ buf f Specifies where the resulting counted string of digits is stored.
max_di gi t s Specifies the maximum number of digits permitted (excluding
punctuation marks). This must be less than or equal to 15.
f r act i on Specifies the number of digits to the right of the radix. For example, the
fractional value. This must be less than or equal to 10. If the user presses
[ENTER] without additional input, the destination buffer contains a
counted string of zeros in the format specified in fraction.

0 - fraction bytes_read = 2. buffer = 0.

1 - fraction bytes_read = 3. buffer = 0.0

2 - fraction bytes_read = 4. buffer = 0.00

punct uat e Specifies the style of punctuation requested:

0 - Radix = point No separator 12345678.90

2 - Radix = point Separator = comma 12,345,678.90

4 - Radix = comma No separator 12345678,90

6 - Radix = comma Separator = point 12.345.678,90

Return Values
Success: bytes_read: The integer value containing the actual number of bytes stored
in the destination buffer (including punctuation characters) on a successful
read.

Failure: 1: The user pressed the clear key. The clear key trap is disabled when this
function is called.

Example The linked example code file demonstrates use of SVC_KEY_NUM().

226 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
SVC_KEY_TXT()

SVC_KEY_TXT()

Uses keyboard, display, and beeper to retrieve formatted data input. The following
are used for key presses:
• The control keys in the fourth column of the keyboard (backspace, alpha, and
enter) provide primitive editing options.
• The enter key is used to terminate the string, assuming the
mi ni mum_al l owed parameter has been satisfied.
• Each of the twelve imprinted keys on the keyboard represents several
characters: the alpha key scrolls through each of the possible characters. The
scroll sequence is inscribed on the key caps, with the following two
exceptions:
[0]: “0”, “-”, “ ” (space), “+”

[#]: “#”, “!”, “:”, “@”, “=”, “&”

• The backspace key is used to delete the last character entered.
• The clear key is used to abort the read.
The SVC_KEY_TXT( ) does not accept input from a function or screen-
addressable key, and beeps on a keypress from one of these keys.

Prototype #i ncl ude <t xosvc. h>

shor t SVC_KEY_TXT( char * dest , shor t t ype, shor t max, shor t mi n,
char sz Keymap[ ] [ CHAR_PER_KEY] , i nt KeyMapSi ze) ;

Parameters
szKeyMap[ ] [ CHAR_PER_KEY] The key map specifying the mapping of the logical
alphanumeric keys to the physical keys on the
keypad.
sz KeyMap[ MAX_ALPNUM_KEYS] [ CHAR_PER_KEY] = {"0- +%" , " 1QZ. \ \ " , " 2ABC&" ,
" 3DEF%" , " 4GHI *" , " 5J KL/ " , " 6MNO~" , " 7PRS^" , " 8TUV[ " , " 9WXY] " ,
" * , ' \ " : " , " #=: $? " };
By default, in the Verix eVo ACT library, CHAR_PER_KEY is defined as 6. Hence the
application can have five chars per key in the key-mapping array. User can modify this
value by calling set_chars_per_key_value(). Based on the value set by the user, the
szKeyMap array should be passed to the library APIs. There is no validation done on
the array size by the library.
KeyMapSi ze Size of the key map specified.
dest The location for the entered data to be returned
(should be large enough to receive max_al l owed
bytes plus one count byte).
t ype Specifies the type of data entry allowed:

• 0= Numeric keys only.

• 1= Alphanumeric keys.

VERIX EVO ACT PROGRAMMERS GUIDE 227

F UNCTION C A L L S
SVC_KEY_TXT()

• 2= Numeric keys for password. Each key is

echoed with an asterisk.

• 3= Alphanumeric keys for password. Each key

is echoed with an asterisk.
max The maximum number of bytes that can be entered.
mi n The minimum number of bytes allowed.

Retur n Values
Success: byt es_r ead: Integer value containing the actual number of bytes read on
a successful read.

Failure: -1: The user has pressed the clear key to cancel the read operation. The
clear key trap is disabled when this function is called.

Example The linked example code file demonstrates use of SVC_KEY_TXT().

See Als o set_chars_per_key_value()

228 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
SVC_TICKS()

SVC_TICKS()

Allows the user to check if a tick value has expired or read the systems tick
counter.

Prototype #i ncl ude <svct xo. h>

i nt SVC_TI CKS( i nt act i on, l ong *l ongadr ) ;

Parameters
ac t i on Determines the behavior of the function. Valid values are:

• 0= Compares the specified longword value against the systems

current longword tick counter. The return value indicates if the
users value has expired:
• 0 = expired
• 1 = pending

• 1= Copies the systems longword tick counter to the callers longword.

l ongadr Pointer to store the tick counter.

Retur n Values Return values are based on the value of action.

Action: Returned Value

Success: 1: Always returns 1.

Failure: 0: • 0 = users tick expired.

• 1 = users tick is pending (not expired).

This function is supported on EPROM version 10 and higher.

See Als o tick_compare()

Example The linked example code file demonstrates use of SVC_TICKS().

VERIX EVO ACT PROGRAMMERS GUIDE 229

F UNCTION C A L L S
Ap pl ic at io n Id le En gi ne Fu nc tion Call s

Applicat ion This section covers the Branch Table entry, Function Table, and idle loop
Idle Engi ne processing for the application engine, and presents Application Idle Engine
Function Calls Examples. The following application engine functions calls are described:

• aie_main() • appl_idle_set_cancel_loop_time()

• appl_idle_get_cancel_poll_time() • appl_idle_set_fast_poll_time()

• appl_idle_get_fast_poll_time() • appl_idle_set_idle_poll_time()

• appl_idle_get_idle_loop_time() • appl_idle_set_slow_poll_time()

• appl_idle_get_slow_poll_time()

branch_tbl_entry
t ypedef st r uct br anch
{
short event ;
shor t f unc;
st r uct br anch *next_ t abl e;
} Br anch_Tbl _Ent r y;

Function Table
t ypedef shor t ( *PF_TABLE) ( shor t st at e) ;

Idle Loop proc essing, Slow Poll, Fast Poll

The idle loop processing, slow poll, and fast poll functions should be of AI E
Pr oc .
t ypedef shor t ( * AI E Pr oc)( ) ;

Ap pl ic ati on Idl e Idle Loop Functi on

Engine Examples
This function is the main() loop in the engine and is called once per cycle. In this
example, appl_idle_loop() calls an auto_settle() function and an auto_download()
function. Based on a certain condition being met, the auto_download() function
performs a full or partial VeriCentre download and the auto_settle() function
performs an automatic settlement with the host.

Example The linked example code file demonstrates use of appl_idle_loop().

230 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
aie_main()

aie_main()

Starts the application idle engine. The mai n( ) of the program is defined by the
application. After performing the application initialization, Application Idle Engine
Examples should be invoked. Application Idle Engine Examples is the idle engine
processing loop. See Figure 1 for details on processing.

Prototype # i ncl ude <appl i dl . h>

i nt ai e_mai n( BRANCH_TBL_ENTRY *i dl et abl e, PF_TABLE *appl t abl e,
AI EPROC i dl e l oop, AI EPROC f ast pol l , AI EPROC sl owpol l ,
AI EPROC act i vat e, AI EPROC deact i vat e) ;

Parameters
i dl et a bl e Branch Table structure to search for the event.
appl t abl e Function Table structure containing the function pointers to the
application event handling routines.
l oop Pointer to the application-defined idle loop function.
f as t pol l Pointer to the application-defined fast poll function.
sl owpol l Pointer to the application-defined slow poll function.
ac t i vat e The application-defined routine to call when a activate event occurs.
deact i vat e The application-defined routine to call when a deactivate event occurs

Retur n Values TRUE.

NOTE The Application Idle Engine uses the EVT_TIMER supported by the Verix V OS
for the slowpoll, fastpoll and idlepoll functionalities. The results are unpredictable
when the application uses the EVT_TIMER along with Application Idle Engine, as
there might be a clash of EVT_TIMER event by the library as well as the
application.

appl_idle_get_cancel_poll_time()

Returns the value of the cancel detect timer. This timer determines the periodicity
of the AIE checks for the cancel key.

Prototype #i ncl ude <appl i dl . h>

l ong appl _i dl e_get _cancel _pol l _t i me( ) ;

Retur n Values The value of the cancel poll timer.

VERIX EVO ACT PROGRAMMERS GUIDE 231

F UNCTION C A L L S
appl_idle_get_fast_poll_time()

appl_idle_get_fast_poll_time()

Returns the value of the fast poll timer. This timer determines the periodicity of the
fast poll function that is called in the idle state.

Prototype #i ncl ude <appl i dl . h>

l ong appl _i dl e_get _f ast _pol l _t i me( ) ;

Retur n Values
Success: The value of the fast poll timer.

appl_idle_get_idle_loop_time()

Returns the value of the idle loop timer. This timer determines the periodicity of
the idle poll function that is called in the idle state.

Prototype #i ncl ude <appl i dl . h>

l ong appl _ i dl e_ get _ i dl e_ pol l _ t i me( ) ;

Retur n Values
Success: The value of the idle poll timer.

appl_idle_get_slow_poll_time()

Returns the value of the slow poll timer. This timer determines the periodicity of
the slow poll function that is called in the idle state.

Prototype #i ncl ude <appl i dl . h>

l ong appl _i dl e_get _sl ow_pol l _t i me( ) ;

Retur n Values
Success: The value of the slow poll timer.

appl_idle_set_cancel_loop_time()

Sets the value of the cancel poll timer.

Prototype #i ncl ude <appl i dl . h>

voi d appl _i dl e_set_cancel _l oop_t i me( l ong ti me) ;

Parameters
t i me The new value of the cancel poll timer.

Return Values Void.

232 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
appl_idle_set_fast_poll_time()

VERIX EVO ACT PROGRAMMERS GUIDE 233

F UNCTION C A L L S
Me ssag e/ Da ta Entr y Engi ne Func tion Calls

Message/Data This section describes the following message/data entry function calls:
Entry Engine
• msg_get() • msg_select_file()
Function Calls

msg_get()

Retrieves a record from the message file.

NOTE
Assumes msg_sel ect_ f i l e( ) has been called. This routine does not check for
buffer overflow. If the message file is compressed, msg_get() decompresses it.

Prototype #i ncl ude <mess age. h>

char *msg_get ( unsi gned message_num, char *buf _pt r ) ;

Parameters
message_ num Number of the text message to retrieve.

buf _pt r Pointer to the buffer receiving the text data (uses global variables
msg_f i l e and msg_compr ess ).

Return Values
Success: Pointer to null-terminated text string.

Failure: NULL.

Global variable errno contains the error code.

See Als o msg_select_file()

234 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
msg_select_file()

msg_select_file()

Opens a message file, reads the first record that contains the initialization
information, and sets the local file handle and compression variables.

NOTE The following global variables are set:

msg_f i l e = file handle.
msg_ compr ess = Compression used; Any previously opened message file is closed.

Compression on/off is determined at the time the message file is built. This is
transparent to the user.

Prototype #i ncl ude <mess age. h>

i nt msg_sel ect_f i l e( char *f i l e_name) ;

Parameters
f i l e_name Message filename where record is located.

Retur n Values
Success: Positive: Number of bytes read from the first record in the message file.

Failure: Negative: Number indicates an error.

See Als o msg_get()

VERIX EVO ACT PROGRAMMERS GUIDE 235

F UNCTION C A L L S
IS O 85 83 Me ssage Inte rfac e Engi ne Fu nc ti on Ca lls

ISO 8583 This section describes the following ISO 8583 message interface function calls:
Message • asc_to_asc() • hst_to_bi3()
Interface
Engine • asc_to_bcd() • hst_to_bin()

Function Calls • asc_to_str() • iso8583_main()

• av2_to_str() • map_clear()

• av3_to_av3() • map_man()

• av3_to_str() • map_reset()

• bcd_to_asc() • map_set()

• bcd_to_bcd() • map_test()

• bcd_to_snz() • process_8583()

• bcd_to_str() • set_dst_8583()

• bi2_to_hst() • set_src_8583()

• bi3_to_hst() • str_to_asc()

• bin_to_hst() • str_to_av2()

• bit_to_bit() • str_to_av3()

• bv2_to_str() • str_to_bcd()

• get_dst_8583() • str_to_bv2()

• get_fn_8583() • str_to_xbc()

• get_src_8583() • xbc_to_str()

voi d as c_ t o_ s t r ( i nt n) ;

Parameters
n Number of characters to move.

Retur n Values Void

Dependencies Verix eVo SDK.

Return Values Void

Dependencies Standard TXO C Library, asc_to_asc().

Retur n Values Void

Return Values Void

Dependencies Standard TXO C Library, bin_to_hex(), get_len_v2()

240 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
bin_to_hst()

VERIX EVO ACT PROGRAMMERS GUIDE 241

F UNCTION C A L L S
get_dst_8583()

get_dst_8583()

Prototype #i ncl ude

voi d get _ dst _8583( unsi gned char * dst ) ;

Parameters
dst Buffer to store the destination buffer of the ISO 8583 engine.

Return Values None

Dependencies Used in all the conversion routines that must obtain the destination buffer of the
ISO 8583 engine.

get_fn_8583()

Returns the erroneous field number during packet packing or unpacking. The
application calls this function to obtain the erroneous field after pr ocess _8583( )
fails, returning an -1 error. This implies that the field is not defined in the field
table.

Prototype #i ncl ude

i nt get _f n_8583( voi d) ;

Retur n Values
Success: The field number that had the error during message packing or unpacking.

Dependencies Obtain a meaningful results, the application should call get_fn_8583() only after
the packing/unpacking fails.

get_src_8583()

Prototype #i ncl ude

voi d get_ sr c_8583( unsi gned char *sr c) ;

Parameters
sr c Buffer to store the source buffer of the ISO 8583 engine.

Return Values None

Parameters
n Number of ASCII hex digits to convert.

Retur n Values Void

Dependencies Standard TXO C Library, hex_to_bin()

VERIX EVO ACT PROGRAMMERS GUIDE 243

F UNCTION C A L L S
iso8583_main()

iso8583_main()

Passes pointers to a convert table, function pointers to a user-defined functions

that returns the value of variant fields, and two buffers to hold the values of the
source and the destination (when conversion routines are used). These pointers
are used by the ISO Message Engine.

Prototype # i ncl ude

voi d i so8583_mai n( conver t ers *pConver t Tabl e, f n Ret1, f n Ret2,
unsi gned char *szdst _8583, unsi gned char *szsr c_8583) ;

Parameters
pConver t Tabl e Pointer to a convert table.
Ret 1 Function pointer to a user-defined function that returns the value of
variant fields.
Ret 2 Function pointer to a user-defined function that returns the value of
variant fields.
sz dst _8583 Buffer to store the destination buffer of the ISO 8583 engine.
szsrc_8583 Buffer to store the source buffer of the ISO 8583 engine.

Return Values None

Dependencies For any application, iso8583_main() should be called in mai n( ) before using the
ISO Message Engine.

map_clear()

Resets all bits in the designated map. The max_ f n parameter indicates the
maximum field number in the map (64, 128, 192, or 256). This is necessary to
ensure the correct construction of maps that exceed 64 bits.

Prototype #i ncl ude

voi d map_cl ear ( unsi gned char *map, i nt max_f n) ;

Parameters
map Pointer to bit map.
max_f n Maximum field number in map.

Return Values Void

Dependencies Verix eVo SDK

See Als o map_test(), map_set(), map_reset(), map_man()

Example The linked example code file demonstrates use of map_clear().

244 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
map_man()

map_man()

Turns bits on or off in the specified map. The default is to set (turn on) the bit in the
map associated with each field number. To reset a bit, simply add the constant
0xFF to the desired field number. Since there are a variable number of
parameters, add the constant STOP to the last parameter. If f i el d_ no is illegal
for the given map, the operation on that particular bit is ignored.

Prototype #i ncl ude

voi d map_man( unsi gned char *va_al i st , . . . ) ;

Parameters
map Pointer to the bitmap.
f i el d_ no Field (bit number) to reset.

Retur n Values Void

Dependencies Standard TXO C Library

See Als o map_clear(), map_test(), map_set(), map_reset()

Example The linked example code file demonstrates use of map_man().

map_reset()

Turns off the bit associated with the field number. If f i el d_ no is illegal for the
given map, this function does nothing.

Prototype #i ncl ude

voi d map_r eset ( unsi gned char *map, i nt f i el d_no) ;

Parameters
map Pointer to the bitmap.
f i el d_ no Field (bit number) to reset.

Retur n Values Void

Dependencies Standard TXO C Library, LEGAL_FIELD()

See Als o map_clear(), map_test(), map_set(), map_man()

Example The linked example code file demonstrates use of map_reset().

VERIX EVO ACT PROGRAMMERS GUIDE 245

F UNCTION C A L L S
map_set()

map_set()

Turns on the bit associated with the field number. If f i el d_ no is illegal for the
given map, this function does nothing.

Prototype #i ncl ude

voi d map_set ( unsi gned char *map, i nt f i el d_no) ;

Parameters
map Pointer to the bitmap.
f i el d_ no Field (bit number) to set.

Return Values Void

Dependencies Standard TXO C Library, LEGAL_FIELD()

See Als o map_clear(), map_test(), map_reset(), map_man()

Example The linked example code file demonstrates use of map_set().

map_test()

Returns the status of the bit in the bitmap corresponding to the field number. The
returned value is 0 if the bit is off, and 1 if it is on.

Prototype #i ncl ude

i nt map_t est ( unsi gned char *map, i nt f i el d_no);

Parameters
map Pointer to the bitmap.
f i el d_ no Field (bit number) to check.

Retur ns Values
Success: 1: The bit is set.

Failure: 0: The bit is off or an illegal field number was passed by the caller.

Dependencies Verix eVo SDK

See Als o map_clear(), map_set(), map_reset(), map_man()

Example The linked example code file demonstrates use of map_test().

246 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
pro ce ss_8 58 3()

process_8583()

Processes packing or unpacking of a packet by checking the bits in the map. For
each bit that is set, it either appends the formatted data to the outgoing packet or
disassembles the packet and stores the data into proper application variables as
indicated by the parameter how.

Prototype #i ncl ude

i nt pr ocess_8583( i nt how, f i el d st r uct *f i el d_t bl , unsi gned char *map,
unsi gned char *buf f er , i nt l i mi t ) ;

Parameters
how Pack or unpack.
f i el d_ t bl Field table.
map Bitmap to pack.
buf f er Buffer address.
l i mi t Maximum buffer size.

Retur n Values
Success:  0: Assembly: number of bytes placed in buf f er , which is used for write.
Disassembly: Number of bytes in buf f er not processed, which should be
zero.
Failure: -1: Field not defined in field table. The variable fn_8583 contains the field in
error.
-2: Stored more in buf f er than limit.
-3: Exceeded size of valid data in buf f er .
-4: Stored more than variable limit on an incoming message.
-5: No matching variant field definition.

Dependencies Verix eVo SDK

Example The linked example code file demonstrates use of process_8583().

set_dst_8583()

Sets the destination buffer of the ISO 8583 engine.

Prototype #i ncl ude

voi d set _dst _8583( unsi gned char *dest ) ;

Parameters
dest Data to set the destination buffer of the ISO 8583 engine.

Retur n Values None

Dependencies Used in all conversion routines that must set the destination buffer of the ISO
8583 engine.
VERIX EVO ACT PROGRAMMERS GUIDE 247

F UNCTION C A L L S
set_src_8583()

set_src_8583()

Sets the source buffer of the ISO 8583 engine.

Prototype #i ncl ude

voi d set _sr c_8583( unsi gned char *sr c) ;

Parameters
sr c Data to set the source buffer of the ISO 8583 engine.

Return Values None

Dependencies Used in all the conversion routines that must set the source buffer of the ISO 8583
engine.

str_to_asc()

Converts a null-terminated ASCII string to fixed-size ASCII string with blank

padding on the right, if necessary. If the count specified is less than the length of
the string, the string is truncated.

Prototype #i ncl ude

voi d s t r _ t o _ as c( i nt n) ;

Parameters
n Size of the ASCII string.

Return Values Void

Dependencies Standard TXO C Library, asc_to_asc()

str_to_av2()

Converts a null-terminated ASCII string to a 1-byte counted string. The count is in

BCD format.

Prototype #i ncl ude

voi d st r _ t o _ av2( i nt c ) ;

Parameters
c Required to be 1.

Return Values Void

Dependencies Verix eVo SDK

Retur n Values Void

Dependencies Verix eVo SDK

VERIX EVO ACT PROGRAMMERS GUIDE 249

F UNCTION C A L L S
str_to_xbc()

str_to_xbc()

Converts a null-terminated ASCII string to a BCD string while preserving the first
byte of the source. The first byte must contain one of the two following values:
• C: Denotes a credit transaction.
• D: Denotes a debit transaction.

Prototype #i ncl ude

voi d st r _ t o _ xbc ( i nt n) ;

Parameters
n Size of the BCD string.

Return Values Void

Dependencies Standard TXO C Library, str_to_bcd()

xbc_to_str()

Converts a BCD string to a null-terminated ASCII string while preserving the first
byte of the source. The first byte must contain one of the two following values:
• C: Denotes a credit transaction.
• D: Denotes a debit transaction.

Prototype #i ncl ude

voi d xbc _t o_ s t r ( i nt n) ;

Parameters
n Size of null-terminated ASCII string.

Return Values Void

Dependencies Standard TXO C Library, bcd_to_str()

250 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
PIP Engine Function Calls

PIP Engin e This section describes the following PIP Engine function calls:
Function Calls
• check_8583_tpdu_msg_id() • prot_8583()

• find_field_index() • prot8583_main()

• pip_main() • save_8583_tpdu_msg_id()

• pip_trans() • set_tpdu_length()

check_8583_tpdu_msg_id()

Verifies a valid match between the current values of the TPDU and message ID
found in the field table, and the values passed in the call. This comparison
requires that the TPDU and message ID are stored as packed numeric (BCD)
values.
This function is used by pip_trans() and prot_8583(). In addition, this function can
be used in other places in the application.
Both the TPDU and the message ID are used in the transmit packet.

Prototype #i ncl ude <pr ot 8583. h>

#i ncl ude <acl f i l e. h>
i nt check_8583_t pdu_msg_i d( COMM_8583_DATA *c ont r ol , unsi gned char
*or i g_t pdu, unsi gned char *or i g_msg_i d) ;

Parameters
cont r ol Pointer to the data structure used by the ISO 8583 Protocol Engine.
or i g_t pdu Pointer to the buffer containing the original TPDU.
ori g_msg_i d Pointer to the buffer containing the original message ID.

Retur n Values
Success: 1: The TPDU and message ID match.

Failure: errno set to PROT8583_RCV_TPDU_ERROR: TPDU is incorrect.

errno set to PROT8583_RCV_MSG_ID_ERROR: Message ID is incorrect.

errno set to PROT8583_BAD_TPDU_MSG_ID: Both the TPDU and

message ID are incorrect.

VERIX EVO ACT PROGRAMMERS GUIDE 251

F UNCTION C A L L S
fi nd _f ie ld _ind ex ()

find_field_index()

Searches a field table array for a specific field entry. This function is used by the
pip_trans() function.

CAUTION There is no mechanism within the function to determine the validity of the
field_struct-type pointer passed to it. Passing an invalid field_struct pointer to the
function causes invalid results.

Prototype #i ncl ude <amexhost . h>

#i ncl ude <acl st r . h>
#i ncl ude 
f i el d_ s t r uc t * f i nd_ f i el d_ i ndex( i nt s ear c h_ num, f i el d_ s t r uc t * pt r ) ;

Parameters
sear ch_num The field for which to search.

pt r The field table array to search.

Return Values
Success: The address of the array element.

Failure: NULL if requested field is not found.

pip_main()

Passes pointers to the map buffer, pointer to the message ID buffer, pointer to
processing code, and a function pointer to user-defined set_trans_field function.
The first three buffers are filled by the application before these are used by the
PIP Engine.

Prototype #i ncl ude <por t def . h>

voi d pi p_mai n( unsi gned char * t map, char *t msgi d, char * t pr occode,
Fxn f unc ) ;

Retur n Values None

Dependencies For any application, pip_main() must be called in mai n( ) before using the PIP
Engine. Also, note that the fourth parameter can be null if the application wants to
use the default s et _ t r ans _f i el d function provided in PIP engine.

252 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
pi p_ tran s()

pip_trans()

Provides advice message processing and an interface to the ISO 8583 Protocol
Engine. This function sets up AMEX host (PIP) processing, and defines the
transaction type and initializes the host data structure.

NOTE • Verix eVo ACT library checks for the cancel key operation during PIP transaction. If the
DISABLECANKEYPIP c onf i g. s ys entry is set to 1, then Verix eVo ACT library
ignores the cancel key pressed during the PIP transaction.
• If the DISABLECANKEYPIP c onf i g. s ys entry is set to 0, or the config entry is not
found, then Verix eVo ACT library checks for the cancel key press and aborts the PIP
transaction if it is pressed.
• For more information on the PIP specification, refer to the AMEX Express 3000 PIP
Terminal Technical Specifications (available from American Express).

Prototype #i ncl ude <amexhost . h>

#i ncl ude <acl st r . h>
#i ncl ude 
i nt pi p_t r ans( i nt t r ans_t ype, HOST_8583_DATA *host _st r uct ) ;

Parameters
t r ans_t ype Informs pip_trans() of the requested transaction. Valid values are:

• A_AUTH_TRANS 0x0028 /* 0x0028 or 00101000b */

• A_REFUND_TRANS 0x0009 /* 0x0009 or 00001001b */

• A_SALE_TRANS 0x0008 /* 0x0008 or 00001000b */

• A_VOID_CREDIT 0x000d /* 0x000d or 00001101b */

• A_VOID_DEBIT 0x000c /* 0x000c or 00001100b */

• A_REFUND_OFFLINE 0x0011 /* 0x0011 or 00010001b */

• A_SALE_OFFLINE 0x0010 /* 0x0010 or 00010000b */

• A_VOID_CR_OFFLINE 0x0015 /* 0x0015 or 00010101b */

• A_VOID_DB_OFFLINE 0x0014 /* 0x0014 or 00010100b */

• A_ADJUST_CREDIT 0x0013 /* 0x0013 or 00010011b */

• A_ADJUST_DEBIT 0x0012 /* 0x0012 or 00010010b */

• A_SEND_ADVICE 0x000b /* 0x000b or 00001011b */

• A_SEND_REVERSAL 0x000a /* 0x000a or 00001010b */

• A_CLOSE_BEGIN 0x0018 /* 0x0018 or 00011000b */

• A_CLOSE_DETAIL 0x0038 /* 0x0038 or 00111000b */

• A_DCP_REVERSAL 0x0048 /* 0x0048 or 01001000b */

• A_CLOSE_END 0x0078 /* 0x0078 or 01111000b */

host _st r uct Pointer to the structure used by the PIP Engine that contains all the
required information to complete a transaction with the AMEX host.

VERIX EVO ACT PROGRAMMERS GUIDE 253

F UNCTION C A L L S
pi p_ tran s()

Retur n Values
Success: 1: Transaction type and structure data successfully passed to application.

Failure: AMEXHOST_ADJUST_ERROR (-64)

AMEXHOST_DUPKEY_ERROR (-65)

AMEXHOST_VOID_ERROR (-66)

AMEXHOST_INVADV_ERROR (-67)

AMEXHOST_INV_OPTION (-68)

PIP_NOT_ONLIN (-69)

AMEX_VOICE_AUTH (-70)

AMEX_DCP_APPROVAL (-71)

AMEX_NO_ADVICE (-72)

AMEX_DCP_REVERSAL (-73)

HOST_ERROR (-74)

NOTE
errno may provide additional information.

The following options are defined in AMEXHOST. H. Transaction codes are

bitmapped according to the following table (with the exception of close packets
and transmission of advice packets):

Bit Posit ion Desc ript ion

1 1 = Credit / 0 = Debit
2 1 = Adjustment transaction
3 1 = Void transaction
4 1 = Online transaction
5 1 = Offline transaction
6 1 = Close packets
7 1 = Close upload
8 1 = Final close

host _st r uct must be properly initialized following the HOST_8583_DATA

structure as defined in AMEXHOST. H.

254 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
pi p_ tran s()

The pip_trans() function only uses the lower byte of the trans_type parameter,
which it passes to the AMEX host module. This module uses the lower byte to
determine the type of transaction being processed (as defined in AMEXHOST. H).
The AMEX host module passes the trans_type parameter to the
s et _ t r ans _f i el ds ( ) function (application defined). This function may use both
the lower and upper bytes to complete any additional transaction information
required by the application.

NOTE
The lower byte should only use assigned values defined in AMEXHOST. H. The
upper byte can be assigned any value.

In the following example, the application uses the lower byte to define a valid
AMEX transaction, and the upper byte to define the bitmap, message ID, and
processing code associated with the transaction.
#i ncl ude " amexhost . h"
/ * A_ADJ UST_CREDI T and A_ADJ UST_DEBI T ar e def i ned i n AMEXHOST. H. */
#def i ne ADJ UST_CREDI T ( 0x1000 | A_ADJ UST_CREDI T)
/ * 0x0013 or 00010011b */
#def i ne ADJ UST_DEBI T ( 0x1100 | A_ADJ UST_DEBI T)
/ * 0x0012 or 00010010b */
/ * Fi l e For mat
* Recor ds 0 - 20 = Bi t map I ndex, Mess age I D I ndex, and Pr ocessi ng Code
I ndex
* Recor ds 21 - 35 = I SO 8583 Bi t maps
* Recor ds 36 - 45 = I SO Mess age I Ds
* Recor ds 46 - 53 = I SO Pr ocessi ng Codes
*/
10 Tr an Code 10=" 33, 42, 52"
/ * AMEX Sal e */
11 Tr an Code 11=" 33, 42, 53"
/ * AMEX Ref und */
/ * Tr ansacti on bi t maps def i nes f or AMEX and Ci t i */
33 Bi t map 8 =" \ x30\ x20\ x05\ x80\ x00\ xc0\ x00\ x0c"
/ * AMEX Fi nanci al */
/ * Message I Ds f or AMEX and Ci t i */
42 Message I D 2 =" \ x02\ x00"
/ * Fi nanci al Tr ansacti on */
/ * Pr ocessi ng Codes f or AMEX and Ci t i */
52 Pr oc Code 1 ="\ x00\ x40\ x00"
/ * Sal e, Of f l i ne Sal e, Aut h * /
53 Pr oc Code 2 ="\ x02\ x40\ x00"
/ * Voi d DB, DB Adj ust */

VERIX EVO ACT PROGRAMMERS GUIDE 255

F UNCTION C A L L S
pro t_ 8583 ()

prot_8583()

This function is called by the PIP Engine and provides the following functionality:
• an interface to the ISO 8583 Message Engine to assemble and disassemble
packets.
• an interface to the application-defined validation function used to determine if
an appropriate response was received.
• an interface to the application-defined communications function used to
transmit and receive request/response messages.
• processes reversals as specified in the ISO 8583 standard.

NOTE • Verix eVo ACT library checks for the cancel key operation during PIP
transaction.
• If the DISABLECANKEYPIP conf i g. sys entry is set to 1, then Verix eVo
ACT library ignores the cancel key pressed during the PIP transaction.
• If the DISABLECANKEYPIP conf i g. sys entry is set to 0 or the config entry
is not found, then Verix eVo ACT library checks for the cancel key press and
aborts the PIP transaction if the cancel key is pressed.

Prototype #i ncl ude <pr ot 8583. h>

#i ncl ude <acl f i l e. h>
i nt pr ot _8583( COMM_8583_DATA *cont r ol _dat a, i nt r ev_opt ,
unsi gned r esp_t i meout ) ;

Parameters
cont r ol _dat a Must be a properly initialized COMM_8583_DATA structure.
r ev_opt Determines the reversal processing required and must be one of the
following, (as defined in PROT8583. H):
• REV_ON: Normal reversal processing.
• REV_OFF: No reversal processing.
• REV_ONLY: Process only a pending reversal, if one exists.

r esp_t i meout Defines the time, in seconds, allowed to receive a response to a

request. This time-out is passed to the transceiver function and is not
referenced internally.

Return Values
Success: PROT8583_SUCCESS

Failure: PROT8583_PARM_ERROR: Illegal parameter passed in the call.

PROT8583_REVERSAL_FILE_ERROR: Error occurred accessing the

reversal file.

PROT8583_FAILED_REVERSAL: Error occurred processing the reversal.

PROT8583_CREATED_REVERSAL: Request resulted in a reversal

beings created.

256 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
pro t_ 85 83 ()

PROT8583_FAILED_TRANSMIT: Request could not be processed.

PROT8583_CLR_KEY: gu_clr_state variable was set to 1 on a clear key

press.

PROT8583_UNPACK_ERROR: Error occurred unpacking the response.

-17: A field is not defined in the field table.

-18: While parsing the outgoing packet, more data was stored in the buffer
than the specified limit (packet size).

-19: While unpacking the incoming packet, the packet size is larger than
the size specified in the field table.

-20: While unpacking the incoming packet, the data parsed for a variable is
larger than the size specified in the field table.

-21: No matching variant in the variant table.

The errno variable returns additional error information. Always examine errno if

the function fails. Error return values are defined in PROT8583. H. Any errors
passed from the transmit/receive and any errors from the validation process are
also returned.

NOTE
If r esp_t i meout is zero, the member in the control data structure, comm_ t i meout ,
must be greater than zero.

Two functions must be provided: the transmit/receive function and the validation
function. Both of these functions must have a return type of int.
The validation function is called after receiving a response. This function can
return the following values:

Success: 0

Failure: -1 to -14: Use if the validation routine fails and you do not want to wait for
another response packet.

 1: Indicates the new time-out value (in seconds) to use to wait for
another response packet.

RETRY_CURRENT_TIMEOUT: Waits for another response packet using

the current time-out value.

VERIX EVO ACT PROGRAMMERS GUIDE 257

F UNCTION C A L L S
pro t8 583_ ma in ()

prot8583_main()

Passes a function pointer to a callback function used to modify the contents of

reversal data if required by the specific host. If the application does not want to
update the contents, a null pointer is passed.

Prototype #i ncl ude <pr ot 8583. h>

i nt pr ot 8583_mai n( RevFxn f unc) ;
t ypedef i nt ( *RevFxn) ( COMM_8583_DATA *cont r ol _dat a) ;

Parameters
RevFxn f unc User defined function pointer to modify the reversal data.

Return Values None.

Dependencies prot8583_main() must be called by the application before performing any PIP-

related transactions.

save_8583_tpdu_msg_id()

Copies the TPDU and message ID from the application variable to the destination
buffer. This function is primarily used by the pip_trans() and prot_8583() functions.

Prototype #i ncl ude <pr ot 8583. h>

#i ncl ude <acl f i l e. h>
voi d save_8583_t pdu_msg_i d( COMM_8583_DATA *c ont r ol , unsi gned char
*dest _t pdu, unsi gned char *dest _msg_i d) ;

Parameters
cont r ol Pointer to the structure used to find the variable declared in the field
table.
dest_ t pdu Pointer to the buffer to store the TPDU.
dest _msg_i d Pointer to the buffer to store the message ID.

Return Values None.

258 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
set_tpdu_length()

set_tpdu_length()

Allows the user to set the length of the TPDU field for the PIP processing.

NOTE
The device handle must be valid.

Prototype #i ncl ude

i nt set _t pdu_l engt h( i nt i nTPDULengt h) ;

Parameters
i nTPDULengt h Length of the TPDU field. Pass zero if absent.

Retur n Values
Success: TPDU_PARAM_SUCCESS

Failure: -1 to -14: Use if the validation routine fails and you do not want to wait for
another response packet. INVLD_ORDER (-2)

TPDU_PARAM_INVALID (< 0)

TPDU_PARAM_ERROR (> MAX_TPDU_LENGTH (32 bytes))

NOTE
set _t pdu_l engt h( ) must be called by the application if the TPDU field is
present and its length is not 5 bytes (default value).

VERIX EVO ACT PROGRAMMERS GUIDE 259

F UNCTION C A L L S
Da ta Capt ure En gi ne Fu nc ti on Call s

Data Capt ur e The Data Capture Engine allows short integers, long integers, characters, and
Engine strings to be stored and retrieved from keyed files. The calling application
Function Calls specifies the application variable indicating the source or destination of the data,
the files for storage, the operation desired (write or read), and the type of
conversion required. The Data Capture Engine completes the conversion and
accesses the data file as required. This is accomplished using a single function,
dce_key_cvt().
This section describes the following data capture function calls:

• dce_key_cvt() • DCE_PUTCFG_C()

• DCE_GETCFG_C() • DCE_PUTCFG_S()

• DCE_GETCFG_S()

The application programmer can create other macros as required, but should not
modify the standard macros provided in ACDCE. H. Any modification of standard
macros can introduce confusion and problems in the maintenance of the
application.

260 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
dce_key_cvt()

dce_key_cvt()

Access function for Data Capture Engine keyed file. This function permits
application data to be written to and read from keyed files, and completes any
required data conversion using functions provided by the ACL.
The Data Capture Engine does not attempt to create a keyed file; the file must
exist prior to requesting any Data Capture Engine operation. The specified file
does not have to be open; this function opens the file, performs the operation, and
closes it automatically. If the file is not already open, a file handle is obtained from
the operating system, and released on completion of the operation.
The data is not validated to be of the type specified in the call. The caller is
expected to call the Data Capture Engine and correctly specify the data type. The
result of requesting an operation with an incorrect data type is undefined.

Prototype #i ncl ude <acdce. h>

i nt dce_key_cvt ( unsi gned char pr ocess, char *f i l e, char *key, unsi gned
char cnvt , DCE_KEY_DATA dat a) ;

Parameters
pr ocess Valid values are:
• DCE_ READ
• DCE_WRI TE

file Name of the keyed file.

key Keyed record identifier.
cnvt Data type valid values are:
• DCE_I
• DCE_ UI
• DCE_L
• DCE_ UL
• DCE_C
• DCE_S

dat a Source or destination data address.

Retur n Values
Success: 1

Failure: -1: Filename is null.

-2: Key is null or does not exist.

-3: Unsupported data type specified.

-4: File handle or file not available.

VERIX EVO ACT PROGRAMMERS GUIDE 261

F UNCTION C A L L S
dce_key_cvt()

NOTE • When reading previously stored information, the data type can be specified as
a character string. This may be useful when the data is to be displayed,
printed, and so on.
• For example, storing the value 100 to a keyed file results in the conversion of
the value to the ASCII string “100”. If the value is then read as a string variable,
the string “100” is placed in the application buffer. This does not affect the
ability to later read the data as a signed or unsigned integer.
• This concept applies to each of the macros listed in this manual that end with
_I, _L, _UI and _UL.

See Als o put key( ) , get key( )

Dependencies ACL: st r 2di gi t ( ) , st r 2i nt ( ) , st r 2l ong( ) , i nt 2st r ( ) , l ong2st r ( )

262 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
DCE_ GETCFG _C()

DCE_GETCFG_C()

This macro call is the same as dce_key_cvt(), except that the filename is supplied
as CONFIG.SYS, the process is supplied as read, and the data type is supplied as
character.

Prototype #i ncl ude <acdce. h>

i nt DCE_GETCFG_C( char *key, DCE_KEY_DATA dat a) ;

Parameters
key Keyed record identifier.
dat a Destination data address.

Retur n Values
Success: 1

Failure: -2: key is null or does not exist.

See Als o Application Construction Engine Data Capture function: dce_key_cvt()

DCE_GETCFG_S()

This macro call is the same as the dce_key_cvt() function, except that the
filename is supplied as CONFIG.SYS, the process is supplied as read, and the
data type is supplied as string.

Prototype #i ncl ude <acdce. h>

i nt DCE_GETCFG_S ( char *key, DCE_KEY_DATA dat a) ;

Parameters
key Keyed record identifier.
dat a Address of source data.

Retur n Values
Success: 1

Failure: -2: key is null or does not exist.

See Als o Application Construction Engine Data Capture function: dce_key_cvt()

VERIX EVO ACT PROGRAMMERS GUIDE 263

F UNCTION C A L L S
DC E_PU TCFG_C ()

DCE_PUTCFG_C()

This macro call is the same as dce_key_cvt(), except that the filename is supplied
as CONFIG.SYS, the process is supplied as write, and the data type is supplied
as character.

Prototype #i ncl ude <acdce. h>

i nt DCE_PUTCFG_C( char *key, DCE_KEY_DATA dat a) ;

Parameters
key Keyed record identifier.
dat a Address of source data.

Return Values
Success: 1

Failure: -2: key is null.

See Als o Application Construction Engine Data Capture function: dce_key_cvt()

DCE_PUTCFG_S()

This macro call is the same as dce_key_cvt(), except that the filename is supplied
as CONFIG.SYS, the process is supplied as write, and the data type is supplied
as string.

Prototype #i ncl ude <acdce. h>

i nt DCE_PUTCFG_S( char *key, DCE_KEY_DATA dat a) ;

Parameters
key Keyed record identifier.
dat a Address of source data.

Return Values
Success: 1

Failure: -2: key is null.

See Als o Application Construction Engine Data Capture function: dce_key_cvt()

264 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
Mode m Engi ne Fu nc ti on Call s

Modem Engin e This section describes the following modem engine function calls:
Function Calls
• inInitModem() • xmdm_dial_status()

• inOpenModem() • xmdm_failed_output_pending()

• vdCheckDataMode() • xmdm_flush()

• vdSetEchoMode() • xmdm_get_line_dial()

• xhayes_control() • xmdm_hangup()

• xhayes_display() • xmdm_init()

• xhayes_flush() • xmdm_input_pending()

• xhayes_response() • xmdm_open()

• xhayes_send_cmd() • xmdm_output_pending()

• xhayes_status() • xmdm_receive_data()

• xmdm_check_status() • xmdm_send_data()

• xmdm_checkline() • xmdm_set_attrib()

• xmdm_clear() • xmdm_set_protocol()

• xmdm_close()

VERIX EVO ACT PROGRAMMERS GUIDE 265

F UNCTION C A L L S
inInitModem()

inInitModem()

Initializes the modem by receiving environment variable numbers as parameters.

It adds “M” with each number passed by the application and obtains the command
strings specified by this environment variable.

Prototype #i ncl ude <XMODEM. H>

i nt i nI ni t Modem( i nt h_modem, i nt i _max_wai t , i nt va_al i st , . . . ) ;

Parameters
h_ modem Opened modem device handle.
max_ wai t Maximum amount time, in seconds, to wait for a response.
va_ al i s t Environment variable number of init string commands to send.

Return Values
Success: SUCCESS: Initialization successful.

Failure: E_INVALID_PARM: Invalid parameter passed.

E_WRITE: Write to the modem fails.

value < 0: Hayes response for the command.

Example i nt max_wai t ;
i nt h_modem;
r esul t = i nI ni t Modem( h_modem, 5, 1, 2, 3, 4, 5, 6, - 1) ;

NOTE This function can be used to send any number of initialize commands. It should be
passed with numeric values. The function appends “M” to the passed numeric,
and looks for the environment variables. So, for the above example, it looks for
environment variables “M1”, “M2”, “M3”, “M4”, “M5,” and “M6”. The parameters
should be terminated with -1.
If the CONFIG.SYS environment variable is non-populated, it skips and continues
to the next CONFIG.SYS environment variable. The user is informed about this by
means of LOG_PRI NTF statement.

266 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
inOpenModem()

inOpenModem()

Opens the modem, as specified in por t and obtains the resulting modem
response. h_ modemcontains the handle returned by the open( ) call. It opens the
port and sets the protocol parameters. If por t is null or empty, then the device
MDM_PORT is opened.
This call is a simplified version of xmdm_open().

NOTE This function opens the modem port, sets the baud and formats parameters. It
does not send any initialization commands. To initialize the port, use
i nI ni t Modem( ) .

Prototype #i ncl ude <XMODEM. H>

i nt i nOpenModem( i nt *h_modem, char *por t , i nt Baud, i nt For mat ) ;

Parameters
h_ modem Pointer to the modem handle.
port Pointer to the modem port string.
rate Rate of connection.
f or mat Connection format.

Retur n Values
Success: SUCCESS: Execution successful.

Failure: E_WRITE_BLK: Failure to write port setup with MDM_WRITE_BLK().

E_OPEN: open() command unsuccessful.

Example i nt r et Val ;
i nt h_modem;
r et Val = i nOpenModem ( &h_modem, NULL, Rt _2400, Fmt _A7N1) ;

VERIX EVO ACT PROGRAMMERS GUIDE 267

F UNCTION C A L L S
vdCheckDataMode()

vdCheckDataMode()

Sets the parameter for checking the data mode before sending any command to
the modem. xhayes_send_cmd() checks for this and if set to TRUE, checks for
the data mode before sending the command. If set to FALSE, it does not perform
any data mode checking. Default is TRUE for backward compatibility.

Prototype #i ncl ude <XMODEM. H>

voi d vdCheckDat aMode( i nt mode) ;

Parameters
mode Parameter to enable or disable check for data mode before sending the
command.

Return Values None.

Example vdCheckDat aMode( TRUE) ;

vdCheckDat aMode( FALSE) ;

vdSetEchoMode()

Sets the parameter for echo mode ON or OFF in the command response. It is
used in conjunction with xmdm_open(). If echo mode is set to TRUE, the user
must provide the init string with echo on. If echo mode is set to FALSE, the library
initializes the port with echo off.

Prototype #i ncl ude <XMODEM. H>

voi d vdSet EchoMode( i nt set echo) ;

Parameters
set echo Parameter to set or reset the echo mode command response.

Return Values None.

NOTE Call function before calling xmdm_open( ) . If set to TRUE, xmdm_open( ) adds
“E1” to the user-defined init string.
If set to FALSE, xmdm_open( ) adds “E0” to the user-defined command string.
The default value is FALSE for backward compatibility.

Example vdSet EchoMode( TRUE) ;

vdSet EchoMode( FALSE) ;

268 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xh ay es _c on tro l()

xhayes_control()

Sends a Hayes command to the modem and returns a Hayes status code.

NOTE xhayes_cont r ol ( ) uses xhayes_send_cmd( ) to send the command string

and xhayes_st at us( ) to return the numeric response code once the command
is sent.

Prototype #i ncl ude <XMODEM. H>

i nt xhayes_cont r ol ( i nt h_modem, i nt h_cl ock, i nt max_wai t , char command,
char *buf f er ) ;

Parameters
h_ modem Modem device handle.
h_cl ock Clock device handle.
max_ wai t Maximum wait time (seconds). If no limit on the amount of time in which to
access the modem is desired, set max_ wai t to zero so that the function
never times out, but only returns with the first response from the modem.
command Command to execute.
buf f er Buffer address.
For the Hayes “Dial” command (“D”), buf f er must be a string containing
the phone number and any other valid dial command characters, plus four
additional bytes used internally for Hayes formatting.
For the Hayes “Check Line” command (“-”) and “Hang Up” command (“H”),
buf f er must be at least four bytes in length.

Retur n Values
Success: 0 - 91: Numeric Hayes response (see Table 17).

Failure: E_FORMAT_CMD: Formatting of the Hayes command failed.

E_WRITE_CMD: Hayes write command failed.

E_HR_TIMEOUT: Allotted time specified by max_ wai t exceeded.

E_READ_CMD: Command to access the Hayes response failed.

E_ONLY_CR: Only a single carriage return was received in reply.

Command was not “D”, “H”, or “-”.

Example The linked example code file demonstrates use of xhayes_control().

VERIX EVO ACT PROGRAMMERS GUIDE 269

F UNCTION C A L L S
xh ay es _d ispl ay ()

xhayes_display()

Translates a Hayes modem response code to its descriptive text equivalent,

storing the string at the specified buffer address.

Prototype #i ncl ude <XMODEM. H>

i nt xhayes_di spl ay(i nt hayes_code, char *buf f er ) ;

Parameters
hayes_code Hayes modem response code.
buf f er Buffer address.

Return Values
Success: SUCCESS: Hayes response code is valid.

Failure: See Table 17.

NOTE
XMODEM. H contains a list of valid Hayes response codes. The buffer must be at
least 14 bytes in length to accommodate the returned string.

Invalid response codes are returned in buf f er , and the function returns with
FAILURE.
Table 17 Hayes Failure Codes
Numeric Hayes Code Hayes String
0 HAYES_OK “OK”
1 CONNECT_300 “CONNECT 300”
2 RING_DETECT “RING”
3 NO_CARRIER “NO CARRIER”
4 HAYES_ERROR “ERROR”
5 CONNECT_1200 “CONNECT 1200”
6 NO_DIALTONE “NO DIAL TONE”
7 BUSY_DETECT “BUSY”
8 NO_ANSWER “NO ANSWER”
10 CONNECT_2400 “CONNECT 2400”
11 CONNECT_4800 Hayes “CONNECT 4800” status.
12 CONNECT_9600 Hayes “CONNECT 9600” status.
13 CONNECT_7200 Hayes “CONNECT 7200” status.
14 CONNECT_12000 Hayes “CONNECT 12000” status.
15 CONNECT_14000 Hayes “CONNECT 14000” status.
16 CONNECT_19200 Hayes “CONNECT 19200” status.
17 CONNECT_38400 Hayes “CONNECT 38400” status.
18 CONNECT_57600 Hayes “CONNECT 57600” status.
19 CONNECT_115200 Hayes “CONNECT 115200” status.

270 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xh ay es_d is play ()

Table 17 Hay es Fai lure Codes (continued)

Numeric Hayes Code Hayes String
22 CONNECT_75TX_ Hayes “V.23 originate connection establish”
1200RX status.
23 CONNECT_1200TX_ Hayes “V.23 answer connection establish” status.
75RX
24 DELAYED Hayes “COUNTRY SPECFIC BLACKLIST” status.
32 BLACKLISTED Hayes “number dialed is blacklisted” status.
35 DATA Hayes “data modem connection” status.
40 CARRIER_300 Hayes “0-300 data rate” status.
44 CARRIER_1200_75 Hayes “V.23 backward channel carrier” status.
45 CARRIER_75_1200 Hayes “V.23 forward channel carrier” status.
46 CARRIER_1200 Hayes “1200 data rate” status.
47 CARRIER_2400 Hayes “2400 data rate” status.
48 CARRIER_4800 Hayes “4800 data rate” status.
49 CARRIER_7200 Hayes “7200 data rate” status.
50 CARRIER_9600 Hayes “9600 data rate” status.
51 CARRIER_12000 Hayes “12000 data rate” status.
52 CARRIER_14400 Hayes “14400 data rate” status.
66 COMPRESSION_ Hayes “MNP CLASS 5 COMPRESSION 2400”
CLASS5 status.
67 COMPRESSION_ Hayes “MODEM CONNECT AT V42BIS” status.
V42BIS
69 COMPRESSION_ Hayes “MODEM CONNECT WITH NO DATA
NONE COMPRESSION” status.
70 PROTOCOL_NONE Hayes “NO ERROR CORRECTION PROTOCOL”
status.
77 PROTOCOL_LAPM Hayes “PROTOCOL LAPM” status.
80 PROTOCOL_ALT Hayes “PROTOCOL ALT” status.
90 VFI_NO_LINE “VFI NO LINE”
91 VFI_DIALTONE “VFI DIAL TONE”

Example The linked example code file demonstrates use of xhayes_display().

VERIX EVO ACT PROGRAMMERS GUIDE 271

F UNCTION C A L L S
xh ay es_f lu sh()

xhayes_flush()

Clears the command response buffer from the modem device. The r ead( )
function is called until the response buffer is empty. This function returns
immediately.

NOTE Issuing a call to xhayes_f l ush( ) immediately after xhayes_send_cmd( ) or

wr i t e( ) , effectively results in the buffer not being cleared. Some commands,
such as “H” (hangup/go on-hook), require more than one second of real time to
complete and elicit a valid Hayes response to the request. A 100-ms delay is
generally adequate between commands and responses.

xhayes_flush() can be useful when called just before a dial command to remove

old responses that may still be in the modem devices response queue.

Prototype #i ncl ude <XMODEM. H>

i nt xhayes_f l ush( i nt h_modem) ;

Parameters
h_ modem Opened modem device handle.

Return Values
Success: SUCCESS: The Hayes response buffer cleared successfully.

Failure: E_READ_CMD: r ead( ) function returned FAILURE.

Example The linked example code file demonstrates use of xhayes_flush().

272 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xh ay es_re spon se ()

xhayes_response()

Reads a Hayes modem command response and converts the command into a
Hayes code integer value. Use xhayes_response() to obtain a valid Hayes
response code following any modem command.

Prototype #i ncl ude <XMODEM. H>

i nt xhayes_r esponse(i nt h_modem, i nt h_cl ock, i nt max_wai t ) ;

Parameters
h_ modem Opened modem device handle.
h_cl ock Clock device handle.
max_ wai t Maximum amount time, in seconds, to wait for a response. If no timeout is
desired, set max_ wai t to zero

Retur n Values The value returned is the Hayes numeric response value, which is an integer and
is in the allowed range of valid Hayes numeric response codes, see Table 8.

Failure: E_READ_CMD: The command to access status response was unsuccessful.

E_HR_TIMEOUT: A response cannot be obtained in less than or equal to the

number of seconds specified by max_wait.

E_ONLY_CR: Hayes response returned from the modem is a single carriage

return only.

NOTE xhayes_di spl ay( ) can be called to convert the Hayes response return value
to a display string. If echo is enabled then the echo response is ignored and the
Hayes numeric response is returned.

Example The linked example code file demonstrates use of xhayes_response().

VERIX EVO ACT PROGRAMMERS GUIDE 273

F UNCTION C A L L S
xh ay es_sen d_ cm d()

xhayes_send_cmd()

Converts the input string into Hayes format and sends the resulting command
string to the modem.
If vdCheckDataMode() is set to TRUE, this function checks if the modem is in data
mode or command mode before sending the command.
If vdCheckDataMode() is set to FALSE, this function does not perform any
checking before sending the command.
By default, vdCheckDataMode() is set to TRUE so the function performs a data
mode check.

Prototype #i ncl ude <XMODEM. H>

i nt xhayes_ send_c md( i nt h_ modem, char * cmd_buf f ) ;

Parameters
h_ modem Opened modem device handle.
cmd_buf f Command buffer string. cmd_buf f points to the command buffer string
that contains a valid, null-terminated string, such as “D555-1234”, “H” or
“S0= 1”. It must also be large enough to accommodate two additional
command characters, “AT” and <CR> (three bytes total). Upon return,
cmd_buf f contains the fully formatted Hayes command. If the returned
length of cmd_buf f is not equal to the return value of
xhayes_send_cmd(), an error occurred.

Return Values The number of bytes written to the modem.

Failure: E_WRITE_CMD: Unsuccessful write to modem. This value is returned as a

result of write() returning an error code.

NOTE The value returned is the number of bytes sent to the modem. Any value less than
3 should be interpreted as a send command error, since “AT\ r” is the shortest
possible command.

Example The linked example code file demonstrates use of xhayes_send_cmd().

274 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xh ay es_s ta tu s()

xhayes_status()

Obtains the Hayes response from the mode. This function calls the
xhayes_response() and returns the response.

Prototype #i ncl ude <XMODEM. H>

i nt xhayes_st at us( i nt h_modem, i nt h_cl ock, i nt wai t _t i me) ;

Parameters
h_ modem Modem handle.
h_cl ock Clock device handle.
wai t _t i me Specifies the maximum amount of time, in seconds, to receive the Hayes
response. Set this to zero if no time out is desired.

Retur n Values Refer to the xhayes_response() return values.

Example The linked example code file demonstrates use of xhayes_status().

VERIX EVO ACT PROGRAMMERS GUIDE 275

F UNCTION C A L L S
xm dm_c he ck _s tatu s()

xmdm_check_status()

Returns the current modem signal information, including CTS, DCD, framing error,
overrun error, parity error, and break or abort. The st at _map parameter indicates
which signal(s) to check. Each signal is defined in XMODEM.H and can be
combined for example, E_PARI TY_ FRAME| E_FRAME_OVERRUN.

Prototype #i ncl ude<XMODEM. H>

i nt xmdm_c heck_ st at us( i nt h_modem, unsi gned char s t at _map) ;

Parameters
h_ modem Modem handle.
st at _map Signal(s) of interest. Valid values are:
• E_PARITY
• E_OVERRUN
• E_PARITY_OVERRUN
• E_FRAMING
• E_PARITY_FRAME
• E_FRAME_OVERRUN
• MDM_BREAK
• MDM_CTS
• MDM_DCD

Return Values
Success: 1: At least one signal in stat_map was set.

Failure: 0: None of the signals in stat_map were set.

-1: Modem status command failure: ioctl() failed.

Example The linked example code file demonstrates use of xmdm_check_status().

276 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _c he ck line ()

xmdm_checkline()

Checks if an active telephone line is connected to the terminal.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_c heckl i ne( i nt h_modem) ;

Parameters
h_ modem Opened modem device handle.

Retur n Values
Success: SUCCESS: Phone line present.

Failure: VFI_NO_LINE: Phone line not present.

E_WRITE: Write to the modem failed.

E_HR_TIMEOUT:A response could not be obtained. Timed out.

Example The linked example code file demonstrates use of xmdm_checkline().

VERIX EVO ACT PROGRAMMERS GUIDE 277

F UNCTION C A L L S
xm dm _c le ar()

xmdm_clear()

Closes and re-opens the modem device.

NOTE The modem device should be in initialized state before calling xmdm_cl ear ( )
API. If h_ modemis non-zero, xmdm_cl ear ( ) refers to the opened modem
device, if h_ modemis zero, then xmdm_cl ear ( ) API behaves similar to
xmdm_open( ) API. xmdm_set _pr ot ocol ( ) API is used to initialize the modem.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_cl ear ( i nt h_modem, char *sz _mdm_name, i nt h_cl ock, i nt wai t _t i me,
i nt r a t e, i nt f or mat ) ;

Parameters
h_ modem Modem handle.
sz_mdm_name Modem access path.
h_cl ock Clock device handle.
wai t _t i me Maximum response time (seconds).
rate Rate of connection.
f or mat Connection format.

Return Values
Success: > 0: Successful initialization, open modem handle value returned.

Failure: E_OPEN: Failure to open modem with open().

E_CLOSE: Failure to close modem with close().

E_FW_READ_CMD: Modem opened. Unsuccessful read() while trying to

access firmware status.

E_FW_ONLY_CR: Modem opened. Hayes response received during

firmware open was single carriage return character, <CR>.

E_FW_TIMEOUT: Allotted time in which to receive Hayes response

expired while obtaining firmware status.

E_FW_STATUS: Modem opened. Hayes error response as result of

firmware initialization.

E_MI_READ_CMD: Modem opened. Unsuccessful read() while trying to

access the CONFIG.SYS environment variable *MI.

E_MI_ONLY_CR: Modem opened. Hayes response received during *MI

initialization was <CR>.

E_MI_TIMEOUT: Allotted time in which to receive Hayes response expired

while obtaining *MI status.

E_MI_STATUS: Modem opened. Hayes error response as result of

generating invalid Hayes command from *MI environment variable in
CONFIG.SYS.

278 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _c le ar()

E_X_HR_TIMEOUT: Allotted time in which to receive Hayes response

expired while obtaining *MI status in Vx680 terminal.

E_X_MI_TIMEOUT: Allotted time in which to receive Hayes response

expired while obtaining *MI status in Vx520 terminal.

Example The linked example code file demonstrates use of xmdm_clear().

VERIX EVO ACT PROGRAMMERS GUIDE 279

F UNCTION C A L L S
xm dm _c lo se ()

xmdm_close()

First obtains modem status, then, closes the modem device based on input
parameters and modem communication status. xmdm_close() acts as a safe
close so that, for example, if output is currently pending, the modem is not closed.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_cl ose( i nt h_modem, i nt out put _pend, i nt i nput _pend) ;

Parameters
h_ modem Opened modem device handle.
out put _pend Non-zero value causes the function to test for pending output. If output
exists, the function does not close the modem, and an error code
returns.
i nput _pend Non-zero value causes the function to test for pending input. If input
exists, the function does not close the modem and an error code
returns.

Return Values
Success: SUCCESS: Successful close.

Failure: OUTPUT_PENDING: Modem not closed; modem output pending and

output_pend, is non-zero. Allow time for this condition to clear or call
xmdm_flush().

INPUT_PENDING: Modem not closed; input pending at modem, and

input_pend is non-zero.

OUTPUT_FAILED: Modem not closed; failed output records exist and

output_pend is non-zero.

FAILURE: close() function failed.

E_STATUS_CMD: Error obtaining initial modem status.

E_M_FLUSH: Flushing output buffer failed.

Example The linked example code file demonstrates use of xmdm_close().

280 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _d ia l_ stat us ()

xmdm_dial_status()

Obtains the results from a Hayes dial command.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_di al _st atus( i nt h_modem, i nt h_cl ock, i nt max_wai t ) ;

Parameters
h_ modem Opened modem device handle.
h_cl ock Clock device handle.
max_ wai t Maximum amount time, in seconds, to wait for a response.
If max_ wai t is zero, xmdm_di al _s t at us( ) does not time out. The
default wait-for-carrier detect after dialing for Verix eVo modems is 30
seconds. This 30 second wait can be changed through the S7 modem
register or by setting the *S7 environment variable in CONFIG.SYS.
The *S7= 55 entry causes the modem device to wait up to 55 seconds for
answer and carrier detect.

Retur n Values
Failure: E_HR_TIMEOUT: Hayes response not obtained before max_ wai t elapsed.

E_READ_CMD: Error accessing modem status.

E_ONLY_CR: Hayes response = <CR> only. Any other response received

(such as, “OK”) causes xmdm_dial_status() to return a value of
E_INVALID_RESP.

E_INVALID_RESP: Hayes response does not pertain to a dial command;

response is invalid.

Value Description
CONNECT_ 300 Dial and connect successful; 300 baud.
NO_CARRI ER No carrier detected.
HAYES_ERROR Hayes error occurred in the dial command.
CONNECT_ 1200 Dial and connect successful; 1200 baud.
NO_DI ALTONE Indicates no dialtone present. This status exists only if dialtone is
enabled with the S60= 0 command (the default setting).
BUSY_ DETECT Indicates line is busy. This status exists only if busy detection is
enabled. The X4 command (default) enables both dialtone and busy
detect.
NO_ANSWER Hayes silence; phone not answered.
VFI _NO_LI NE VeriFone unique; phone line does not exist.
VFI _DI ALDONE VeriFones dial done; dialing complete.

Example The linked example code file demonstrates use of xmdm_dial_status().

VERIX EVO ACT PROGRAMMERS GUIDE 281

F UNCTION C A L L S
xm dm _f ai le d_ ou tput _p en di ng ()

xmdm_failed_output_pending()

Determines if there are any failed output messages pending.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_f ai l ed_out put _pendi ng( i nt h_modem) ;

Parameters
h_ modem Opened modem device handle.

Return Values
Success: SUCCESS: No failed output pending.

Failure: FAILURE: Status access failure.

1: At least one failed output message pending.

Example The linked example code file demonstrates use of

xmdm_failed_output_pending().

xmdm_flush()

Clears the modem data read receive buffer.

NOTE This function can be useful just before closing the modem. Also see
xmdm_cl ose( ) and xmdm_s et _at t r i b( ) , which both attempt to flush the
output buffer.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_f l ush( i nt h_modem) ;

Parameters
h_ modem Opened modem device handle.

Return Values
Success: SUCCESS: Modem buffer and reject queue flushed.

Failure: E_READ: Error clearing modem input buffer.

Example The linked example code file demonstrates use of xmdm_flush().

282 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _g et _l in e_ di al ()

xmdm_get_line_dial()

Checks for the presence of a phone line. If the line is available,

xmdm_get_line_dial() begins dialing the number set in di al _ st r i ng. This
causes the modem to dial, and begin waiting for the carrier. If the carrier is
detected, the modem connects and goes online. max_ wai t determines how
many seconds to wait for the dial response.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_get _l i ne_di al ( i nt h_modem, char *di al _st r i ng, i nt * i wr i t e,
i nt h_ c l oc k, i nt max_ wai t ) ;

Parameters
h_ modem Opened modem device handle.
di al _ st r i ng Phone number to dial.
i wr i t e write() return value.
h_cl ock Clock device handle.
max_ wai t Maximum amount time, in seconds, to wait for a response.

NOTE di al _ st r i ng must be a null-terminated string containing valid dialing

information (see Table 18), and must be large enough to accommodate the four
extra command characters used by this function. The longest Hayes command
that can be sent is 40 bytes.

When xmdm_get_line_dial() returns, i wr i t e contains the number of bytes

written to the modem command buffer, and di al _ st r i ng contains the complete
dial command string whose string length should be equal to iwrite for a successful
dial.
If max_ wai t is set to zero, this function does not time out, but returns when the
first Hayes response is received.

Retur n Values
Failure: E_INVALID_RESP: Obtained invalid dial status response such as “OK”.

E_WRITE_CMD: Command to request line status failed.

E_READ_CMD: Command to access line status failed.

E_HR_TIMEOUT: Could not obtain line status response in time specified in

max_ wai t .
E_ONLY_CR: Hayes response = <CR> only.

VERIX EVO ACT PROGRAMMERS GUIDE 283

F UNCTION C A L L S
xm dm _g et _lin e_ di al ()

Value Description
CONNECT_300 Connection made; 300 baud.
CONNECT_1200 Connection made; 1200 baud.
NO_CARRIER Connection not established.
HAYES_ERROR Modem error occurred.
NO_DIALTONE No dial tone present on the phone line.
BUSY_DETECT Called number was busy.
NO_ANSWER Called number did not answer.
VFI_NO_LINE VeriFone-defined; no phone line status.
VFI_DIALDONE VeriFone-defined; dialing completed status.

CAUTION If auto-answer is enabled and a call comes in just before dialing out,
xmdm_get _l i ne_di al ( ) does not consider this a valid Hayes response to
dialing, and returns the value E_INVALID_RESP. This can be unpredictable.
Setting auto-answer to off (ATS0= 0) just before dialing prevents this condition.

Tabl e 18 Di al Co mm an d St ri ng Mo di fi er s
Hex ASCII
Command Descriptio n
Code Code
30h–39h ’0’–’9’ Digits pulse/tone dialed.
41h–44h ’A’–’D’ Digits pulse/tone dialed.
23h, 2Ah ’#’, ’*’ Digits tone dial only.
50h ’P’ Switch to pulse dial.
54h ’T’ Switch to tone dial.
56h ’V’ Verify answer tone (Bell 103/ Bell 212).
57h ’W’ Wait for dial tone or (S7) seconds.
2Ch ’,’ Comma; wait for (S8) seconds.
3Bh ’;’ Semicolon; eliminate the handshake.
20h ’’ Space/blank is ignored.
2Dh ’-’ Dash/hyphen is ignored.
Any other characters or unimplemented digits cause a return code of 4 (ERROR).

Example The linked example code file demonstrates use of xmdm_get_line_dial().

284 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _h an gu p()

xmdm_hangup()

Instructs the modem unit to go on-hook (disconnect) from the phone line.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_hangup( i nt h_modem, i nt h_cl ock, i nt max_wai t ) ;

Parameters
h_ modem Opened modem device handle.
h_cl ock Clock device handle.
max_ wai t Parameter is not used in the library, but is retained for backward
compatibility.

Retur n Values
Success: SUCCESS: Successful execution.

Failure: E_READ: Error reading modem buffer; read() returned -1.

E_WRITE_BLK: Failure to write modem parameters in Vx520 terminal.

E_USBMDM_SETSRLFAILED : Failure to write modem parameters in

Vx680 terminal.

NOTE Calling xmdm_hangup( ) to a modem that is currently on-hook has no effect. The
hangup function always terminates the connection, regardless of who originated
the call. (Closing the modem also guarantees a disconnect.)

Example The linked example code file demonstrates use of xmdm_hangup().

VERIX EVO ACT PROGRAMMERS GUIDE 285

F UNCTION C A L L S
xm dm_i ni t( )

xmdm_init()

Initializes the modem by opening the device and setting the communications
parameters to the specified protocol. If the modem device is already open, it is
closed and then re-opened. If the modem is not open, the h_ modemparameter
must be set to zero. This function is equivalent to calling xmdm_clear() and
xmdm_set_protocol().

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_i ni t ( i nt h_modem, char *s z_ mdm_name, i nt h_cl ock, i nt max_wai t ,
i nt r a t e, i nt f or mat ) ;

Parameters
h_ modem Opened modem device handle.
sz_mdm_name Path to modem device.
h_cl ock Clock device handle.
max_ wai t Maximum amount time, in seconds, to wait for a response.
rate Rate of connection.
f or mat Connection format.

Return Values
Success: > 0: Successful initialization; modem device handle is returned.

Failure: E_OPEN: Failure to open modem with open().

E_CLOSE: Failure to close modem with close(); modem handle on input

was non-zero, but did not reference an opened device.

FAILURE: Error writing modem protocol parameters.

Table 19 Firmware Errors

Value Description
E_ FW_READ_CMD Modem opened; Unsuccessful read() while trying to access firmware
status.
E_ FW_TI MEOUT Allotted time to receive the Hayes response expired while obtaining
firmware status. This function does not time out if max_ wai t is set
to zero.
E_ FW_STATUS Modem opened; Hayes error response as result of firmware
initialization.
E_ FW_ONLY_ CR Modem opened; Hayes response received during firmware open
was a single <CR>.

286 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _i ni t()

Table 20 CONFIG.SYS *MI Initialization Errors

Value Description
E_MI _READ_CMD Modem opened; Unsuccessful read() = -1 while trying to access *MI
entry. This is received when *MI contains a bad Hayes command.
E_MI _TI MEOUT Allotted time to receive the Hayes response expired while obtaining
*MI status.
E_MI _STATUS Modem opened; Hayes error response as result of generating invalid
Hayes command from *MI command in CONFIG.SYS.
E_MI _ONLY_ CR Modem opened; Hayes response received during *MI initialization is
only a single <CR>.

Example The linked example code file demonstrates use of xmdm_init().

VERIX EVO ACT PROGRAMMERS GUIDE 287

F UNCTION C A L L S
xm dm _i np ut _p en di ng ()

xmdm_input_pending()

Determines if there are any input messages pending.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_i nput _pendi ng( i nt h_modem) ;

Parameters
h_ modem Modem handle.

Return Values
Success: SUCCESS: No input pending.

Failure: 1: At least one input message pending.

FAILURE: Status access failure.

Example The linked example code file demonstrates use of xmdm_input_pending().

288 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _o pen( )

xmdm_open()

Opens the modem device specified in pat h and obtains the resulting modem
responses.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_open( i nt *h_modem, char * pat h, i nt h_cl ock, i nt max_wai t , i nt
r at e, i nt f or mat ) ;

Parameters
h_ modem Pointer to the modem handle.
pat h Pointer to the modem path string.
h_cl ock Clock device handle.
max_ wai t Maximum amount time, in seconds, to wait for a response.
rate Rate of connection.
f or mat Connection format.

Retur n Values
Value Description
HAYES_OK Successful execution.
E_OPEN open() command unsuccessful.
E_ FW_READ_CMD Firmware error; initial read() failed.
E_ FW_TI MEOUT Firmware error; too long to execute.
E_ FW_STATUS Firmware error; Hayes response status.
E_ FW_ONLY_ CR Firmware error; modem opened; Hayes response received during
firmware open was single carriage return character, <CR>.
E_WRI TE_BLK Failure to write port setup with MDM_WRITE_BLK().

Tab le 21 CONFIG.SYS *MI En tr y Er ro rs

Value Description
E_MI _READ_CMD read() failed.
E_MI _TI MEOUT Modem busy; too long to execute. This function should not timeout.
If it does, set max_ wai t to zero so it cannot timeout.
E_MI _STATUS Hayes response status is ERROR.
E_MI _ONLY_ CR Modem opened. Hayes response received during *MI initialization
was a single carriage return character.

NOTE The modem device remains inactive until a call is made to initialize the
parameters such as baud rate, format, and so on. See the
xmdm_set _pr ot ocol ( ) function. If pat h is null or empty, then the device
MDM_PORT is opened.

VERIX EVO ACT PROGRAMMERS GUIDE 289

F UNCTION C A L L S
xm dm _o pe n( )

NOTE It is highly recommended to flush the port after xmdm_open using

xmdm_f l ush( ) . *MI CONFI G. SYS environment variable is used to specify the
modem init string in the Verix eVo terminal. It is used while opening the modem.
Since E0V0Q0 is added by the library, the user is not required to provide this as
part of *MI variable.

Example The linked example code file demonstrates use of xmdm_open().

290 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _o ut pu t_ pe nd in g()

xmdm_output_pending()

Determines if there are any output messages pending.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_out put _pendi ng( i nt h_modem) ;

Parameters
h_ modem Opened modem device handle.

Retur n Values
Success: SUCCESS: No output pending.

Failure: FAILURE: Status access failure.

1: At least one output message pending.

Example The linked example code file demonstrates use of xmdm_output_pending().

VERIX EVO ACT PROGRAMMERS GUIDE 291

F UNCTION C A L L S
xm dm _re ce iv e_ da ta()

xmdm_receive_data()

Waits until a specified incoming data, with maximum positive number of bytes
from the modem port or a pause in reception, or a timeout expires on a first come
first basis. If there are more data pending than specified, it will be ignored.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_r ecei ve_dat a( i nt h_modem, char * buf f er , i nt mi n, i nt max,
i nt max_ wai t ) ;

Parameters
h_ modem Handle to the modem comport.
buf f er Pointer to receive buffer.
mi n Not used in the library. Maintained for backward compatibility.
max Maximum number of characters to receive. Must be greater than zero.
max_ wai t Maximum receive time in 10-ms increments.

Return Values
Success: > 0: Number of bytes read

Failure: E_INVALID_PARM: Invalid parameter passed.

E_READ: Error reading input data, read() = -1.

E_X_HR_TIMEOUT: Time out reached before 'max' number of bytes read.

E_X_NO_CARRIER: Carrier lost while receiving data.

Example The linked example code file demonstrates use of xmdm_receive_data().

292 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _sen d_da ta ()

xmdm_send_data()

Provides a timed transmission of data in buf f er to the modem device.

The maximum transfer length allowed by this function is 32767 bytes. In packet
mode, transfers should be limited to 254 bytes. The number of bytes actually
transmitted depends on available modem buffer space.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_send_dat a( i nt h_modem, char *buf f er , i nt buf f _l en, i nt max_wai t ) ;

Parameters
h_ modem Opened modem device handle.
buf f er Data to send to modem.
buf f _ l en Buffer length.
max_ wai t Maximum transmit time in 10-ms increments.

NOTE If max_ wai t is zero (0), the routine makes a single attempt to transfer data to the
modem. If the execution of the data transfer fails, xmdm_send_data() returns
FAILURE.

Retur n Values
Success: > 0: Contains the number of bytes transferred. This value should equal
buf f _ l en on successful transfer. Since the output is buffered by the
modem device and sent at a controlled rate, the output is pending at the
time this function returns. To determine if all buffered output was sent, call
xmdm_checkline() until a value of zero returns.
Failure: FAILURE: Error writing to modem port.
E_NOCARR IER: Carrier lost while trying to send data.
E_PARTIAL: Sent only part of buffer. Check errno for the number of bytes
sent.
E_STATUS_CMD: Unable to obtain modem status when sending buffers
larger than 200 bytes.

If only part of the buffer is transmitted,

E_PARTIAL is returned, with the number of bytes sent in errno.
If max_ wai t is a non-zero value, xmdm_send_data() times the transmission, and
returns with a time out error if the buffer could not be transmitted in the specified
amount of time. In a time-out condition, the actual number of bytes sent returned
in errno.

Example The linked example code file demonstrates use of xmdm_send_data().

VERIX EVO ACT PROGRAMMERS GUIDE 293

F UNCTION C A L L S
xm dm _set _a ttri b()

xmdm_set_attrib()

Changes a single modem attribute without affecting previously established

modem attributes. This function is for on-the-fly changes when the modem has
already been initialized. xmdm_set_attrib() was written with the character, packet,
and SDLC standard protocols in mind.
Specific #def i nes can be declared to make this function useful with custom
protocols.
attrib identifies which modem attribute to change. value designates the value to
assign to this attribute.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_set _at t r i b( i nt h_modem, i nt r at e, i nt f or mat , i nt f l ush) ;

Parameters
h_ modem Opened modem device handle.

rate Rate of connection.

f or mat Connection format.
f l ush Flush buffers control flag. Once the modem attribute is reset, you can clear
the Hayes and modem data. If this is the case, set flush to 1; otherwise, set
flush to 0. Valid values are as follows:
• 1 = Flush buffer.
• 0 = Buffer not flushed.

Return Values
Success: SUCCESS: Successful update of attribute.

Failure: FAILURE: Invalid attribute, attrib.

E_WRITE_BLK: Unable to update system modem attributes.

E_READ: Unable to flush modem data buffer.

NOTE
Each attribute has a corresponding identification number. Attributes can be
specific to a particular protocol. These values are from XMODEM.H.

Example The linked example code file demonstrates use of xmdm_set_attrib().

294 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
xm dm _set _p rot oc ol()

xmdm_set_protocol()

Initializes the communication data protocol attributes of the currently opened

modem.

NOTE The library supports a structure definition for each type of protocol. The
programmer should load the appropriate structure with the intended attributes for
the desired protocol. xmdm_s et _pr ot ocol ( ) initializes the modem with this
information.

Prototype #i ncl ude <XMODEM. H>

i nt xmdm_set _prot ocol ( i nt h_modem, i nt r ate, i nt f ormat) ;

Parameters
h_ modem Modem device handle.
rate Rate of connection.
f or mat Connection format. Any parameter that is passed to the f or mat variable,
Fmt _AFC and Fmt _ DTR gets appended which is a default setting for open
block format.

Retur n Values

Success: SUCCESS: Normal function completion.

Failure: FAILURE: Unable to write in the modem initialization block. A negative

number is returned for the following data communication baud rates:
• 2400: -3 error value is returned.
• 4800: -4 error value is returned.
• 38.4 K: -7 error value is returned.

Example The linked example code file demonstrates use of xmdm_set_protocol().

VERIX EVO ACT PROGRAMMERS GUIDE 295

F UNCTION C A L L S
Re po rt Form at te r Func tion Call s

Report This section describes the following report formatter function calls:
Formatter
• formater_close() • formater_open()
Function Calls
• formater_line() • formater_template()

• formater_main() • formater_set_flags()

Report Formatter Sample Input Text Fil e

Examples

Example Generates the . FRMfile using the FORMCVT tool. A sample text file for
generating the . FRMfile as follows.
1: 1, "I TP Test Repor t "
3: 1. 30, " \ C\ DVALUECARD"
4: 1. 40, \ C\ D" SPOT \ W\ HREPORT\ B"
6: 1, " \ NTERM I D"; 14, "DATE" ; 24, " TI ME" ; 32, " BONUS" ; 38, " ART"
7: 1. 10, \ L\ Dt erm_i d; 14. 21, date; 24. 28, v_t i me; 32. 32, bonus; 34, "WORK\ B"
9: 1, " TOTAL" ; 19, " TOTAL"
10: 3, "I NT = $"; 10. 16, i nt _t t l ; 21, "CUM = $"; 28. 34, cum_t t l
12: 1, "BI LL"; 19, "BI LL"
13: 3, "I NT = $"; 10. 16, i nt _bi l ; 21, "CUM = $"; 28. 34, cum_bi l
15: 1, " CREDI T CARD" ; 19, " CREDI T CARD"
16: 3, "I NT = $"; 10. 20, i nt _cr d; 21, "CUM = $"; 28. 34, cum_cr d
20: 1, "SUBJ ECT TO"; 19, "S____ ____ ___ ____ ___ _"
21: 1, " \ D\ W\ HLATER AUDI T\ B" ;
22: 10. 30, \ Ni nt _crd
23: 1, "\ N\ Dt est val ue: "; 25. 28, t est ; 30. 39, \ Cname
25: 1. 12, \ L\ Dt er m_i d; 13. 26, \ Bt er m_i d; 27. 40, \ Ct er m_i d
27: 1. 12, \ Lt er m_i d; 13. 18, \ Lt er m_i d; 27. 40, \ Rt er m_i d
29: 1. 12, \ L i nt _ t t l ; 13. 26, i nt _ t t l ; 27. 40, \ Cv_ t i me
31: 3. 23, "st r i ng const ant "; 24, "t est "; 30. 39, "on l ef t "
33: 2. 14, \ D\ Wt est ; 16. 20, \ B\ Ht est
35: 2. 14, \ N\ Ct est ; 16. 23, \ Ltest; 30. 39, t est
37: 2. 14, \ Cbonus; 16. 23, \ Lbonus; 30. 39, bonus
39&x80000000: 1, " Condi t i on l i ne x80000000"
39&x40000002: 1, " Condi t i on l i ne x40000002"
39&x1: 1, " Condi t i on l i ne x00000001"
41: 1, " That ' s al l f ol ks . . . "

296 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
form ater _c lo se()

formater_close()

Closes the template file and returns to the caller.

Prototype voi d f or mat er _cl ose ( FORMATER *f or mdat a) ;

Parameters
f or mdat a Pointer to a FORMATER structure.

Retur n Values None

Dependencies Verix eVo SDK

VERIX EVO ACT PROGRAMMERS GUIDE 297

F UNCTION C A L L S
fo rm at er_l in e()

formater_line()

Formats a range of report lines. Formatting of conditional lines is based on the

condi t i on parameter. The formatted data is buffered into 200-byte buffers and
passed to the output print function (assigned in the initialized output function).

NOTE The following special printing modes are not handled by this function. They are
processed by the output driver.
• Print red
• Restore print color to black
• Print double width
• Print double height
• Restore to normal print mode
• Send initialization command to printer

If a string constant or variable has a length longer than the column range specified
in the template file, it is truncated to fit the specified range. The default for
formatting a string constant is left justification; the default for formatting a variable
is right justification.
When formatting a range of line numbers, problems may occur with system buffer
usage. In this case, f or mat er _l i ne( ) returns -1 and stores the next line
number to format in er r or _ l i ne. Using the contents of er r or _ l i ne, these
types of errors can be processed.

Prototype i nt f or mat er _l i ne( FORMATER *f or mdat a, i nt st ar t _l i ne, i nt st op_l i ne,

i nt pr i nt _ bl ank_ l i nes , uns i gned l ong c ondi t i on,
i nt *er r or _l i ne) ;

Parameters
f or mdat a Pointer to a FORMATER structure.
s t ar t _ l i ne Starting line number. If the line is not defined in the template
and pr i nt _ bl ank_ l i nes is non-zero, blank lines print until
the line number in the template is reached.
s t op_ l i ne Last line number to print. If this value is TO_ END (-1), the
template is processed through to the last line.
pr i nt _ bl ank_ l i nes If zero, print undefined lines as blank lines; otherwise, ignore
undefined lines.
c ondi t i on Value ANDed with the condition in each template record. If the
result is not 0, the line prints; otherwise it is ignored.

Note: Any line in the template that does not specify a

condition is always printed.
er r or _ l i ne Pointer to an i nt containing a line number being printed when
the error occurred.

298 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
form at er_m ai n()

Note: The formatter keeps print data in 200-byte buffers.

The value returned is the first line number in the
current buffer.

Retur n Values
Success: 0

Failure: -1: An error condition. er r or _ l i ne is set to indicate where to resume, and
errno may have been set by out put _pr i nt ( ) .

Example whi l e (f or mat er _l i ne (f or mat dat a, st ar t _l i ne, TO_END, pr i nt _bl ank_l i nes,
condi t i on, er r or _l i ne) ! = 0)
s t ar t _ l i ne = * er r or _ l i ne;

Dependencies Verix eVo SDK

formater_main()

Accepts a handle of g_dat a to be used by the application for formatting.

NOTE
Call f or mat er _mai n( ) before using any other function.

Prototype voi d f or mat er_ mai n( g_dat a *gvar dat a) ;

Parameters
g_dat a gvar dat a Structure holding application-specific information required by the
formatter.

VERIX EVO ACT PROGRAMMERS GUIDE 299

F UNCTION C A L L S
fo rm ater _o pe n()

formater_open()

Accepts the handle of an open output device, a FORMATER structure address

that holds information about the current formatter job, the name of the report
template file, a pointer to the output initialization function, and a time-out value
that initializes the output device. It also opens the template file, then calls the
output initialization function. The result is returned to the application.

NOTE
The output initialization function fills in the FORMATER structure with pointers to
the output drivers print and close functions.

If the output device is a direct interface to a communications port, the maximum

number of slots is retrieved and saved so that it can control the maximum number
of buffers used during output. Examples of indirect interfaces are spoolers and
display drivers.

Prototype i nt f or mat er _open( i nt handl e, FORMATER f ormdat a, char t empl at e, i nt

( * out put _ i ni t i al i z er ) ( ) , i nt t i me_ out ) ;

Parameters
handl e Handle of an open communications device.
f or mdat a Pointer to a FORMATER structure which is filled in by the
f or mat er _open( ) function and used when calling other
formatter functions.
t empl at e Name of the template file.
* out put _ i ni t i al i z er Pointer to a function that initializes the output driver, (for
example, p150di r ).
t i me_out Time-out value used when initializing an output device. The
initialized output can elect to ignore this parameter.

Return Values
Success: 0
Failure: -1: Template file cannot be opened.

The formater_open() function checks the return value from the user-written

function passed in * out put _ i ni t i al i z er .
Any value less than zero is considered an error. This function stops execution and
returns this error value to its calling routine.
The user-defined function should not return a value of -1, as the user function
cannot tell whether a general function error has occurred or if the function is
returning a "Template file cannot be opened" error.

Dependencies Verix eVo SDK

300 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
form ater _set _fla gs()

formater_set_flags()

Builds the condition flag from user application-specific variables. It sets a 32-bit
unsigned long bitmap flag to be used by the formatter to format any conditional
lines of the report template.

NOTE
-1 always terminates the parameter list.

Prototype uns i gned l ong f or mat er _ s et _ f l ags ( i nt va_ al i s t , . . . ) ;

Parameters
va_ al i s t Either 0 or non-zero; maximum of 32 (values > 32 shifts bits off the end).

Retur n Values Unsigned long representation of the bit pattern.

NOTE • The first value passed as the parameter to the function will be ignored, for example:
1,0,1,0,1,0 will be treated as 0,1,0,1,0.
• All bits are right justified in the return value by position.

Example The linked example code file demonstrates use of formater_set_flags().

Dependencies Verix eVo SDK

formater_template()

Specifies which template file to use.

Prototype i nt f or mat er _t empl at e( FORMATER f or mdat a, char t empl at e) ;

Parameters
f or mdat a Pointer to a FORMATER structure.
t empl at e Name of the template file.

Retur n Values
Success: 0

Failure: -1: Template file cannot be opened.

Dependencies Verix eVo SDK

VERIX EVO ACT PROGRAMMERS GUIDE 301

F UNCTION C A L L S
Da ta ba se Li brary Fu nc ti on Ca lls

Database This section provides descriptions of the following database library function calls:
Library
• db_close() • db_remove()
Function Calls
• db_delete() • db_seek_key()

• db_get_key() • db_seek_record()

• db_open() • db_write()

• db_read()

Database Library The following linked files illustrate the use of the function calls provided by the
Examples Database library, with examples.

TBatch Key Functio n

In the TBatch Key Function example, a batch implementation for a typical

application is included. The structure TBat chRec is the definition of the batch
record and TBat chKey is the definition of the key structure to access the batch
records.

Example The linked example code file demonstrates use of TBatchKey().

db_close()

Closes the database and index files.

Prototype #i ncl ude <dbmgr . h>

shor t db_cl ose( DB_FI LE *db_pt r ) ;

Parameters
db_pt r Pointer to the database file structure.

Return Values
Success: Positive: Successful operation.

Failure: DB_INVALID_PARAM: db_pt r is NULL.

-1 : System error. errno contains the specific error code.

302 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
db_delete()

db_delete()

Deletes one or more records from the database and index files.

NOTE
The delete operation slows the application down, so the offsets can be updated.

If the start record plus the number of records to delete is greater than the actual
number of records in the file, all records in the file starting from the specified
record number are deleted. There is no error message. The argument r ec_cnt
includes the start record number (r ec_num). If r ec_num= 1 and r ec_cnt = 0,
no record is deleted and 0 is returned.

Prototype #i ncl ude <dbmgr . h>

short db_del ete( DB_FI LE *db_ptr , l ong r ec_num, l ong r ec_cnt ) ;

Parameters
db_pt r Pointer to database file structure.
r ec_num The record number to start deleting from.

r ec_cnt The number of consecutive records to delete.

Retur n Values
Success: Positive ( Successful operation. The number returned indicates the
number of records deleted.

Failure: DB_INVALID_PARAM: db_pt r is NULL.

Negative: One of the following errors:

• System error. errno contains the specific error code.
• DB_INVALID_REC_NUM: Starting record is out of range.
• DB_INVALID_REC_CNT: Record count invalid; negative not allowed.

VERIX EVO ACT PROGRAMMERS GUIDE 303

F UNCTION C A L L S
db_get_key()

db_get_key()

Finds the specified key value.

Prototype #i ncl ude <dbmgr . h>

l ong db_get_ key( DB_FI LE *db_pt r , voi d *key_st r uct , voi d *Matchst r ,
l ong acti on, char *dat abuf , i nt dl en, l ong *r ec_num) ;

Parameters
db_pt r Pointer to the database file structure.
key_st r uct The buffer to contain the key structure.
Mat chst r See Match Structure.
ac t i on Find criteria. Valid values are:
• DB_FIRST: Start from the beginning of file and search forward to find
the first key match.
• DB_LAST: Start from the end of file and search backward to find the
first key match.
• DB_PREVIOUS: Find the previous key from the present position.
• DB_NEXT: Find the next key from the present position.
• n: nth occurrence of the key relative to the current position. If n > 0,
then search forward.
dat abuf Pointer to the data buffer.
dl en Length of the data record.
r ec_num Address of the r ec_numthat is updated when a successful comparison
occurs.

Match Struct ure

This structure must be created by the programmer. The first element in this
structure must be a pointer to a compare function written by the programmer. The
other elements of the key structure are values to compare against. This
comparison function must return 0 if a match occurs. When db_seek_key() calls
the comparison function, it passes the address of the key_st r uct buffer (this
buffer contains the key structure read by the Database library) and the Match
structure.
db_get_key() calls db_seek_key() internally to obtain the record number of the
specified database record and reads the record into the data buffer for
subsequent processing.

304 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
db_get_key()

NOTE If the function returns a value greater than 0, then the r ec_numand key_st r uct
are updated. If you search for the 5th occurrence but only 1 key exists, then
r ec_numand key_st r uct are updated anyway. In this case, db_seek_key( )
returns 1 and not 5.
The prototype of the compare function is:
s hor t ( * comp_ f unc) ( voi d * , voi d * ) ;

where, the first argument is the key structure and the second argument is the
Match structure.

Retur n Values
Success: 1: The requested number of occurrences were found. (r ec_numand
key_st r are updated).
Failure: 0: No key was found or the requested number of occurrences were not
found.

DB_INVALID_PARAM: db_pt r is NULL.

DB_INVALID_BUF_SIZE: The length of the buffer size ( dl en) is zero.

DB_INVALID_RANGE: dl en is not between DB_MAX_ I NT and

DB_ MI N_I NT (defined in dbmgr.h).
-1: System error. errno contains the specific error code.

NOTE The compare function that compares the specified search key to the
corresponding key in the index file record must be provided by the programmer. If
this function is not provided, db_s eek_key( ) and db_get _key( ) fail.

Example The linked example code file demonstrates use of db_get_key().

VERIX EVO ACT PROGRAMMERS GUIDE 305

F UNCTION C A L L S
db_open()

db_open()

Creates a database file and the corresponding index file and updates the
database file structure. If a database file is already created, db_open() opens the
existing file.

NOTE • Do not provide a filename extension. This function does not check for a
filename extension. The filename should not be more than
DB_MAX_FI LENAME_SI ZE (= 26) characters.
• In flash, db_open( ) API allows only one file to open in the O_RDWR mode.
• Refer to the Verix eVo OS Programmers Manual for more details about the
restrictions on the usage of flash file.

Prototype #i ncl ude <dbmgr . h>

shor t db_open( DB_FI LE *db_ptr , char * f i l ename, i nt key_l en, i nt mode);

Parameters
db_pt r Pointer to database file structure.
f i l ename The filename with no extension.
key_l en The length of key structure in bytes.
mode The file creation mode as described in fnctl.h (the standard C/C++ library
include file). Valid values are:
• O_RDWR
• O_EXCL
• O_TRUNC
• O_CREAT

NOTE • When creating a new file, use the O_CREAT | O_ RDWR mode.

• O_RDONLY, O_WRONLY and O_APPEND are not supported.

Return Values
Success: Positive: Handle to the index file.

Failure: DB_INVALID_PARAM: db_pt r is NULL.

DB_INV ALID_RANGE: key_l en or mode is not between DB_MAX_I NT

and DB_MI N_I NT (defined in dbmgr.h).

D B_INVALID_REC_NUM: key_l en is negative.

DB_INVALID_BUF_SIZE: key_l en is 0.

DB_INVALID_FILENAME: Length of the filename is greater than

DB_MAX_FI LENAME_SI ZE (defined in dbmgr.h).
DB_INVALID_FILE_MODE: Invalid file mode.

Negative: System error. errno contains the specific error code.

306 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
db_read()

NOTE
If the file name is given with an extension, the API adds . dat extension along
with the file name given. For example, t es t . t xt is created as t es t . t xt . dat .

db_read()

Retrieves a specified record from the database file.

Prototype #i ncl ude <dbmgr . h>

shor t db_r ead( DB_FI LE *db_pt r , voi d *key_str uct , char *dat a_buf , i nt dl en,
l ong r ec_num) ;

Parameters
db_pt r Pointer to the database file structure.
key_st r uct Pointer to the key structure.
dat a_buf Pointer to the data buffer.
dl en Length of the data buffer.
r ec_num Use the following parameters:
• n: Record number to be read.
• DB_CURRENT: Reads current record; does not move file pointer.
• DB_FORWARD: Reads current record and moves file pointer to the next
record.
• DB_BACKWARD: Reads previous record and leaves file pointer in front
of the record that was read.

Note: db_r ead( ) also takes r ec_numas a zero-based index.

Retur n Values
Positive: Positive: Number of bytes read.

Failure: DB_INVALID_HANDLE: File handle not greater than zero.

DB_INVALID_REC_NUM: r ec_numis negative or greater than the

number of records in the database.

DB_INVALID_PARM: db_pt r is NULL.

DB_INVALID_RANGE: dl en is greater than DB_MAX_I NT.

DB_INVALID_BUF_SIZE: dl en is equal to 0.

Negative: System error. errno contains the specific error code.

VERIX EVO ACT PROGRAMMERS GUIDE 307

F UNCTION C A L L S
db_remove()

db_remove()

Deletes the database file and corresponding index files.

NOTE Do not provide a filename extension. This function does not check for a filename
extension. The filename should not be more than DB_MAX_ FI LENAME_SI ZE (= 26)
characters.

Prototype #i ncl ude <dbmgr . h>

shor t db_r emove( char *f i l ename) ;

Parameters
f i l ename Name of the file to remove.

Return Values
Success: 0: File successfully removed.

Failure: DB_INVALID_FILENAME: Length of the filename is greater than

DB_MAX_ FI LENAME_SI ZE (defined in dbmgr.h).
Negative: System error. errno contains the specific error code.

308 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
db_seek_key()

db_seek_key()

Searches the index file records for the specified key value. The key value can be
an element of a structure or a text string.

Prototype #i ncl ude <dbmgr . h>

l ong db_seek_key( DB_FI LE *db_ptr , voi d *key_st r uct , voi d *Matchst r ,
l ong act i on, l ong *r ec_num) ;

Parameters
db_pt r Pointer to the database file structure.
key_st r uct Pointer to the key structure.
Mat chst r This structure must be created by the programmer. The first element in
this structure must be a pointer to a compare function written by the
programmer. See db_get_key() for details.
ac t i on Find criteria, as follows:
• DB_FI RST: Start from the beginning of file and search forward to find
the first key match.
• DB_LAST: Start from the end of file and search backward to find the
first key match.
• DB_PREVI OUS: Find the previous key from the present position.
• DB_NEXT: Find the next key from the present position.
• n: nth occurrence of the key relative to the current position.
If n>0, search forward.
r ec_num Address of the record number that updates when the key is found.

Retur n Values
Success: Positive (>0): The key was found specified number of times. r ec_num
is updated with the last record number found.

Failure: 0: No key was found.

DB_INVALID_REC_NUM: r ec_numis negative or greater than the

number of records in the database.

Negative: System error. errno contains the specific error code.

NOTE If the function returns a value greater than 0 (zero), then r ec_numand
key_st r uct are updated. Searching for a 5th occurrence of a key when there is
only one occurrence still updates r ec_numand key_st r uct . In this case,
db_seek_key( ) returns 1 and not 5.
db_r ead( ) must be called to get the entire key and data structure.
The first element of the Match structure must be initialized to the compare
function. The prototype of the compare function is:
shor t ( *comp_f unc) ( voi d *, voi d *)
where, the first argument is the key structure and the second argument is the
Match structure.

Example The linked example code file demonstrates use of db_seek_key().

VERIX EVO ACT PROGRAMMERS GUIDE 309

F UNCTION C A L L S
db_seek_record()

db_seek_record()

Searches for a specified record in an index file and modifies the file pointer
position accordingly.

NOTE
db_s eek_r ecor d( ) takes record number as a zero-based index.

Prototype #i ncl ude <dbmgr . h>

l ong db_seek_r ecord( DB_FI LE *db_ptr , l ong r ec_num, i nt ori gi n) ;

Parameters
db_pt r Pointer to the database file structure.
r ec_num Number of the record to seek, relative to the origin.

or i gi n Record number of the starting point. Valid values are:

• SEEK_SET: Start from the beginning of the file.
• SEEK_CUR: Start from current position of the file pointer.
• SEEK_END: Start from end of the file towards the beginning.

NOTE • While searching the records backwards, the r ec_numvariable should be specified with
a negative sign. If the negative value of r ec_num is greater than the number of records
or greater than the records from the nth position, then the db_s eek_r ecor d fails.
• While searching the records, the starting file value, SEEK_SET variable cannot have a
negative value.

Return Values
Success: Positive: Record number in the database file.

Failure: DB_INVALID_PARAM: db_pt r is NULL.

DB_INVALID_HANDLE: File handle not greater than zero.

DB_INVALID_REC_NUM: Origin is not SEEK_SET, SEEK_CUR, or

SEEK_END.
DB_SEEK_ERROR: Error in seeking the record.

Negative: System error. errno contains the specific error code. See

errno.h for error descriptions.

Example The linked example code file demonstrates use of db_seek_record().

310 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
db_write()

db_write()

Writes or updates a record in both the database and index files.

Prototype #i ncl ude <dbmgr . h>

shor t db_wr i t e( DB_FI LE *db_pt r , voi d *key_str uct , char *dat a_buf ,
unsi gned i nt dat a_l en, l ong rec_num) ;

Parameters
db_pt r Pointer to the database file structure.
key_st r uct Pointer to the key structure.
dat a_buf Pointer to the data buffer.
dat a_l en Data length.
r ec_num File entry index or pointer. Valid values are:
• DB_APPEND: Writes to end of file.
• DB_CURRENT: Writes to current file position; does not advance file
pointer.
• DB_FORWARD: Writes to current file position and advances the file
pointer.
• DB_BACKWARD: Overwrites the previous record. File pointer is placed
in front of written record.

Note: r ec_numaccepts integer values.

Retur n Values
Success: Positive: Number of bytes written.

Failure: DB_INVALID_PARAM: db_pt r is NULL.

DB_INVALID_REC_NUM: r ec_numis negative or greater than the

number of records in the database.

Ne gative: System error. errno contains the specific error code.

NOTE
If a record exists at the current file pointer position, it is overwritten.

Printing This feature enables printing of monochrome bitmaps independent of the printers
Monochrome used in Verix eVo terminals.
Bitmap

print_image()

Prints the monochrome bitmap. The bitmap is printed if the following conditions

are satisfied:
• valid monochrome bitmap type.
VERIX EVO ACT PROGRAMMERS GUIDE 311

F UNCTION C A L L S
pr int_ im ag e( )

• offset should be of the range 0-60.

• width of the bitmap should be within the printable area from the offset position.

Prototype print_image(int offset, char * filename);

parameters

of f s et 0-60.
Note: If the value is less than 0, then 0 is taken as the offset
value.
If the value is greater than 60, then 60 is taken as the
offset value.

f i l ename Valid bmp file.

Retur n Values

Success 1

Failure PRINTER_FAIL Unable to open the printer.

OPEN_FAIL Unable to open the file.

READ_FAIL Unable to read the file.

NOT_MONOCHROME Not a monochrome bitmap.

NO_DATA There is no value in the bitmap.

NO_MEMORY Dynamic memory allocation fails.

WRITE_FAIL Unable to write to printer.

312 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
Print Pak 3700 Function Calls

Prin t Pak 3700 Each of the stand-alone driver functions can be called directly by the application.
Function Calls Each function includes a parameter that specifies the opened port handle. This
handle is an identifier generated by the operating system when the port is opened.
The application is responsible for both opening the opened port to obtain the
handle and closing the opened port after print operations complete.
This section provides descriptions of the following Print Pak 3700 driver function
calls:

• p3700_close() • p3700_mode()

• p3700_dnld_char() • p3700_print()

• p3700_dnld_font_file() • p3700_print_graphic()

• p3700_dnld_graphic_file() • p3700_select_font()

• p3700_id() • p3700_sel_tbl_dnld_char()

• p3700_init() • p3700_status()

NOTE
Print Pak 3700 function calls are supported in Vx680 and Vx520 terminals.

p3700_close()

Waits for all pending data to transmit to the printer, then returns.

CAUTION
p3700_close() performs a device-level close operation.

Prototype #i ncl ude <pr i nt er. h>

i nt p3700_cl ose( shor t h_comm_por t ) ;

Parameters
h_comm_por t Handle for the opened communication port.

Retur n Values

Success: 0: No error.

Failure: -1: Printer did not respond.

VERIX EVO ACT PROGRAMMERS GUIDE 313

F UNCTION C A L L S
p3 70 0_ dn ld _c ha r()

p3700_dnld_char()

Transmits a single character to the printer. The first byte in the passed buffer must
be the character to replace, followed by either 14 bytes (8 x 14 font), 32 bytes (16
x 16 font), or any other font size supported by the printer. These bytes represent
the bitmap for the new font character.

Prototype #i ncl ude <pr i nt er. h>

shor t p3700_dnl d_char ( shor t h_comm_por t , unsi gned char *r d_buf ,
unsi gned shor t wr i t e_byt es) ;

Parameters
h_comm_por t Handle for the opened communication port.
r d_buf Buffer containing the bytes to download to the printer.
wr i t e_bytes Number of characters to download (including the char to replace). For
example, an 8 x 14 font requires 15 bytes.

Return Values

Success: > 0: Number of bytes written.

0: No error.

Failure: -11: Download failed.

314 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
p3 70 0_ dn ld_f on t_ fi le()

p3700_dnld_font_file()

Downloads a font file set to the printer. The font file is composed of an 8-byte
header record. The definition of this record is as follows:
• 1: (N) p3700 printer ID code
• 2: ESC
• 3: l (lower-case L)
• 4: font_size
• 5: font_table
• 6 & 7: number of bytes per character (for example, for a 16 x 16 font, bytes 6
and 7 are 0x00 and 0x20).
• 8: number of characters to download
Following the header record is a series of font images that compose each new
font character. The first byte in the font image is the ASCII character to replace in
the selected font table. The remaining bytes in the font image are the bytes that
form the new font character.
Prototype #i ncl ude <pr i nt er. h>
shor t p3700_dnl d_f ont _f i l e( shor t handl e, shor t h_f ont _f i l e,
s hor t f ont _ t abl e) ;

Parameters
handl e Handle for the opened communication port.
h_ f ont _ f i l e Handle for the font file.
f ont _ t abl e Font table to select.

Retur n Values
Success: > 0: Number of font characters downloaded.

Failure: 0: No characters downloaded (error).

-8: Header error occurred.

-9: File error occurred.

-11: Font download failed.

-22: Invalid printer.

NOTE • Verix eVo ACT printer library checks for the cancel key operation during the
download of graphic file and font file to the printer.
• If the DISABLECANKEYF conf i g. sys entry is set to 1, then Verix eVo ACT
library ignores the cancel key pressed during the font file download.
• If the DISABLECANKEYF conf i g. sys entry is set to 0 or any other value, or
not found, then Verix eVo ACT library checks for the cancel key press and
aborts the font file download if the cancel key is pressed.

VERIX EVO ACT PROGRAMMERS GUIDE 315

F UNCTION C A L L S
p3 70 0_ dn ld _gra ph ic _f il e()

p3700_dnld_graphic_file()

Downloads a graphic logo file to the printer. The graphic file is composed of a
16-byte header record. The definition of this record is:
• 1: “N” (printer ID code of P3700)
• 2: ESC
• 3: “G”
• 4: “M”
• 5: Image format (ASCII)
• 6: “,”
• 7: Reserved (“0”) Image ID (ASCII)
• 8: “,”
• 9, 10, 11: Image Width (ASCII) (for example, the image width is “240” for a 240
column image).
• 12: “,”
• 13,14,15: Image height (ASCII) (for example, the image height is “120” for a
120 column height image).
• 16: “;”

Prototype #i ncl ude <pr i nt er. h>

shor t p3700_dnl d_gr aphi c_f i l e( shor t h_comm_por t , shor t h_gr aphi c_f i l e) ;

Parameters
h_comm_por t Handle for the opened communication port.
h_ gr a phi c _ f i l e Handle for the graphic file.

Return Values
Success: 0: No error.

Failure: -8: Header error occurred.

-9: File error occurred.

-39: Wrong file.

NOTE • Verix eVo ACT printer library checks for the cancel key operation during the
download of graphic file and font file to the printer.
• If the DISABLECANKEYG conf i g. sys entry is set to 1, then Verix eVo ACT
library ignores the cancel key pressed during the graphic file download.
• If the DISABLECANKEYG conf i g. sys entry is set to 0 or any other value, or
not found, then Verix eVo ACT library checks for the cancel key press and
aborts the graphic file download if the cancel key is pressed.

316 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
p3 70 0_ id()

p3700_id()

Sends the <ESC>i command (request printer ID) to the ITP, and waits for a
response. If the ITP responds within the time-out period, the ID is compared to the
valid ID for an ITP.

Prototype i nt p3700_i d( short h_comm_port , short i d_t i me_out ) ;

Parameters
h_comm_por t Handle to the opened communications port.
i d_t i me_out Time-out period, in increments of approximately 500 ms.

Retur n Values
Success: 0: No errors detected.

Failure: -1: Printer did not respond.

-2: Invalid printer ID.

-22: Invalid printer type.

-23: Escape sequence not found.

-24: Printer not initialized.

VERIX EVO ACT PROGRAMMERS GUIDE 317

F UNCTION C A L L S
p3 70 0_ in it ()

p3700_init()

Sets the printer to native mode by sending the <GS><ESC>c<GS> command. If

the printer responds within the time-out period, the ID is compared to the valid ID
for an ITP (P).

Prototype #i ncl ude <pr i nt er. h>

i nt p3700_i ni t ( short h_comm_port , short t i me_out ) ;

Parameters
h_comm_por t Handle for the opened communication port.
t i me_out Time out, in 1-sec increments.

Return Values
Success: 0: No errors detected.

Failure: -1: No response from the printer.

-2: Invalid printer ID.

-22: Invalid printer type.

-23: Escape sequence not found.

-24: Printer not initialized.

-29: Printer not available.

318 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
p3 70 0_mo de ()

p3700_mode()

Converts special print characters to a valid printer command sequence. This

sequence is appended to the buffer passed as the second argument. Returns an
updated pointer to the print buffer.

Prototype #i ncl ude <pr i nt er. h>

unsi gned char *p3700_mode( unsi gned char mode, unsi gned char *buf ) ;

Parameters
mode Special print character.
buf Pointer to the print buffer.

Retur n Values
Success: 0: No errors detected.

Failure: -1: No response from the printer.

-2: Invalid printer ID.

-22: Invalid printer type.

-23: Escape sequence not found.

-24: Printer not initialized.

-29:Printer not available.

p3700_print()

Sends a text string to the ITP.

Prototype #i ncl ude <pr i nt er. h>

i nt p3700_pr i nt ( shor t h_comm_por t , unsi gned char * buf ) ;

Parameters
h_comm_por t Handle to the opened communications port.
buf Pointer to the string to print (maximum 1000 bytes).

Retur n Values
Failure: < 0: Port write error.

1: No send attempted; returns 1 for formatter engine; or

Success:  1: Actual number of characters sent to printer.

VERIX EVO ACT PROGRAMMERS GUIDE 319

F UNCTION C A L L S
p3 70 0_ pr int_ grap hi c()

p3700_print_graphic()

Prints a graphic file already in printer memory.

Prototype #i ncl ude <pr i nt er. h>

shor t p3700_pr i nt _gr aphi c( shor t h_comm_por t , shor t i mageI d,
shor t of f set ) ;

Parameters
h_comm_por t Handle for the opened communication port.
i mageI d The index of the image ID must be 0.
of f s et The left margin for the image.

Return Values
Success: > 0: No error.

Failure:  0: Error occurred.

p3700_select_font()

Selects the font table to use for printing or downloading.

Prototype #i ncl ude <pr i nt er. h>

shor t p3700_sel ect _f ont ( short h_comm_por t , short f ont _si ze,
s hor t f ont _ t abl e) ;

Parameters
h_comm_por t Handle for the opened communication port.
f ont _ s i z e Size of the font.
f ont _ t abl e Font table to select.

Return Values
Success: > 0: No error.

Failure: < 0: Error selecting the font.

320 VERIX EVO ACT PROGRAMMERS GUIDE

F UNCTION C A LL S
p3 70 0_ sel_ tb l_ dn ld _c ha r()

p3700_sel_tbl_dnld_char()

Selects the font table, then downloads a single font character to the printer.

Prototype #i ncl ude <pr i nt er. h>

shor t p3700_sel _t bl _dnl d_char ( shor t h_comm_por t , unsi gned char *f ont _buf ,
s hor t f ont _ t abl e, s hor t f ont _ s i z e, s hor t
f ont _bytes) ;

Parameters
h_comm_por t Handle for the opened communication port.
f ont _buf Buffer containing the bytes to download to the printer.
f ont _ t abl e Font table to select.
f ont _ s i z e Size of the font (valid values determined by printer).
f ont _bytes Number of characters to download (including the char to replace). For
example, an 8 x 14 font requires 15 bytes.

Retur n Values
Success: 0: No error.

Failure: -11: Download failed.

VERIX EVO ACT PROGRAMMERS GUIDE 321

F UNCTION C A L L S
p3 70 0_ stat us()

p3700_status()

Sends the <ESC>d command to the ITP and waits for it to respond with its status
byte. The time-out value is specified in increments of 1000 ms (1 second).
Specifying a time-out value of 6 allows the printer approximately 6 seconds to
respond.

Prototype #i ncl ude <pr i nt er. h>

i nt p3700_st atus ( short h_comm_por t , short st at_ t i me_out ) ;

Parameters
h_comm_por t Handle to the opened communications port.
st at_ t i me_out Time-out period, in increments of approximately 500 ms.

Return Values
Success: 0: No error.

Failure: -4: No status.

-5 : Paper low.

-10: RAM error.

-20: Printer failure.

-21: Paper out.

-23: Escape sequence not found.

-24: Printer not initialized.

-27: Firmware corrupt.

322 VERIX EVO ACT PROGRAMMERS GUIDE

A PPENDIX A

Example Programs

This chapter provides example code for the following:

• EXFIELD.C displays the prompt, ACL FIELD FUNCS, then displays the
prompt, FIELDCNT EXAMPLE
• EXTMOUT.C defines 11 time outs, ranging from 1 second to 3 minutes
• EXTRANS.C prompts for an account and waits for either a card swipe or
keyboard input
• Data Capture Engine Example Program demonstrates the functionality of
DCE.
• Modem Engine Example Program demonstrates the functionality of modem
engine.
• Report Formatter Example Program demonstrates the functionality of report
formatter.
• P3700 Example Program demonstrates the use of all P3700 printer functions.
Further description of each application is included as code comments.

VERIX EVO ACT PROGRAMMERS GUIDE 323

E XAMPLE P ROGRAMS
EXFI ELD. C

EXFIELD.C / *************************************************
* Appl i cat i on: EXFI ELD
* Rel ease Dat e: 7/ 12/ 99
* Ver si on: 1. 0
*
* Pur pose: Demonst r at es usage of Veri x eVo ACT Li br ar y f unct i ons:
* f i el dcnt , f i el df i x , f i el dr ay and f i el dvar
* Ot her ACL f unct i ons used :
* pr ompt , get _char , vi ew_buf f er , di spl ay
* Descr i pt i on: EXFI ELD di spl ays t he pr ompt ACL FI ELD
* FUNCS
* I t t hen di spl ays t he pr ompt FI ELDCNT EXAMPLE.
* The buf f er used as i nput t o t he f l d_cnt ( ) f unct i ons i s
* di spl ayed. The user may scr ol l t hr ough t he buf f er usi ng
* t he # and keys.
* Keys CLEAR or ENTER t er mi nat e t he di spl ay. Next each
* f i el d i n t he buf f er i s di s pl ayed.
* Next , t he pr ompt FI ELDFI X i s di spl ayed. The buf f er
* used as i nput t o t he f l d_f i x( ) f uncti on i s di spl ayed
* f or r evi ew , f ol l owed by each f i el d i n t he buf f er .
* EXFI ELD t hen di spl ays t he FI ELDRAY EXAMPLE pr ompt . The
* buf f er used as i nput t o t he f l d_r ay( ) f uncti on i s
* di spl ayed f or r evi ew , f ol l owed by each f i el d i n t he
* buf f er .
* EXAMPLE OF VARI ABLE FI ELDS DELI MI TED BY SPACES.
* Last l y , t he FI ELDVAR EXAMPLE pr ompt i s di spl ayed. The
* buf f er used as i nput t o t he f l d_var ( ) f uncti on i s
* di spl ayed f or r evi ew, f ol l owed by each f i el d i n t he
* buf f er , EXAMPLE OF VARI BALE FI ELDS DELI MI TED BY SPACES
*
****************************************************/
#i ncl ude <acl coni o. h>
#i ncl ude <acl st r . h>
#i ncl ude <st r i ng. h>
#i ncl ude <svc. h>

char exampl e1[ ] =

{ "EXAMPLE OF VARI BALE FI ELDS DELI MI TED BY SPACES" };
i nt ex1_f l d = 7; / * 7 f i el ds del i mi t ed by spaces */
char f l d_f i x[ ] = {"122333444455555" };
i nt num_f i x = 5; char f l d_cnt [ ] = {"\ 0021\ 00312\ 004123\ 0051234\ 00612345"
};
i nt num_cnt = 5;
c har f i el d[ 17] ;
char buf f [ 15] ;

i nt mai n( i nt ar gc, char * ar gv[ ] )

{
i nt consol e, h_cl ock=1;

324 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
EXFIEL D. C

i nt i , j ;

consol e = open( DEV_CONSOLE, 0) ;

pr ompt ( h_cl ock, " ACL FI ELD FUNCS", 100, CLR_EOL) ;

/ * f i el dcnt ( ) exampl e : St ar t i ng at t he begi nni ng of t he

* f l d_ cnt buf f er ( of f s et 0) ,
* s how count ed f i el ds 1 t hrough 5 */

pr ompt ( h_cl ock, " FI ELDCNT EXAMPLE", 100, CLR_EOL) ;

vi ew_buf f er( f l d_cnt , 1, KM_CR | KM_ESC) ;

f or ( i =1; i <=num_cnt ; ++i )

{
j = f i el dcnt ( f l d_cnt , 0, i , f i el d) ;
pr ompt ( h_cl ock, f i el d, 50, CLR_EOL) ;
get_char();
}

/ * f i el df i x( ) exampl e :
* Show f i xed f i el ds of l engt hs 1 t hr ough 5 f r om f l d_f i x
* buf f er .
* Of f set s t o st ar t f i el d at ar e based on t he r et ur n val ue
* ( f i el d s i z e ) f r om t he pr evi ous f i el df i x( ) cal l * /

pr ompt ( h_cl ock, " FI ELDFI X EXAMPLE" , 1000, CLR_EOL) ;

vi ew_buf f er( f l d_f i x, 1, KM_CR | KM_ESC) ;

f or ( i =1 , j =0; i <= num_f i x; ++i )

{
j += f i el df i x( f l d_f i x , j , i , f i el d) ;
pr ompt ( h_cl ock, f i el d, 500, CLR_EOL) ;
get_char();
}

/ * f i el dr ay( ) exampl e :
* Show r ay f i el ds, each ter mi nated by space, f r om
* exampl e Of f set s to st art f i el d at ar e based on t he
* r et ur n val ue ( f i el d s i z e) f r o m t he pr e vi ous f i el df i x( )
* cal l * /

pr ompt ( h_cl ock, " FI ELDRAY EXAMPLE", 1000, CLR_EOL) ;

vi ew_buf f er ( exampl e1, 1, KM_CR | KM_ESC) ;

f or( j = 0; j < st r l en( exampl e1) ; ++j )

{
j += f i el dr ay( exampl e1 , j , ' ' , f i el d) ;

VERIX EVO ACT PROGRAMMERS GUIDE 325

E XAMPLE P ROGRAMS
EXFI ELD. C

pr ompt ( h_cl ock, f i el d, 500, CLR_EOL) ;

get _char ( ) ;
}

/ * f i el dvar ( ) exampl e :
* Show var i abl e f i el ds 1 t hr ough 5 i n exampl e1 buf f er .
* Each f i el d i s t ermi nated by space.
*/

pr ompt ( h_cl ock, " FI ELDVAR EXAMPLE", 1000, CLR_EOL) ;

vi ew_buf f er ( exampl e1, 1, KM_CR | KM_ESC) ;

f or ( i =1; i <= ex1_f l d; ++i )

{
j = f i el dvar ( exampl e1, i , ' ' , f i el d) ;
pr ompt ( h_cl ock, f i el d, 500, CLR_EOL) ;
get _char ( ) ;
}
di spl ay( "\ f END EXFI ELD") ;
r etur n 1;
}

326 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
EXT MOUT.C

EXTMOUT.C / *******************************************
* Appl i cat i on: EXTMOUT
* Rel ease Dat e: 07/ 12/ 99
* Ver si on: 1. 0
* Pur pose: Demonst r at es usage of Ver i x eVo ACT Li br ary f unct i ons:
* set _i t i meout and CHK_TI MEOUT
* Ot her ACL f unct i ons used - di spl ay and di spl ay_at
*
* Descr i pt i on: EXTMOUT def i nes 11 t i meout s r angi ng f r om 1
* second t o 3 mi nut es f r omcur r ent t i me.
* Each t i meout cont r ol s what i s di spl ayed at a
* cor r espondi ng di spl ay posi t i on.
* EXTMOUT di spl ays a "t wi nkl i ng" char act er i n each of t he
* 16 di spl ay posi t i ons.
* As each t i meout expi r es , EXTMOUT di spl ays t he
* cor r espondi ng l ett er f r oma pr ogr ammessage i n t he
* di spl ay posi t i on assi gned t o t he t i meout .
****************************************************/

#i ncl ude <acl dev. h>

#i ncl ude <acl coni o. h>
#i ncl ude <svc. h>

l ong t i meout s[ 16] ;

char t w_char s[ ] = { ' | ' , ' / ' , ' - ' , ' \ \ ' , ' | ' , ' / ' , ' - ' , ' \ \ ' };
char end_pr ompt [ ] = { " END TI MER DEMO" };
char t emp[ 2] ;

i nt mai n( i nt ar gc, char * ar gv[ ] )

{
i nt h_cl ock = 1;
i nt i , dom, t w_i ndex;
i nt consol e;
i nt mor e;

consol e = open( DEV_CONSOLE, 0) ;

di spl ay( " \ f START DEMO" ) ;
get_char();

/ * Set 12 t i meout s - t i meout s r ange f r om 1 second t o 3

* mi nut es f r om cur r ent t i me */
t i meout s[ 11] = set _i t i meout ( h_cl ock, 3, TM_MI NUTES) ;
t i meout s[ 10] = set _i t i meout ( h_cl ock, 2, TM_MI NUTES) ;
t i meout s[ 9] = set _i t i meout ( h_cl ock, 1, TM_MI NUTES) ;
t i meout s[ 8] = set _i t i meout ( h_cl ock, 50*TI CKS_PER_SEC, TM_TI CKS) ;
t i meout s[ 7] = set _i t i meout ( h_cl ock, 45, TM_SECONDS) ;

VERIX EVO ACT PROGRAMMERS GUIDE 327

E XAMPLE P ROGRAMS
EXTM OU T.C

t i meout s[ 6] = set _i t i meout ( h_cl ock, 30*TI CKS_PER_SEC, TM_TI CKS) ;

t i meout s[ 5] = set _i t i meout ( h_cl ock, 25, TM_SECONDS) ;
t i meout s[ 4] = set _i t i meout ( h_cl ock, 20*TI CKS_PER_SEC, TM_TI CKS) ;
t i meout s[ 3] = set _i t i meout ( h_cl ock, 15, TM_SECONDS) ;
t i meout s[ 2] = set _i t i meout ( h_cl ock, 10*TI CKS_PER_SEC, TM_TI CKS) ;
t i meout s[ 1] = set _i t i meout ( h_cl ock, 5*TI CKS_PER_SEC, TM_TI CKS) ;
t i meout s[ 0] = set _i t i meout ( h_cl ock, 1*TI CKS_PER_SEC, TM_TI CKS) ;

/ * Whi l e al l t i meout s have not expi r ed */

mor e = 1;
t w_i ndex =0;

whi l e( mor e)
{
mor e = 0;
gotoxy( 1, 1) ;

/ * Check each t i meout i f i t has not expi r ed , di spl ay

* "t wi nkl e" char act er ot her wi se di spl ay cor r espondi ng
* l et t er of END message */

f or( i =0; i <16; ++i )

{
i f ( CHK_TI MEOUT( h_cl ock, t i meout s[ i ] ) )
{
t emp[ 0] =t w_char s[ t w_i ndex] ;
t emp[ 1] =' \ 0' ;
di spl ay_at ( 1, 1, t emp, CLR_EOL) ;
mor e = 1;
}
el s e
{
t emp[ 0] =end_pr ompt [ i ] ;
t emp[ 1] =' \ 0' ;
di spl ay( t emp) ;
}
}
t w_i ndex = ( ++t w_i ndex) %8;
}
}

328 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
EXTRANS. C

EXTRANS.C / ****************************************************
* Appl i cat i on: EXTRANS
* Rel ease Dat e: 07/ 12/ 99
* Ver si on: 1. 0
* Pur pose: Demonst r at es usage of Ver i x eVo ACT Li br ary f unct i ons:
* append_char , r ange, sput f , st r 2l ong, di spl ay,
* ERR_BEEP, get kbd_ent r y, KBHI T, keyi n_amt _r ange,
* NORM_BEEP pr ompt _at , vi ew_buf f er , chk_car d_r dr ,
* car d_par se , MEMCLR
* Descr i pt i on: EXTRANS pr ompt s f or an account and wai t s
* f or ei t her a car d swi pe or keyboar d i nput .
* I f keyboar d i nput , EXTRANS r eads t he account and t hen
* prompt s f or and r eads an expi r at i on date. I f car d i nput
* , EXTRANS reads t he car d and par ses t hi s car d
* i nf ormati on. Af t er t he account i s r ead , EXTRANS
* prompt s f or an amount . I t t hen val i dat es bot h t he
* account t he expi r at i on dat e. Account i s val i dated based
* on r ange dat a i n conf i g. sys and must be bet ween
*1000- 5999
* Expi r ati on data i s val i dat ed based on the cur r ent Opsys
* dat e. I f an er r or i s f ound, an appr opr i at e message i s
* di spl ayed. The user may scr ol l t hr ough i t ( usi ng # and * keys ) and exi t
t he di spl ay t hr ough t he Cl ear or Ent er
* keys.
**************************************************/

#i ncl ude <acl coni o. h>

#i ncl ude <acl dev. h>
#i ncl ude <acl st r . h>
#i ncl ude <acl ut i l . h>
#i ncl ude <svc. h>
#i ncl ude <svct xo. h>
#i ncl ude <st r i ng. h>
#i ncl ude <appl i dl . h>

char messages[ 3] [ 16] =

{ " ACL EXAMPLE" , " 1 = CONTI NUE" , " CANCEL = END" };
char er r or _msg[ ] = { "I NVALI D KEY" };
char buf f [ CARD_SI ZE] ;
char szKeyMap[ MAX_ALPNUM_KEYS] [ CHAR_PER_KEY] = {" 0- +%" , " 1QZ. " , " 2ABC&" ,
"3DEF%", "4GHI *" , "5J KL", "6MNO~", "7PRS^", "8TUV[ ", "9WXY]’ , "* , ’ \ ": ",
" #=: $?" };

struct
{
i nt t ype;
st r uct TRACK car d_i nf o;
char r ange_dat a[ 12] ;
char amount [ 15] ;
}i nput ;

VERIX EVO ACT PROGRAMMERS GUIDE 329

E XAMPLE P ROGRAMS
EXTR ANS. C

RANGE_ PARMS r _par m;

i nt get _key_i nput ( i nt h_cl ock) ;

i nt ver i f y_exp_dat e( i nt h_cl ock) ;
voi d Adj ust Val ue( unsi gned char * key) ;

i nt mai n( i nt ar gc, char * ar gv[ ] )

{
i nt h_cl ock = 1;
i nt h_car d;
i nt consol e;
char * p_pr ompt s[ 3] ;
i nt i , er r f l ag;
unsi gned char ch;

wi ndow( 1, 1, 16, 1) ;
h_c ar d = open( DEV_CARD, 0) ;
h_cl ock = open( DEV_CLOCK, 0) ;
consol e = open( DEV_CONSOLE, 0) ;
f or( i =0; i <=2; ++i )
p_pr ompt s[ i ] = messages[ i ] ;

r _par m. l abel = " ACCT";

r _parm. dat a_f l d = i nput . r ange_data;
r _par m. st ar t = 1;
r _par m. f i l e_name = " CONFI G. SYS";

whi l e( 1)
{
cl r s cr ( ) ;
di spl ay_at ( 1, 1, p_prompt s[ 0] , CLR_EOL) ;
di spl ay_at ( 1, 2, p_prompt s[ 1] , CLR_EOL) ;
di spl ay_at ( 1, 3, p_prompt s[ 2] , CLR_EOL) ;
ch = get _char ( ) ;
Adj ust Val ue( &ch) ;
i f ( ch == ' 1' )
{
/ * Cont i nue sel ect i on wai t f or ei t her car d swi pe or keyboar d ent r y*/

r _par m. st ar t = 1;
err f l ag = 0;
MEMCLR( &i nput , si zeof ( i nput ) ) ;
cl r s cr ( ) ;
di spl ay_at ( 1, 1, " ACCOUNT ?" , CLR_EOL) ;
whi l e(! chk_car d_r dr ( h_card) &&! KBHI T() ) ;
330 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
EXTRANS. C

/ * I f car d swi pe , r ead car d data and parse */

i f ( chk_car d_r dr ( h_car d) )

{
r ead( h_car d, buf f , 256) ;
i nput . t ype = car d_par se( buf f , &i nput . car d_i nf o, "123") ;
}
el s e
/ * El se must be keyboar d dat a so get dat a and st or e */
i nput . t ype = get _key_i nput ( h_cl ock) ;
err f l ag = ( i nput . t ype >=0) ? 0 : - 1;
/ * Get amount , val i d amount s ar e bet ween 1. 00 and 999999. 99 .
* amount s ar e st or ed wi t h comma separ at or and deci mal
* poi nt r adi x i n st r _amount */

i f ( er r f l ag >= 0)
{
cl r s cr ( ) ;
di spl ay_at ( 1, 1, " AMOUNT?" , CLR_EOL) ;
keyi n_amt _r ange( i nput . amount , RDXPSEPC, 99999999L, 100L, 2) ;
/ * Veri f y expi r ati on date and account r ange */

i f ( 0 >= ( er r f l ag = ver i f y_exp_dat e( h_cl ock) ) )

{
r _par m. acct_num = i nput . car d_i nf o. acct;
er r f l ag = ( r ange( &r _par m) <= 0) ?- 3: 1;
}
}

/ * I f i nval i d account / dat e , di spl ay appr opr i at e er r or message */

i f ( er r f l ag < 0)
{
s wi t c h( er r f l ag)
{
case( - 2) :
di spl ay( "\ f DATE") ;
br eak;
case( - 3) :
di spl ay( "\ f ACCT") ;
br eak;
def aul t :
di s pl ay( " \ f I NPUT" ) ;
br eak;
}

VERIX EVO ACT PROGRAMMERS GUIDE 331

E XAMPLE P ROGRAMS
EXTR ANS. C

ERR_BEEP( ) ;
pr ompt _at ( h_cl ock, 7, 1, " ERROR" , 1000, NO_CLEAR) ;
}

/ * I f t her e i s some i nput , t hen f or mat dat a f or di spl ay

* and l et user r evi ew i t . Revi ew i s t er mi nat ed wi t h
* ei t her t he Ent er or Cancel key */

i f ( er r f l ag ! = - 1)
{
MEMCLR( buf f , si zeof ( buf f ) ) ;
i f ( i nput . t ype == 0)
st r cpy(buf f , "KEY I NPUT: ") ;
el s e
spr i nt f ( buf f , "TRACK %d I NPUT: ", i nput . t ype) ;
st r cat ( buf f , " ACCT=") ;
s t r c at ( buf f , i nput . c ar d_ i nf o. ac ct ) ;
st r cat ( buf f , " EXP DATE=") ;

s t r nc at ( buf f , i nput . c ar d_ i nf o. exp, 7) ;

st r cat ( buf f , " RANGE= ") ;
st r ncat ( buf f , i nput . r ange_dat a, 7) ;
st r cat ( buf f , " AMOUNT=" ) ;
append_char ( buf f , ' $' ) ;
st r cat ( buf f , i nput . amount ) ;

NORM_BEEP( ) ;
vi ew_buf f er ( buf f , 1, KM_CR | KM_ESC) ;
}
}
el s e
i f ( ch == KEY_CANCEL)
br eak;
}
di spl ay( "\ f END EXAMPLE" ) ;
r etur n 1;
}

/ * get account and pr ompt f or and r ead a yymm expi r at i on dat e */

i nt get _key_i nput ( i nt h_cl ock)

{
i nt r et _ val ;

/ * Get account . Wai t f or ever f or i nput . Val i d val ues ar e

* numer i c wi t h at l east 1 char act er and no mor e t han 16
* char acters. */

332 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
EXTRANS. C

r et_ val =
getkbd_ent r y(h_cl ock, NULL, i nput . car d_i nf o. acct , 0, NUMERI C, szKeyMap, si zeof (
szKeyMap) , 16, 1) ;
i f ( 0 < r et _ val )
{
/ * Get expi r ati on dat e - must be 4 numeri c charact ers. */

r et_ val = get kbd_ent r y( h_cl ock, "EXP

DATE( YYMM) ?" , i nput . card_i nf o. exp, 0, NUMERI C, szKeyMap, si zeof ( szKeyMap) , 4, 4)
;
}
r et ur n( ( r et _ val >0) ? 0 : r et _ val ) ;
}

/ * Si mpl e expi r at i on dat e val i dat i on. Expi r at i on dat e must be val i d and of
f or m yymm. */

i nt ver i f y_exp_dat e( i nt h_cl ock)

{
i nt r et v al = 1;
char cur _dat e[16] , car d_dat e[ 7] ;

i f ( r ead( h_cl ock, cur _dat e, 15) ! = 15)

r et val = - 1;

memcpy( car d_dat e+2, i nput . card_i nf o. exp, 4) ;

car d_dat e[ 6] = ' \ 0' ;
cur _dat e[ 6] = ' \ 0' ;

i f ( c ar d_ dat e[ 2] > ' 6' )

memcpy( car d_dat e, " 19" , 2) ;
el s e
memcpy( car d_dat e, " 20" , 2) ;
r et val = ( st r 2l ong( car d_dat e) <= st r 2l ong( cur _dat e) ) ? 1: - 2;
r e t ur n( r e t val ) ;
}

voi d Adj ust Val ue( unsi gned char * key)

{
i f ( *key > 0xf 9)
*key - = 0xf 9; / / scr een keys: f a- f d - > 1- 4
el se i f ( *key < 0xef )
*key &= 0x7f ; / / keypad keys: 0- ef - > 0- 7f
}

VERIX EVO ACT PROGRAMMERS GUIDE 333

E XAMPLE P ROGRAMS
Da ta Capt ure Engi ne Ex am ple Pro gr am

Data Capt ur e / * SAMPLE PROGRAM TO DEMONSTRATE THE FUNCTI ONALI TY OF DCE

Engine 1. DCE_PUTCFG_C( )

Example 2. DCE_GETCFG_C( )

Program 3. DCE_PUTCFG_S( )
4. DCE_GETCFG_S( )
5. dce_key_cvt ( )
*/

#i ncl ude <acdce. h>

#i ncl ude <st di o. h>
mai n ( )
{
i nt consol e_handl e;
i nt i , r t n_ val ;
unsi gned i nt ui ;
DCE_KEY_DATA set _val ;
DCE_KEY_DATA get _val ;
unsi gned char st r [ 3] , st r 1[ 3] ;
unsi gned char c, c1;

consol e_handl e = open( " / dev/ consol e", 0) ;

pr i nt f ( " \ f DCE DEMO- CONFI G. SYS\ n" ) ;
get_char();

set _val . c_val = &c;

get _val . c_val = &c1;

c = ' A' ;
/ / Add CONFI G. SYS key DCE- 1 wi t h val ue ’ A’
r t n_val = DCE_PUTCFG_C( " DCE- 1", set _val ) ;
i f ( r t n_ val ! = 1)
pr i nt f ( "WRI TE - FAI L %d\ n", r t n_val ) ;
el s e
pr i nt f ( "DCE- 1 = %c (CHAR) \ n", *set _val . c_val ) ;
get_char();

/ / Read CONFI G. SYS key DCE- 1 i nt o char var i abl e c1

i f ( ( r t n_val = DCE_GETCFG_C( " DCE- 1" , get _val ) ) ! = 1)
pr i nt f ( "READ - FAI L %d\ n", r t n_val ) ;
el s e
pr i nt f ( "DCE- 1 = %c ( AGAI N) \ n", *get _val . c_val ) ;
get_char();

set _val . s_val = st r ;

get _val . s_val = st r 1;

334 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
Da ta Capt ure Engi ne Ex ampl e Progr am

/ / Wr i t e CONFI G. SYS key DCE- 2 wi t h st r i ng ( val ue=CC)

mems et ( s t r , ' \ 0' , s i z eof ( s t r ) ) ;
mems et ( s t r , ' C' , s i z eof ( s t r ) - 1) ;
get _val . s_val = st r 1;
i f ( ( r t n_val = DCE_PUTCFG_S(" DCE- 2", set _val ) ) ! = 1)
pr i nt f ( "WRI TE - FAI L %d\ n", r t n_val ) ;
el s e
pr i nt f ( "DCE- 2 = %s ( STR) \ n", set _val . s_val ) ;
get _char ( ) ;

i f ( ( r t n_val = DCE_GETCFG_S( " DCE- 2" , get _val ) ) ! = 1)

pr i nt f ( "READ - FAI L %d\ n", r t n_val ) ;
el s e
pr i nt f ( "DCE- 2 = %s ( AGAI N) \ n", get _val . s_val ) ;
get _char ( ) ;

/ / Demonst r at e t he use of t he dce_key_cvt f unct i on

/ / Wr i t e CONFI G. SYS key DCE- 3 wi t h st r i ng ( val ue=DD)
mems et ( s t r , ' \ 0' , s i z eof ( s t r ) ) ;
mems et ( s t r , ' D' , s i z eof ( s t r ) - 1) ;
i f ( ( r t n_val = dce_key_cvt ( DCE_WRI TE, "conf i g. sys", "DCE- 3", DCE_S,
s et _ val ) ) ! = 1)
pr i nt f ( "READ - FAI L %d\ n", r t n_val ) ;
el s e
pr i nt f ( "DCE- 3 = %s ( STR) \ n", set _val . s_val ) ;
get _char ( ) ;

i f ( ( r t n_val = dce_key_cvt ( DCE_READ, "conf i g. sys", "DCE- 3", DCE_S,

get _ val ) ) ! = 1)
pr i nt f ( "READ - FAI L %d\ n", r t n_val ) ;
el s e
pr i nt f ( "DCE- 3 = %s ( AGAI N) \ n", get _val . s_val ) ;
get _char ( ) ;
/ / I f you check CONFI G. SYS, DCE- 1 = A, DCE - 2= CC
pr i nt f ( " END OF DCE DEMO" ) ;
cl ose( consol e_handl e) ;
}

VERIX EVO ACT PROGRAMMERS GUIDE 335

E XAMPLE P ROGRAMS
Mo de m Engi ne Exam pl e Pro gram

Modem Engi ne / * To use t he t est pr ogr am: You r equi r e 2 t er mi nal s

Example
Program 1. UnComment t he cal l MdmCal Test ( ) and comment t he cal l MdmRecTest ( ) i n
mai n( )
2. Change t he phone number t o t he appr opr i at e number t o whi ch t he host
t ermi nal wi l l be connect ed and bui l d t he workspace
3. Downl oad t he out put f i l e (. out ) t o one ter mi nal . Thi s act s as t he
cal l er
4. UnComment t he cal l MdmRecTest ( ) and comment t he cal l MdmCal Test ( ) i n
mai n( ) and bui l d t he wor kspace
5. Downl oad the out put f i l e (. out ) t o t he second t er mi nal . Thi s acts as
t he host . */
#i ncl ude <st dl i b. h>
#i ncl ude <st r i ng. h>
#i ncl ude <st di o. h>
#i ncl ude <acl coni o. h>
#i ncl ude <svc. h>
#i ncl ude <xmodem. h>

voi d MdmCal Test ( ) ;

voi d MdmRecTest ( ) ;

unsi gned i nt mai n( voi d)

{
i nt conHandl e;
conHandl e = open( " / dev/ consol e", 0) ;

MdmCal Test ( ) ; / / Cal l er Modul e

/ / MdmRecTest ( ) ; / / r ecei ver Modul e
r etur n 0;
}

voi d msg_wai t ( char *s z_ msg )

{
wr i t e_at( sz_msg, st r l en( sz_msg) , 1, 2) ;
SVC_WAI T( 1000) ;
}
i nt get _z p_phonenum( char *s z_ phonebuf f )
{
char szpt r [ 50] ;
i nt r et Val ;
r et Val = ( shor t ) get _env( "*ZP", ( char *) szpt r , 5) ;
i f ( szpt r ! = NULL)
{
st r ncpy( sz_phonebuf f , szpt r , 5 ) ;
}

336 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
Mo de m Engi ne Ex ampl e Pro gram

el s e
{
msg_wai t ( "\ f *ZP I S BAD. FI X. " ) ;
st r cpy( sz_phonebuf f , "\ 0") ;
}
s zpt r [ 5] =' \ 0' ;
sz_phonebuf f [ 5] = ' \ 0' ;
i f ( szpt r ! = NULL)
return (0);
return (-1);
}

voi d MdmCal Test ( )

{
i nt r et Val ;
i nt handl e = - 1;
char dl St r [ 20] ;
char dat aTx[ 10] ;
char dat aRx[ 10] ;
i nt i wr i t e, i ;
char t est [ 20] ;
wr i t e_at ( "Modem TEST", 10, 1, 1) ;
r et Val = xmdm_open( &handl e, NULL, - 1, 6, Rt _1200, Fmt _A7E1) ;
s pr i nt f ( t es t , " openi ng, %d" , r et Val ) ;
wr i t e_ at ( t es t , 11, 1, 2) ;
r et Val = xmdm_f l ush( handl e) ;
s pr i nt f ( t es t , " Cl ear i ng, %d" , r et Val ) ;
wr i t e_ at ( t es t , 11, 1, 3) ;

i f ( ( r etVal = get_ zp_phonenum( dl St r ) ) ! = 0)

return;
r et Val = xmdm_get _l i ne_di al ( handl e, dl St r , &i wr i t e, - 1, 15) ;
s pr i nt f ( t es t , " Di al ed, %d" , r et Val ) ;
wr i t e_ at ( t es t , 10, 1, 4) ;

i f ( ( r et Val == CONNECT_300) | | ( r et Val == CONNECT_1200)

| | ( r et Val == CONNECT_2400) )
{
/ / send and r eci eve dat a
wr i t e_at ( "connect scs", 11, 1, 5) ;
wr i t e_ at ( " Rec d : " , 6, 1, 8) ;
wr i t e_ at ( " Sent : " , 6, 1, 7) ;
SVC_WAI T( 100) ;
f or( i = 0; i <10; i ++)
{
memset( dataTx, 0, si zeof ( dataTx) ) ;
VERIX EVO ACT PROGRAMMERS GUIDE 337

E XAMPLE P ROGRAMS
Mo de m Engi ne Exam pl e Pro gram

spr i nt f ( dat aTx, "PI NG %d", i ) ;

r et Val = xmdm_send_dat a( handl e, dat aTx, st r l en( dat aTx) , 10) ;
wr i t e_at ( dat aTx, 6, 8, 7) ;
SVC_WAI T( 400) ;
memset ( dat aRx, 0, si zeof ( dat aRx) ) ;
do{
r et Val = xmdm_r ecei ve_dat a( handl e, dat aRx, 0, 6, 10) ;
} whi l e( r et Val ! = 6) ;
wr i t e_at ( dat aRx, 6, 8, 8) ;
SVC_WAI T( 400) ;
}

}
SVC_WAI T( 1000) ;
/ / di sconnect
r et Val = xmdm_hangup( handl e, - 1, 0) ;
s pr i nt f ( t es t , " di s connec t , %d" , r et Val ) ;
wr i t e_ at ( t es t , 13, 1, 5) ;

r et Val = xmdm_cl ose( handl e, 0, 0) ;

s pr i nt f ( t es t , " c l os i ng, %d" , r e t Val ) ;
wr i t e_ at ( t es t , 11, 1, 6) ;

voi d MdmRecTest ( )
{
i nt r et Val ;
i nt handl e = - 1;
char dl St r [ 20] ;
char dat aTx[ 10] ;
char dat aRx[ 10] ;
i nt i ;
char t est [ 20] ;

wr i t e_at ( "Modem TEST", 10, 1, 1) ;

r et Val = xmdm_open( &handl e, NULL, - 1, 6, Rt _1200, Fmt _A7E1) ;

s pr i nt f ( t es t , " openi ng, %d" , r et Val ) ;
wr i t e_ at ( t es t , 11, 1, 2) ;
SVC_WAI T( 1000) ;
s t r c py( dl St r , " S0=1" ) ; / / wai t f or one di al r i ng onl y
r et Val = xhayes_send_cmd( handl e, dl St r ) ;

r et Val = xmdm_f l ush( handl e) ;

s pr i nt f ( t es t , " Cl ear i ng, %d" , r et Val ) ;
338 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
Mo de m Engi ne Ex ampl e Pro gram

wr i t e_ at ( t es t , 11, 1, 4) ;

wr i t e_at ( " WAI TI NG 1200 CALL" , 17, 1, 4) ;

do {
r etVal = xhayes_r esponse( handl e, - 1, 0) ;
spr i nt f ( t est , "Resp %d", r et Val ) ;
wr i t e _at ( t e st , ( s hor t ) s t r l en( t es t ) , 1, 5) ;
} whi l e ( r et Val ! = CONNECT_1200) ;

wr i t e_at ( " CONNECTED" , 9, 1, 6) ;

wr i t e_ at ( " Rec d : " , 6, 1, 8) ;

wr i t e_ at ( " Sent : " , 6, 1, 7) ;

f or( i = 0; i <10; i ++)

{
memset ( dat aRx, 0, si zeof ( dat aRx) ) ;
do{
r et Val = xmdm_r ecei ve_dat a( handl e, dat aRx, 0, 6, 10) ;
} whi l e (r et Val ! = 6) ;
wr i t e_at ( dat aRx, 6, 8, 8) ;
SVC_WAI T( 400) ;
memset( dataTx, 0, si zeof ( dataTx) ) ;
spr i nt f ( dataTx, "PONG %d", i ) ;
r et Val = xmdm_send_dat a( handl e, dat aTx, st r l en( dat aTx) , 10) ;
wr i t e_at ( dat aTx, 6, 8, 7) ;
SVC_WAI T( 400) ;
}
SVC_WAI T( 1000) ;
whi l e( xmdm_out put _pendi ng( handl e) == X_OUTPUT_PEND) ;
/ / di sconnect
r et Val = xmdm_hangup( handl e, - 1, 0) ;
s pr i nt f ( t es t , " di s connec t , %d" , r et Val ) ;
wr i t e_ at ( t es t , 13, 1, 5) ;

r et Val = xmdm_cl ose( handl e, 0, 0) ;

s pr i nt f ( t es t , " c l os i ng, %d" , r e t Val ) ;
wr i t e_ at ( t es t , 10, 1, 6) ;
}

VERIX EVO ACT PROGRAMMERS GUIDE 339

E XAMPLE P ROGRAMS
Re po rt Format te r Ex am pl e Pro gram

Report #i ncl ude<st di o. h>

Formatter #i ncl ude<svc. h>

Example #i ncl ude<st r i ng. h>

Program #i ncl ude<pr i nt er. h>

#i ncl ude<f or mat er . h>

char t erm_i d[ 11] ;

char date[ 9] ;
char v_t i me[6] ;
char bonus;
l ong i nt _ t t l ;
l ong cum_t t l ;
l ong i nt _ bi l ;
l ong cum_bi l ;
l ong i nt _crd;
l ong cum_c r d;
char name[ 5] ;
i nt t es t ;

#i f ndef G_C
#def i ne G_C 1
#def i ne G_S 2
#def i ne G_I 3
#def i ne G_L 4
t ypedef st r uct
{
voi d *addr ;
i nt t ype;
}g_dat a;
#endi f

g_dat a gvar dat a[ ] = {

/ * 0 */ { ( voi d *) t er m_i d, G_S },
/ * 1 */ { ( voi d *) dat e, G_S },
/ * 2 */ { ( voi d *) v_ti me, G_S },
/ * 3 */ { ( voi d *) &bonus, G_C },
/ * 4 * / { ( voi d * ) &i nt _ t t l , G_ L },
/ * 5 */ { ( voi d *) &cum_t t l , G_L },
/ * 6 * / { ( voi d * ) &i nt _ bi l , G_ L },
/ * 7 */ { ( voi d *) &cum_bi l , G_L },
/ * 8 */ { ( voi d *) &i nt _crd, G_L },
/ * 9 */ { ( voi d *) &cum_cr d, G_L },
/ * 10 */ { ( voi d *) name, G_S },
/ * 11 */ { ( voi d *) &t est , G_I }
};

340 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
Re po rt Form at te r Ex am ple Progr am

FORMATER p3300;

i nt p3300_di r ect ( FORMATER* f ormat er, i nt i ni t _t i me_out )

{
f or mat er - >out put _cl ose = p3300_cl ose;
f or mat er - >out put _pr i nt = p3300_pr i nt ;
f or mat er - >out put _mode = p3300_mode;
f or mat er - >di r ect = 1;
f or mat er - >max_buf f er s = 2;
r etur n p3300_i ni t ( f or mater - >h_comm_por t , i ni t _t i me_out ) ;
}

voi d mai n( voi d)

{
i nt i , er r l i ne, s t a r t , h_ c omm_ por t ;
unsi gned l ong condi t i on;
i nt handl e_l ogo;
char t empBuf f [ 30] ;
open_bl ock_t par m;

open( "/ dev/ consol e", 0) ;

/ / I ni t i al i z e t he Gl obal var i abl es
memset ( t er m_i d, ' \ 0' , 11) ;
st r cat ( t erm_i d, "1234567890") ;
memset ( dat e, ' \ 0' , 9) ;
st r cat ( dat e, "09/ 06/ 91") ;
memset ( v_ti me, ' \ 0' , 6) ;
st r cat ( v_t i me, "10: 45") ;
bonus = ' K' ;
i nt _t t l = 23456;
cum_t t l = 2123450;
i nt _bi l = 11111;
cum_bi l = 77777;
i nt _cr d = 8888;
cum_cr d = 12377;
memset ( name, ' \ 0' , 5) ;
st r cpy( name, " wi nd" ) ;
t est = 12345;

pr i nt f ( " F or mat er t es t i ng\ n\ n" ) ;

h_comm_por t = open( " / dev/ com4", 0) ;
memset ( &par m, 0, si zeof ( par m) ) ;
par m. r at e = Rt _19200;
par m. f or mat = Fmt _A8N1 | Fmt _aut o;
par m. pr ot ocol = P_char _mode;
VERIX EVO ACT PROGRAMMERS GUIDE 341

E XAMPLE P ROGRAMS
Re po rt Format te r Ex am pl e Pro gram

par m. par amet er = 0;

set _opn_bl k( h_comm_por t , &par m) ;
SVC_WAI T( 1000) ;
pr i nt f ( "Downl oadi ng Logo Fi l e\ n") ;
p3300_i ni t ( h_comm_por t , 6) ;
SVC_WAI T( 200) ;
handl e_l ogo = open( " act . l go" , O_RDONLY) ;
/ / open a val i d l ogo f i l e
P3300_dnl d_gr aphi c_f i l e ( h_comm_por t , handl e_l ogo) ;

pr i nt f ( " I ni t i al i zi ng\ n" ) ;

f ormat er _mai n( gvar dat a) ;
f ormat er _open( h_comm_por t , &p3300, "t est 3300. f r m" , p3300_di r ect , 12) ;

condi t i on = 0L;
st art = 1;
pr i nt f ( " Pr i nt i ng. . . \ n" ) ;
whi l e( f or mat er _l i ne( &p3300, st ar t , TO_END, 1, condi t i on, &er r l i ne) < 0 )
{
pr i nt f ( t empBuf f , " Pr i nt er e r r : %d" , i ) ;
s t a r t = er r l i ne;
}
pr i nt f ( " Cl os i ng Pr i nt er \ n" ) ;
f ormat er _cl ose( &p3300) ;
pr i nt f ( "\ nFor mat t er End\ n") ;
}

342 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
P3700 Example Program

P3700 Example This example program demonstrates the use of all P3700 printer functions. Return
Program values from the called functions are not generally processed as this is for
demonstration purposes only. VeriFone strongly recommends that you process
the return values in your application using this library.
#i ncl ude <svc. h>
#i ncl ude <st di o. h>
#i ncl ude <st r i ng. h>
#i ncl ude <pr i nt er. h>

voi d mai n( voi d)

{
i nt h andl e; / / f i l e handl e f or t he Pr i nt er
i nt conHandl e; / / f i l e handl e f or t he di spl ay
open_bl ock_t _par m;
/ / st r ucture to f i l l comm par amet er s f or com por t
i nt h_ f o nt _ f i l e; / / handl e t o t he f ont f i l e
i nt r et Val ;
/ / capt ur e t he r et ur n val ue f r om cal l ed f uncti ons
unsi gned char ucChar Val ue;
unsi gned shor t usOf f set ;
unsi gned char pr i nt Buf [ 256 + 1] ;
unsi gned char s _buf [ 10] ;

/ / Open t he Di spl ay Ter mi nal

conHandl e = open( " / dev/ consol e", 0) ;

/ / PRI NTI NG on t he t er mi nal

wr i t e_at( "P3700 Pri nt Sampl e", 18, 1, 1) ;
handl e = open( " / dev/ com4", 0) ;

/ / Set t he Comm Par amet er s

memset ( &par m, 0, si zeof ( par m) ) ;
par m. r at e = Rt _19200;
/ / I TP i s al ways set t o 19200 baud
par m. f or mat = Fmt _A8N1 | Fmt _aut o | Fmt _RTS;
/ / I TP i s al ways set at 8N1
par m. pr ot ocol = P_char _mode;
par m. par amet er = 0;
set _opn_bl k( handl e, &par m) ;
SVC_WAI T( 200) ;
p3700_i ni t ( handl e, 6) ;
SVC_WAI T( 100) ;

/ / Fi l l t he buf f er wi t h t he r ange f or p r i nt abl e

/ / char act er s( 0x20 to 0x7f )

VERIX EVO ACT PROGRAMMERS GUIDE 343

E XAMPLE P ROGRAMS
P3700 Example Program

ucChar Val ue = 0x20;

f or ( ucChar Val ue=0x20; ucChar Val ue<= 0x7f ; ucChar Val ue++)
pr i nt Buf [ ucChar Val ue - 0x20] = ucChar Val ue;
pr i nt Buf [ ucCharVal ue++ - 0x20] =' \ n' ;
pr i nt Buf [ ucCharVal ue++ - 0x20] =' \ 0' ;

/ / St ar t i ng wi t h t he def aul t f ont whi ch 8x14 at 42

/ / col umn mode
r etVal = p3700_pr i nt ( handl e, ( unsi gned char *) " \ n\ n8x14, 42 col umns\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Set t he pr i nt er def aul t f ont t o 8x14 at 32 col umn

/ / mode
r etVal = p3700_sel ect _f ont ( handl e, 0x03, 0) ;
r etVal = p3700_pri nt ( handl e, ( unsi gned char *) " \ n\ n8x14, 32
col umns\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Set t he pr i nt er def aul t f ont t o 5x8 at 24 col umn

/ / mode 5x8 f ont s ar e by def aul t pr i nt ed i n doubl e
/ / wi dt h and hei ght
r etVal = p3700_sel ect _f ont ( handl e, 0x02, 0) ;
r etVal = p3700_pr i nt ( handl e, ( unsi gned char *) " \ n\ n5x8, 24 col umns\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Set t he pr i nt er def aul t f ont back t o 8x14 at 42

/ / col umn mode
r etVal = p3700_sel ect _f ont ( handl e, 0x04, 0) ;
r et Val = p3700_pr i nt ( handl e, ( unsi gned char * ) " \ n\ nBack t o 8x14, 42
col umns\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / pr i nt er i n NORMAl f ont
memset ( pr i nt Buf , 0, si zeof ( pr i nt Buf ) ) ;
pr i nt Buf [ 0] = PRI NT_NORM;
st r cpy( ( char *) &pr i nt Buf [ 1] , ( const char *) " \ n\ nNORMAL PRI NT\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;
/ / Pr i nt i n Doubl e Hei ght
memset ( pr i nt Buf , 0, si zeof ( pr i nt Buf ) ) ;
pr i nt Buf [ 0] = DBL_ HEI GHT;
st r cpy( ( char *) &pr i nt Buf [ 1] , ( const char * ) "DOUBLE HEI GHT\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / pr i nt er i n NORMAl f ont
memset ( pr i nt Buf , 0, si zeof ( pr i nt Buf ) ) ;
pr i nt Buf [ 0] = PRI NT_NORM;
st r cpy( ( char *) &pr i nt Buf [ 1] , ( const char *) "NORMAL PRI NT\ n\ n") ;

344 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
P3700 Example Program

r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Pr i nt i n Doubl e Wi dt h
memset ( pr i nt Buf , 0, si zeof ( pr i nt Buf ) ) ;
pr i nt Buf [ 0] = DBL_ WI DTH;
st r cpy( ( char * ) &pr i nt Buf [ 1] , ( const char *) "DOUBLE WI DTH\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Pri nt i n Doubl e Hei ght and Doubl e Wi dt h

/ / Pl ease not e that Pr i nt i ng At t r i but es can be cl ubbed
/ / meani ngf ul l y
memset ( pr i nt Buf , 0, si zeof ( pr i nt Buf ) ) ;
pr i nt Buf [ 0] = PRI NT_NORM;
pr i nt Buf [ 1] = DBL_ HEI GHT;
pr i nt Buf [ 2] = DBL_ WI DTH;
st r cpy( ( char *) &pr i nt Buf [ 3] , ( const char *) "DOUBLE HEI GHT & WI DTH\ n\ n" ) ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Pr i nt i n I nver s e St yl e
memset ( pr i nt Buf , 0, si zeof ( pr i nt Buf ) ) ;
pr i nt Buf [ 0] = PRI NT_NORM;
pr i nt Buf [ 1] = I NVERSE;
st r cpy(( char *) &pr i nt Buf [ 2] , ( const char *) "I NVERSE PRI NTI NG\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Gr aphi cs Downl oad & pr i nt

st r cpy(( char *) pr i nt Buf , ( const char *) "Downl oadi ng Logo Fi l e") ;
r et Val = st r l en( ( const char *) pr i nt Buf ) ;
wr i t e_ at ( ( c har * ) pr i nt Buf , r e t Val , 1, 1) ;
h_f ont _f i l e = open( "vmacl ogo. l go", O_RDONLY) ;
/ / open a val i d l ogo f i l e
r et Val = p3700_dnl d_gr aphi c_f i l e ( handl e, h_f ont _f i l e) ;

st r cpy( ( char ) pr i nt Buf , ( const char ) "Logo at Of f set 0\ n") ;

r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;
usOf f set = 0; / / Set t he of f set at 0 dot s f r om t he Lef t
r etVal = p3700_pri nt _graphi c( handl e, 0, usOf f set) ;
st r cpy( ( char *) pr i nt Buf , ( const char *) "Logo at Of f set 100\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;
usOf f set = 100;
/ / Set t he of f set at 100 dot s f r om t he Lef t
r etVal = p3700_pri nt _graphi c( handl e, 0, usOf f set) ;

/ / Down l oad f ont f i l e 16 X 16

st r cpy( ( char *) pr i nt Buf , ( const char *) "Downl oadi ng 16x16 Font ") ;
r et Val = st r l en( ( const char *) pr i nt Buf ) ;

VERIX EVO ACT PROGRAMMERS GUIDE 345

E XAMPLE P ROGRAMS
P3700 Example Program

wr i t e_ at ( ( c har * ) pr i nt Buf , r et Val , 1, 1) ;

/ / 16x16 pr i nt er f ont f i l e cont ai ni ng 128 char s f r om
/ / of f s et 0 t o 127
h_f ont _f i l e = open( "16x16. pf t " , O_RDONLY) ;
/ / downl oad t he pr i nt er f ont f i l e at f ont t abl e 1
r et Val = p3700_dnl d_f ont _f i l e (handl e, h_f ont _f i l e, 1) ;
st r cpy( ( char *) pr i nt Buf , ( const char *) "Pri nt i ng 16x16 Font \ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;
r etVal = p3700_sel ect _f ont ( handl e, 0x01, 1) ;
/ / 0x01 corr esponds t o 16x16 f ont si ze

/ / Hexa Dump of 32 Char s downl oaded f r om of f set 0 t o

/ / 31
st r cpy(( char *) pr i nt Buf , ( const char *) "Hexa Dump Pr i nt i ng\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;
memset ( pr i nt Buf , 0, si zeof ( pr i nt Buf ) ) ;
pr i nt Buf [ 0] = SEL_ HEX; / / set t o Hexa Dump Mode
/ / I n Hex Dump Mode each char act er i s s peci f i ed by a
/ / t wo byt e of f set
/ / For exampl e Char act er at of f set 8 i s speci f i ed as
/ / 08 and of f set 15 as 0e
/ / Hexa Dump out put buf f er shoul d t er mi nat e wi t h a
/ / semi col on charact er
/ / Fi l l t he buf f er wi t h t he r ange f or non pr i nt abl e
/ / char act er s( 0x00 to 0x1f )
st r cpy( ( char *) &pr i nt Buf [ 1] , ( const char *)
" 000102030405060708090a0b0c0d0e0f 101112131415161718191a1b1c1d1e1f ; \ n\ n" ) ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;
st r cpy( ( char *) pr i nt Buf , ( const char *) "Pri nt i ng ASCI I Char s\ n\ n") ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;
/ / Hexa Dump not r equi r ed f or charact ers i n pr i nt abl e
/ / r ange
/ / Fi l l t he buf f er wi t h t he r ange f or pr i nt abl e
/ / char act er s( 0x20 to 0x7f )
ucChar Val ue = 0x20;
f or ( ucChar Val ue=0x20; ucChar Val ue<= 0x7f ; ucChar Val ue++)
pr i nt Buf [ ucChar Val ue - 0x20] = ucChar Val ue;
pr i nt Buf [ ucCharVal ue++ - 0x20] =' \ n' ;
pr i nt Buf [ ucCharVal ue++ - 0x20] =' \ 0' ;
r et Val = p3700_pr i nt ( handl e, pr i nt Buf ) ;

/ / Cr eat e the buf f er f or a si ngl e char act er downl oad

/ / of s i z e 5X8
s_buf [ 0] = ' A' ;
/ / To be Downl oaded at of f set 0x41 ( ' A' ) i n 5 X 8 si ze
s_buf [ 1] = 31; / / 00011111
s_ buf [ 2] = 17; / / 00010001
s_ buf [ 3] = 17; / / 00010001

346 VERIX EVO ACT PROGRAMMERS GUIDE

EXAMPLE P ROGRAMS
P3700 Example Program

s_ buf [ 4] = 17; / / 00010001

s_ buf [ 5] = 31; / / 00011111
s_ buf [ 6] = 17; / / 00010001
s_ buf [ 7] = 17; / / 00010001
s_ buf [ 8] = 17; / / 00010001

/ / Sel ect t he f ont t abl e 10 f or a 5x8 char act er t o

/ / s t o r e at of f s et 0x41
r etVal = p3700_sel _t bl _dnl d_char( handl e, s_buf , 10, 0x02, 9) ;
i f ( r et Val < 0)
wr i t e_at( "DNLD FAI L", 9, 1, 1) ;
el s e
r etVal = p3700_pri nt ( handl e, ( unsi gned char *) "A\ n") ;
s_buf [ 0] =' Z' ;
/ / Copy the pat t er n A i n of f set f or Z al so
r etVal = p3700_dnl d_char( handl e, s_buf , 9) ;
i f ( r et Val < 0)
wr i t e_at( "DNLD FAI L", 9, 1, 1) ;
el s e
r etVal = p3700_pri nt ( handl e, ( unsi gned char * ) "AZ\ n") ;
/ / t hi s wi l l pr i nt AA

/ / swi t ch t o f ont t abl e 1 f or 16x16 char act er s

r etVal = p3700_sel ect _f ont ( handl e, 0x01, 1) ;
r etVal = p3700_pri nt ( handl e, ( unsi gned char * ) "AZ\ n") ;
/ / t hi s wi l l pr i nt AZ

/ / swi t ch t o f ont t abl e 10 f or 5X8 char act er s

r etVal = p3700_sel ect _f ont ( handl e, 0x02, 10) ;
r etVal = p3700_pri nt ( handl e, ( unsi gned char * ) "AZ\ n") ;
/ / t hi s wi l l pr i nt AA

SVC_WAI T( 1000) ;
r et Val = p3700_cl ose( handl e) ;
wr i t e_at ( ( char *) "Pr i nt er Demo Compl ete", 21, 1, 1) ;

VERIX EVO ACT PROGRAMMERS GUIDE 347

VeriFone Systems
2099 Gateway Place, Suite 600
San Jose, CA, 95110 USA
(800) VeriFone (837-4366)
www.verifone.com

Verix eVo ACT

Programmers Guide

VeriFone Part Number DOC00310, Revision B

Ansi x9 - 24 1 2009
100% (4)
Ansi x9 - 24 1 2009
92 pages
Verix V Operating System Programmers Manual
100% (3)
Verix V Operating System Programmers Manual
862 pages
Web Designer: TSX ETG 3000 Product Range User Manual
No ratings yet
Web Designer: TSX ETG 3000 Product Range User Manual
310 pages
CXL Subsystem SVT Uvm User Guide
67% (3)
CXL Subsystem SVT Uvm User Guide
164 pages
ISPSoft Tutorial 2008
No ratings yet
ISPSoft Tutorial 2008
33 pages
DeltaV Configuration PDF
100% (1)
DeltaV Configuration PDF
518 pages
PrecisionRTL Style
No ratings yet
PrecisionRTL Style
345 pages
Library System Final
0% (1)
Library System Final
100 pages
Dev Guide
100% (3)
Dev Guide
195 pages
DeltaV Configuration
94% (16)
DeltaV Configuration
518 pages
Programming in C
No ratings yet
Programming in C
132 pages
Control M PDF
No ratings yet
Control M PDF
608 pages
Tib RV CPP Reference
No ratings yet
Tib RV CPP Reference
422 pages
Questa Sim Ref
100% (1)
Questa Sim Ref
1,198 pages
Vse ICCF User's Guide
100% (2)
Vse ICCF User's Guide
509 pages
OVM UserGuide
100% (1)
OVM UserGuide
158 pages
Toolkit FeatUsers Guide Rel 5
No ratings yet
Toolkit FeatUsers Guide Rel 5
371 pages
Modelsim User Guide
No ratings yet
Modelsim User Guide
722 pages
TCL Ucli Modelsim Ref v11p7
No ratings yet
TCL Ucli Modelsim Ref v11p7
564 pages
D800010X062
No ratings yet
D800010X062
605 pages
ModelSim Reference Manual v10.1c
No ratings yet
ModelSim Reference Manual v10.1c
455 pages
User Manual - App Dev Guide 3.14.12
No ratings yet
User Manual - App Dev Guide 3.14.12
334 pages
SoMachine PDF
No ratings yet
SoMachine PDF
962 pages
GC Basic
No ratings yet
GC Basic
375 pages
EcoStruxure Hybrid DCS GPL Process Templates Reference Manual - Eng - EIO0000004043.00
No ratings yet
EcoStruxure Hybrid DCS GPL Process Templates Reference Manual - Eng - EIO0000004043.00
1,270 pages
EcoStruxure Hybrid DCS Process Supervision Services User Guide - Eng - EIO0000000989.15
No ratings yet
EcoStruxure Hybrid DCS Process Supervision Services User Guide - Eng - EIO0000000989.15
434 pages
Modelsim Se Ref
No ratings yet
Modelsim Se Ref
734 pages
ModelSim ME v10.5c User PDF
No ratings yet
ModelSim ME v10.5c User PDF
808 pages
Dialogic SDK
No ratings yet
Dialogic SDK
592 pages
Modelsim Pele User
No ratings yet
Modelsim Pele User
706 pages
IBM AIX Enhancements: and Modernization
No ratings yet
IBM AIX Enhancements: and Modernization
188 pages
Eio0000002168 04
No ratings yet
Eio0000002168 04
418 pages
Modelsim Reference Manual: Software Version 6.3G May 2008
No ratings yet
Modelsim Reference Manual: Software Version 6.3G May 2008
346 pages
Twido Programmable Controllers: Software Reference Guide
No ratings yet
Twido Programmable Controllers: Software Reference Guide
636 pages
Twido Programming Guide
No ratings yet
Twido Programming Guide
604 pages
Modelsim CMD Reference
No ratings yet
Modelsim CMD Reference
453 pages
C Taw12
100% (2)
C Taw12
39 pages
Modelsim User
No ratings yet
Modelsim User
854 pages
Isense iXMedia User Rev 9A
No ratings yet
Isense iXMedia User Rev 9A
140 pages
Interview Questions Consolidated Mainframe
100% (1)
Interview Questions Consolidated Mainframe
8 pages
EMV Overview Tecnica
No ratings yet
EMV Overview Tecnica
14 pages
DOC00310 Verix EVo ACT Programmers Guide
75% (4)
DOC00310 Verix EVo ACT Programmers Guide
348 pages
Programming Guide
No ratings yet
Programming Guide
316 pages
User and Best Practices Guide: Downloaded From Manuals Search Engine
No ratings yet
User and Best Practices Guide: Downloaded From Manuals Search Engine
78 pages
Communicationlibrary PDF
100% (1)
Communicationlibrary PDF
282 pages
Mptmon
No ratings yet
Mptmon
212 pages
Seminar MWC Visa Token Service
No ratings yet
Seminar MWC Visa Token Service
11 pages
PL7 Standard Applications
No ratings yet
PL7 Standard Applications
410 pages
C-1 Kernel 1 v2.6 20160512101416661
No ratings yet
C-1 Kernel 1 v2.6 20160512101416661
34 pages
840USE50500
No ratings yet
840USE50500
120 pages
Pimpmykali SH
No ratings yet
Pimpmykali SH
20 pages
CS401 Computer Architecture and Assembly Language Programming
No ratings yet
CS401 Computer Architecture and Assembly Language Programming
3 pages
Intro To OOP Using C++
No ratings yet
Intro To OOP Using C++
86 pages
Soft Error Mitigation Controller v4.1
No ratings yet
Soft Error Mitigation Controller v4.1
125 pages
Dukpt Explained
100% (1)
Dukpt Explained
42 pages
PLC Concept Software 2.6 User Manual Vol 3
No ratings yet
PLC Concept Software 2.6 User Manual Vol 3
350 pages
Cfe Usersguide
No ratings yet
Cfe Usersguide
1,195 pages
Computer Practical File C++
No ratings yet
Computer Practical File C++
46 pages
VSE OPC UA Server VOS050: Software Manual
No ratings yet
VSE OPC UA Server VOS050: Software Manual
39 pages
CO - PCA - 2 - Report Painter & Allocations
No ratings yet
CO - PCA - 2 - Report Painter & Allocations
395 pages
OS Lecture Notes 3-5
No ratings yet
OS Lecture Notes 3-5
67 pages
IDA Pro 5.0: Introduction of A Graph Based Used Interface. The Text Interface Remains Instantly Available
No ratings yet
IDA Pro 5.0: Introduction of A Graph Based Used Interface. The Text Interface Remains Instantly Available
6 pages
Oracle 1Z0-808 (12) 53423z42
No ratings yet
Oracle 1Z0-808 (12) 53423z42
109 pages
genmed-DDS - Drive PLC Developer Studio IEC61131 3 Programming - v2 0 - EN
No ratings yet
genmed-DDS - Drive PLC Developer Studio IEC61131 3 Programming - v2 0 - EN
26 pages
Processor Architecture
No ratings yet
Processor Architecture
25 pages
Java Swing Front End: Minor Project Report
No ratings yet
Java Swing Front End: Minor Project Report
20 pages
Cse420 Lab 1
No ratings yet
Cse420 Lab 1
4 pages
LG l1753,1953s-sfq
No ratings yet
LG l1753,1953s-sfq
35 pages
West Bengal State University: Omputer Cience Onours
No ratings yet
West Bengal State University: Omputer Cience Onours
2 pages
A New Approach To Sorting Min Max Sorting Algorithm IJERTV2IS50210 PDF
No ratings yet
A New Approach To Sorting Min Max Sorting Algorithm IJERTV2IS50210 PDF
4 pages
Kernel Programming Master Class
No ratings yet
Kernel Programming Master Class
4 pages
Modelsim Ref
No ratings yet
Modelsim Ref
542 pages
Handson Lab JavaScript Browser Console Edx
No ratings yet
Handson Lab JavaScript Browser Console Edx
8 pages
Chapter#4 ObjectModeling
No ratings yet
Chapter#4 ObjectModeling
23 pages
Android Programming - Lecture 2
No ratings yet
Android Programming - Lecture 2
14 pages
Servlet AJP Assignment Unit 6
No ratings yet
Servlet AJP Assignment Unit 6
4 pages
App Dev Guide
No ratings yet
App Dev Guide
354 pages
CoreABC HB
No ratings yet
CoreABC HB
85 pages
Eetop - CN valusUG
No ratings yet
Eetop - CN valusUG
216 pages
Cia Java
No ratings yet
Cia Java
10 pages
Pip QP
No ratings yet
Pip QP
35 pages
F
No ratings yet
F
28 pages
Computer Studies Syllabus Grades 10 To 12
No ratings yet
Computer Studies Syllabus Grades 10 To 12
41 pages
Ads La5 - Avl Tree Insertion
No ratings yet
Ads La5 - Avl Tree Insertion
7 pages
Fcug
No ratings yet
Fcug
101 pages
Matlab Tutorial 2023
No ratings yet
Matlab Tutorial 2023
11 pages
AlgoPrep's 151 Problems Sheet
No ratings yet
AlgoPrep's 151 Problems Sheet
3 pages
Quest A Verification Ip Data Book
No ratings yet
Quest A Verification Ip Data Book
186 pages
OICore
No ratings yet
OICore
122 pages
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
From Everand
The Linux Terminal for Advanced Users - The Command Line Made Easy: First Edition
Michael Basler
No ratings yet
Content Creation Revolution with chatGPT
From Everand
Content Creation Revolution with chatGPT
Maria Cowen
No ratings yet
Plain JavaScript: Learning the Front-End
From Everand
Plain JavaScript: Learning the Front-End
Roger Beans-Rivet
No ratings yet
ChatGPT for Business: Strategies for Success
From Everand
ChatGPT for Business: Strategies for Success
Matthew C. Smith
No ratings yet
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
From Everand
Securing ChatGPT: Best Practices for Protecting Sensitive Data in AI Language Models
Matthew C. Smith
No ratings yet
Gray Hat Hacking the Ethical Hacker's
From Everand
Gray Hat Hacking the Ethical Hacker's
Çağatay Şanlı
5/5 (1)
Software Patterns Made Easy
From Everand
Software Patterns Made Easy
Justice Nanhou
No ratings yet