VingCard Vision 3.

3B
B

Appendix C
PMS Integration

Contents of this chapter

INTRODUCTION ..................................................................................................................................2
OVERVIEW OF VISION PMS INTEGRATION...............................................................................2
INTERFACE TO VISION MODULE..................................................................................................2
VISION MAIN MODULE..........................................................................................................................2
INTERFACE TO GUEST KEYCARD SERVICES ...........................................................................3
OVERVIEW ............................................................................................................................................3
MODES OF OPERATION ..........................................................................................................................3
LIBRARY FUNCTIONS .............................................................................................................................4
HOW TO USE THE PMS INTERFACE LIBRARY .......................................................................................12

Appendix C: PMS Integration

Page 1

VingCard Vision 3.1

Introduction
There are three ways to connect the PMS and Vision:

RS232 connection (see Appendix A)

TCP/IP connection (see Appendix B)

Direct Integration on the VingCard Vision server, via DLL calls (see this Appendix)

Overview of Vision PMS Integration

This document describes the Vision PMS integration. It is a guide to the issuing of guest keycards
from the PMS system using a direct programmatic interface on the Vision server.

NOTE: This guide is meant as a technical description for software

developers who are familiar with Delphi and the Object Pascal
language. Readers should also be familiar with library calls
(DLLs) and using different calling conventions.

Interface to Vision Module

For successful integration, Vision must be properly and fully installed. See Chapter 1.
This section describes how to integrate the Vision system into the PMS system.
The Vision main module can be integrated at different places in the PMS system. The PMS system can
execute the Vision from a menu or a button, and also request Guest Keycard services during check-in,
pre-check-in, etc.

Vision Main Module

The Vision main module should be integrated in the main menu of PMS. It should have its own button
with a proper graphic art or icon supplied by VingCard.

NOTE: This module is not a library, but a regular Win32 executable.

When a workstation is installed with both Vision and the PMS program, the workstation could be set
up so that the Vision main module starts up automatically when the PC is turned on. By issuing the
/MIN parameter to Vision, it runs in minimized mode, and will not disturb the visual appearance of the
calling program.
An easy way to enter the Vision system from the PMS main menu is to just restore it from its
minimized state, and bring it to front when the user presses the Vision button.

Appendix C: PMS Integration

Page 2

VingCard Vision 3.1

When the user leaves Vision, it will return to its minimized state, and give focus back to the PMS
system.
The PMS main menu could implement these Win32 API calls to handle it:
// Delphi Code to bring the Vision application in front
var
Wnd: HWnd;
begin
Wnd := FindWindow('TApplication', 'Vision');
if Wnd <> 0 then
SendMessage(Wnd, WM_SYSCOMMAND, SC_RESTORE, 0);
end;
// Delphi Code to minimize the Vision application
var
Wnd: HWnd;
begin
Wnd := FindWindow('TApplication', 'Vision');
if Wnd <> 0 then
SendMessage(Wnd, WM_SYSCOMMAND, SC_MINIMIZE, 0);
end;

Interface to Guest Keycard Services

Vision offers an interface to encode Guest keycards from PMS systems. The interface is implemented
as a Windows9x/NT 32 bit DLL. The RS232 Vision/PMS connection uses the PMSIF.DLL, while the
TCP/IP connection uses the TCPPMSIF.DLL. The TCPPMSIF is an interface module much like the
PMSIF, bur slightly improved. This section describes the practical use of the library against
applications that want to interface to the Vision system.
This section outlines how the PMS interacts with the Vision system and how to call the library
functions to make Guest Keycards.
The library allows the PMS system to encode keycards on the same workstation that the Vision
software and the PMS software are running on.
The library permits the PMS system to encode keycards on any remote Vision station as long as the
basic Vision modules are installed on the same station as the PMS software.

Overview
In order to use the PMSIF.DLL/TCPPMSIF.DLL all Vision modules must to be properly installed
through the regular installation application, shipped with Vision. The Vision installation will require a
proper license code, which gives authorization to use the library.
The library requires that the main Vision application be running. The Vision main application loads all
other necessary modules needed to make Guest keycards.
The Vision main module executable can be started with a /MIN parameter, to tell it to operate in
minimized mode.

Modes of operation
The Vision system has four modes of operation when Guest keycards are made using the
PMSIF.DLL/TCPPMSIF.DLL library. The modes are set in the Vision setup module and stored in
the Vision database.

Appendix C: PMS Integration

Page 3

VingCard Vision 3.1

Mode

Description

Silent

Vision only displays the VingCard logo when encoding starts. When the card is
encoded the logo goes away.

Windows

Vision displays a standard Windows dialog with the same information as the
Touch screen mode.

Touch screen

Vision displays a touch screen message with room number and the number of
cards it encodes. The user can abort encoding by an abort button. When the card
is encoded the message goes away.

Full Vision

The Vision Guest keycard application uses the PMS input as default values and
runs a normal stand-alone full screen application. The user can enter and change
values as required.

Library functions
The PMSIF.DLL/TCPPMSIF.DLL interface library contains 11 functions/procedures to control the
keycard issuing and related topics from the PMS application.
The caller should use the stdcall calling convention when importing functions. This convention
passes parameters from right to the left, and the function removes parameters from the stack upon
returning.
PMSIF.DLL/TCPPMSIF.DLL library functions
Function Name

Description

PMSifRegister

Registers the application to the Vision system

PMSifUnregister

Unregisters the application

PMSifEncodeKcdLcl

Encodes the keycards on an encoder attached to the workstation

where the DLL and PMS runs

PMSifEncodeKcdRmt

Encodes the keycards on an encoder connected to the remote

workstation

PMSifReturnKcdLcl

Returns the bit pattern for a keycard

PMSifGetUserGroups

Returns a list of valid User Groups for guest keycards

PMSifGetDefUserGroup

Returns a name of default User Group for guest keycards

PMSifGetKeycardTypes

Returns a list of valid Keycard Types for guest keycards

PMSifGetDefKeycardType Returns a name of default Keycard Type for guest keycards

PMSifGetAddress

Returns a PMS address (00-99) for a workstation name

PMSifShutdownVision

Shuts down the Vision program

PMSifRegister
Syntax-VB:
Syntax-Delphi:

Declare Function PMSifRegister(ByVal szLicense As

String, ByVal szApplName AsString) As Integer
function PMSifRegister(szLicense, szApplName: PChar):
Integer;

Appendix C: PMS Integration

Page 4

VingCard Vision 3.1

Arguments:

<szLicense> points to a null-terminated string

containing the license/access code which gives
authorization to use the library
<szApplName> points to a null-terminated string
containing the name of the application that uses the
library; the name must be unique for the workstation

Returns:
Description:

0 for success, 1 for failure

This function registers the application to the Vision messaging system for
the required service. The messaging system controls the communication
further to the Guest keycard module.
Call it once to initialize the library, typically when the PMS system starts
up. A return value of zero indicates success, while non-zero indicates
failure.
Needs to be called before any other library calls can be made. The function
will fail if the Vision main module is not running.

PMSifUnregister
Syntax-VB:
Syntax-Delphi:
Returns:
Description:

Declare Function PMSifUnregister() As Integer

function PMSifRegister: Integer;

0 for success, 1 for failure

This function unregisters the application previously initialized with the
PMSifRegister function. Call it once when Guest keycard services are
no longer required. A return value of zero indicates success, while one
indicates failure.
No calls can be made after a call to this routine except for
PMSifRegister.

Appendix C: PMS Integration

Page 5

VingCard Vision 3.1

PMSifEncodeKcdLcl
Syntax-VB:

Declare Sub PMSifEncodeKcdLcl(ByRef ff As Byte, ByVal

Dta As String, ByVal Dbg As Boolean, ByVal szOpID As
String, ByVal szOpFirst As String, ByVal szOpLast As
String)

Syntax-Delphi:

procedure PMSifEncodeKcdLcl(var ff: Char; Dta: PChar;

Dbg: Boolean; szOpID, szOpFirst, szOpLast: PChar);

Arguments:

<ff> command, answer code (on return)

<Dta> points to a null-terminated string containing
data necessary to encode Guest keycards. The string
contains fields described by their field identifier.
The caller is responsible to allocate enough memory to
hold the entire string
<Dbg> a boolean flag, indicating if the library should
display a debug screen while encoding; pass TRUE to
show debug info, FALSE if not
<szOpID> points to a null-terminated string containing
the operator identification
<szOpFirst> points to a null-terminated string
containing the operator first name
<szOpLast> points to a null-terminated string
containing the operator last name / family name

Description:

This procedure is used to encode keycards on an encoder attached to the

workstation where the DLL (and PMS) runs.
For both the ff and Dta parameter see section 7.3.3 in the Vision
System Handbook, describing the interface protocol.
Important: if the command is VerifyCard [E], then the data buffer
pointed by Dta argument must be big enough to store all the information
as interpreted from the card, including field separators and their
identifiers; it is recommended to declare it as at least 700 bytes memory
block

Appendix C: PMS Integration

Page 6

VingCard Vision 3.1

PMSifEncodeKcdRmt
Syntax-VB:

Syntax-Delphi:

Arguments:

Declare Sub PMSifEncodeKcdRmt(ByRef ff As Byte, ByVal

Dta As String, ByVal dd As String, ByVal ss As String,
ByVal Dbg As Boolean, ByVal szOpID As String, ByVal
szOpFirst As String, ByVal szOpLast As String)
procedure PMSifEncodeKcdRmt(var ff: Char; Dta: PChar;
dd, ss: PChar; Dbg: Boolean; szOpID, szOpFirst,
szOpLast: PChar);
<ff> command, answer code (on return)
<Dta> points to a null-terminated string containing
data necessary to encode guest keycards. The string
contains fields described by their field identifier.
The caller is responsible to allocate enough memory to
hold the entire string
<dd> destination address field
<ss> source address field
<Dbg> a boolean flag, indicating if the library should
display a debug screen while encoding; pass TRUE to
show debug info, FALSE if not
<szOpID> points to a null-terminated string containing
the operator identification
<szOpFirst> points to a null-terminated string
containing the operator first name
<szOpLast> points to a null-terminated string
containing the operator last name / family name

Description:

This procedure is used to encode keycards on an encoder connected to a

remote workstation.
For both the ff and Dta parameter see section 7.3.3 in the Vision System
Handbook, describing the interface protocol. The function will fail if the
Vision main module is not running on the destination workstation

Appendix C: PMS Integration

Page 7

VingCard Vision 3.1

PMSifReturnKcdLcl
Syntax-VB:

Syntax-Delphi:

Arguments:

Declare Function PMSifReturnKcdLcl(ByRef ff As Byte,

ByVal Dta As String, ByVal Dbg As Boolean, ByVal szOpID
As String, ByVal szOpFirst As String, ByVal szOpLast As
String) As String
function PMSifReturnKcdLcl(var ff: Char; Dta: PChar;
Dbg: Boolean; szOpID, szOpFirst, szOpLast: PChar):
PChar;
<ff> command, answer code (on return)
<Dta> points to a null-terminated string containing
data necessary to encode Guest keycards. The string
contains fields described by their field identifier.
Remember that this data will be then overwritten by
returned key bitmap string and must be big enough to
hold entire string (at least 268 bytes)
<Dbg> a boolean flag, indicating if the library should
display a debug screen while encoding; pass TRUE to
show debug info, FALSE if not
<szOpID> points to a null-terminated string containing
the operator identification
<szOpFirst> points to a null-terminated string
containing the operator first name
<szOpLast> points to a null-terminated string
containing the operator last name / family name

Returns:
Description:

pointer to the string with key bitmap

This function is used to return the keycode to encode, instead of being
encoded on a keycard. The function operates locally on the workstation
where the DLL (and PMS) runs. The keycode returned from the function
result contains character 1 and 0, each representing one bit on the
keycard.
Format of the data returned in <Dta> buffer follows the interface protocol,
so the first byte is a <RS> - record separator, then ASCII 3 and than the
stream of ASCII 1 and 0 representing individual bits on card. The
leading and trailing 0 bits (clocking bits) are not included.
For both the ff and Dta parameter see section 7.3.3 in the Vision System
Handbook, describing the interface protocol

Appendix C: PMS Integration

Page 8

VingCard Vision 3.1

PMSifGetUserGroups
Syntax-VB:
Syntax-Delphi:
Arguments:

Declare Function PMSifGetUserGroups(ByVal Dta As

String, ByRef nCount As Integer) As String
function PMSifGetUserGroups(Dta: PChar; var nCount:
Integer): PChar;
<Dta> points to a null-terminated string buffer to hold
the returned list of User Groups
<nCount> an integer containing the size of needed
buffer

Returns:
Description:

pointer to the string with list of User Groups

This function returns a list of valid guest User Groups as defined in the
Vision database. Each User Group in the returned character buffer is
separated by CR/LF.
Call once with Dta = nil to retrieve the size of the buffer needed to
hold the list of User Groups in nCount. Call once more with a valid
character pointer in Dta. The final character buffer pointer is both
returned in Dta and the function result itself.

PMSifGetDefUserGroup
Syntax-VB:
Syntax-Delphi:
Arguments:
Returns:
Description:

Declare Function PMSifGetDefUserGroup(ByVal Dta As

String) As String
function PMSifGetDefUserGroup(Dta: PChar): PChar;
<Dta> points to a null terminated string buffer to hold
the returned User Group name

pointer to the string with default User Group

This function returns the default Guest User Group as defined in the
Vision database.
The caller is responsible of allocating at least 16 bytes of buffer space + 1.
16 bytes represent the name space size in the Vision database.

Appendix C: PMS Integration

Page 9

VingCard Vision 3.1

PMSifGetKeycardTypes
Syntax-VB:
Syntax-Delphi:
Arguments:

Declare Function PMSifGetKeycardTypes(ByVal Dta As

String, ByRef nCount As Integer) As String
function PMSifGetKeycardTypes (Dta: PChar; var nCount:
Integer): PChar;
<Dta> points to a null-terminated string buffer to hold
the returned list of Keycard Types
<nCount> an integer containing the size of needed
buffer

Returns:
Description:

pointer to the string with list of Keycard Types

This function returns a list of valid guest Keycard Types as defined in the
Vision database. Each Keycard Type in the returned character buffer is
separated by CR/LF.
Call once with Dta = nil to retrieve the size of the buffer needed to
hold the list of Keycard Types in nCount. Call once more with a valid
character pointer in Dta. The final character buffer pointer is both
returned in Dta and the function result itself.

PMSifGetDefKeycardType
Syntax-VB:
Syntax-Delphi:
Arguments:
Returns:
Description:

Declare Function PMSifGetDefKeycardType(ByVal Dta As

String) As String
function PMSifGetDefKeycardType(Dta: PChar): PChar;
<Dta> points to a null terminated string buffer to hold
the returned Keycard Type name

pointer to the string with default Keycard Type

This function returns the default Keycard Type for guest keycards as
defined in the Vision database.
The caller is responsible of allocating at least 16 bytes of buffer space + 1.
16 bytes represent the name space size in the Vision database.

Appendix C: PMS Integration

Page 10

VingCard Vision 3.1

PMSifGetAddress
Syntax-VB:
Syntax-Delphi:
Returns:
Arguments:

Declare Function PMSifGetAddress(ByVal Dta As String,

ByVal szWorkstation As String) As String
function PMSifGetAddress(Dta, szWorkstation: PChar):
PChar;

pointer to the string with PMS address

<Dta> points to a null terminated string buffer to hold
the returned PMS address
<szWorkstation> points to a null terminated string
containing a valid workstation name

Description:

This function returns the PMS address (00-99) for a workstation name.
Use this function with PMSifEncodeKcdRmt, if the Vision PMS
address mapping is unknown.
The caller is responsible of allocating at least 2 bytes of buffer space + 1.

PMSifShutdownVision
Syntax-VB:
Syntax-Delphi:
Returns:
Description:

Declare Function PMSifShutdownVision() As Boolean

function PMSifShutdownVision: Boolean;

TRUE for success, FALSE for failure

This function notifies the running Vision main module to shut itself down.
The function returns a boolean value of TRUE indicating successful
shutdown, else it returns FALSE.
After a successful shutdown, the Vision messaging system and the other
modules, needed to make Guest keycards are closed. Therefor to be able to
make Guest keycards again, Vision has to be reloaded, and the PMS must
re-register with the library.

Appendix C: PMS Integration

Page 11

VingCard Vision 3.1

How to use the PMS interface library

Precautions
It is important that Vision software is running on all stations where cards are to be encoded. The
Vision database must be set up with the correct PMS address schema.
When calling PMSIF.DLL/TCPPMSIF.DLL, only one command can be issued at a time. If
commands to several stations need to be issued before the result from the first is received, it is
possible to achieve this by multithreading the PMS Host software. If such an approach is
chosen, every thread has to register to the DLL using different names.
If the same name is chosen for different threads, only the last thread started will be able to
communicate. The only restriction on the registering name is that it needs to be a character
string, where the first 20 characters are significant.

Example (in Object Pascal of Delphi)

NOTE: Please translate the example into your preferred language.
Programming examples in C++ or Visual Basic and other
examples in Delphi are available from VingCard.
The application needs to register to the library. By registering, a message is sent to the Vision
messaging system to inform that a new application is online. It is necessary to do this
registration to be able to communicate with the rest of the Vision system, both locally and
externally. To successfully register you also need to provide the function with a valid license
key.
IResult := PMSifRegister('1234567890', 'MyPmsApp');
When creating Keycards on the local Workstation, you need provide the function with a
command (for details see section 7.3.3 in the Vision System Handbook):
ff := 'I';

//CheckOutOldCheckInNew

Then the encoding input data:

chDta = chr(ASCII_RS) + 'R201'
+ chr(ASCII_RS) + 'Tguest'
+ chr(ASCII_RS) + 'D199904031000'
+ chr(ASCII_RS) + 'O199904151000'
+ chr(ASCII_RS) + 'UVIP'
+ chr(ASCII_RS) + 'NJohn'
+ chr(ASCII_RS) + 'FDoe';

//Room Number
//Keycard Type = guest
//CheckIn Date yyyymmddhhmm
//CheckOut Date yyyymmddhhmm
//User Group = VIP
//First Name
//Family Name

Then the procedure call can be made with:

PMSifEncodeKcdLcl(ff, chDta, False, '1000', 'Randy', 'Smith');
And then when you dont need the Guest Keycard service anymore:
IResult := PMSifUnregister;
If you want to encode on track #2, specify the data according to ANSI/ISO standard with
regards to character set. Note that the start sentinel, end sentinel and checksum will be
automatically added by Vision software.

Appendix C: PMS Integration

Page 12

VingCard Vision 3.1

For example:
Account number 1112234567, Country 840(USA), Expiration date Dec. 94 Balance 8900
'11112234567=84094128900'
chDta = chDta + chr(ASCII_RS) + '2' +
'11112234567=84094128900';
//Track2 data
PMSifEncodeKcdLcl(ff, chDta, False, '1000', 'Randy', 'Smith');
When creating cards on a remote Vision station, it is necessary to include a destination and
source address. The destination address is a number between 0-99. The number for a specific
Vision station is defined in Vision setup:
PMSifEncodeKcdRmt(ff, chDta, '01', '02', False, '1000',
'Randy', 'Smith');
When creating both local and remote Keycards, you need to give a valid Keycard type and a
valid User group. These are lock terms in Vision. If these values are not available in the PMS
system, you can use one of the library functions to retrieve them.
See protocol parameter FID_USER_TYPE and FID_USER_GROUP in the Vision System
Handbook, and the following functions:
PMSifGetUserGroups
PMSifGetDefUserGroup
PMSifGetKeycardTypes
PMSifGetDefKeycardType
If you want to shut down the Vision system, for example when the PMS system shuts down,
you can solve this with a call to:
PMSifShutdownVision
Remember that the Guest Keycard service is not available after a successful call to this function.

Appendix C: PMS Integration

Page 13