0. Common

0.1. There is a library CScLink.dll provides you accesss to PersonalCards system DB.

Sometimes companies, which are using UCS Personal Discount System (PDS), want to have access to the Card server. The reasons might be different: create web page, where customers can check their balances, make possibility to check balance by sending SMS and etc.

In such cases UCS provides a DLL, which allows external systems to connect to card server.

It means that external software developers should invoke functions from that DLL.

The name of DLL - CscLink.dll. This manual is about ver. 1.24 and newer.

Current CScLink version is 1.27, minimum cardserv is 7.17.

CscInt.pas file contains functions for current version.

1. Basic

1.1. Scheme of connection

1.2. Functions

1.2.1. Import module CscLink.DLL. If the result of functions executions is negative, you can get error text by function GetErrorText: PChar;

unit CscInt;
1.2.1.1.
interface
1.2.1.2.
uses Windows;

1.2.2. To get error happened, last one

Function GetErrorText: PChar; stdcall;

1.2.3. get version of CscLink.dll
Function Version: PChar; stdcall;

1.2.4. Get protocol version

Function GetProtocol( var Protocol: Word ): BOOL; stdcall;

1.2.5. start and connect

Function Login( AUser, APsw: PChar ): BOOL; stdcall;

1.2.6.0. type  {information about card to use on cash station}
  TCardUseInfo = packed record
    Size       : Word;    // Size of TCardUseInfo - fill in before calling
    Account    : Integer; // account number
    Holder     : Array[0..40] of Char; // Full name
    Active     : BOOL;    // Is card active?
    WithMngr   : BOOL;    // use with manager confirmation?
    Expired    : BOOL;    // validity expired?
    Locked     : BOOL;    // Is card locked?
    Seize      : BOOL;    // seize card?
    WhyLocked  : Array[0..255] of Char; // Lock reason - asciiz
    Unpay      : Integer; // Unpayer type
    Discount   : Word;    // discount number
    Bonus      : Word;    // bonus number
    CanPay     : Comp;    // how much money  can be drawn out from the card now
    DiscLimit  : Comp;    // discount sum  limit
    Sum1       : Comp;    // balance on account
    Sum2       : Comp;    // balance on account 2 (for Farcards)
    Sum3       : Comp;    // balance on account 3 (for Farcards)
    Sum4       : Comp;    // balance on account 4 (for Farcards)
    Sum5       : Comp;    // balance on account 5 (for Farcards)
  end;

1.2.6. {get information about card to use on cash station}
Function GetCardUseInfo( Card: Int64; RestCode, UnitNo: Integer; var Info: TCardUseInfo ): BOOL; stdcall;

/expired/? type
  TCardInfo = packed record
    Size       : Word;    //Size of TCardInfo - to fill in before a call
    Holder     : Array[0..40] of Char; // owner of a card - asciiz
    Deleted    : BOOL;    //is card deleted?
    Action     : BOOL;    //is card valid now?
    Discount   : Word;    //type of discount
    Rest       : Comp;    //sum of residue in kopecks(Int64)
    Bonus      : Word;    //bonus type
    CanPay     : Comp;    //card balance

/expired/?  {to get basic information on a card}
Function GetCardInfo( Card: Integer; var Info: TCardInfo ): BOOL; stdcall;
type
  TTransInfo = packed record
    Size     : Word;    //Size of TTransInfo - to fill in before a call
    Kind     : Word;    //0-payment 1-discount
    Summa    : Comp;    {sum in cents;
                         for Transaction()
                           positive numeral - common action;
                           negative numeral - return
                         for GetCardOpers() and GetRkTrans() - vice versa
                        }
    //information of check  - optional
    Office   : Word;    //code of restaurant
    LogDate  : Longint; //date of check (0 -> 30/12/1899)
    UnitNum  : Byte;    //cash register number
    CheckNo  : Word;    //check number
  end;

1.2.7. {get image linked to acount unpacked}
Function GetAccountImageE( Account: Integer; Proc: TFWrite ): BOOL; stdcall;

1.2.8. get account number by card number
Function GetAccountNumber( Card: Int64; var Account: Integer ): BOOL; stdcall;

1.2.9. {get specified message to the account}
Function GetAccountMessage( Account: Integer; var Msg: PChar ): BOOL; stdcall;

1.2.10. {set message to the account}
Function SetAccountMessage( Account: Integer; const Msg: PChar ): BOOL; stdcall;

1.2.11.0. type  {procedure of call back for information record received from the server}
  TFWrite = Procedure( Data: Pointer; Size: Integer ); stdcall;

1.2.11. {get specified image to the account}
Function GetAccountImage( Account: Integer; Proc: TFWrite ): BOOL; stdcall;

1.2.12.0. type  {account information}
  TAccountInfo = packed record
    Size      : Word;    // SizeOf( TAccountInfo )
    Account   : Integer; // account number
    Card      : Int64;   // card number
    Holder    : Array[0..40] of Char; //Full name
    Scheme    : Byte;    {account type:
                          0 - manual recharge without payment limit
                          1 - automatic recharge without payment limit
                          2 - automatic recharge with payment limit for one day
                          3 - automatic recharge with payment limit for a week
                          4 - automatic recharge with payment limit for a month
                          5 - manual recharge with payment limit for one dayа
                          6 - manual recharge with payment limit for a week
                          7 - manual recharge with payment limit for a month
                          }
    Offered   : Integer; // date of issue (0 -> 30/12/1899)
{*} Expired   : Integer; // validity
{*} Birthday  : Integer; // birthday
    Deleted   : BOOL;    // account deleted?
{*} Locked    : BOOL;    // card locked?
{*} Seize     : BOOL;    // seize card?
{*} WhyLocked : Array[0..255] of Char; // причина блокировки - asciiz
    Discount  : Word;    // discount number
{*} Bonus     : Word;    // bonus number
    PayLimit  : Comp;    // limit of payments for accounts with limit
{*} Female    : BOOL;    // sex
    Folder    : Word;    // division identifier
    Unpay     : Integer; // unpayer number
{*} Tel1      : Array[0..15] of Char; //phone 1
{*} Tel2      : Array[0..15] of Char; //phone 2
{*} Email     : Array[0..255] of Char;
{*} Address   : Array[0..255] of Char;
{*} DopInfo   : Array[0..255] of Char; //random information - asciiz
    Balance   : Comp;    // for cards with manual recharge - current balance
  end;

1.2.12. {get account information}
Function GetAccountInfo( Account: Integer; var Info: TAccountInfo ): BOOL; stdcall;

1.2.13. {Change account features. Features marked with sign (*) are changed. Before calling at first fill in Info by calling GetAccountInfo()}
Function SetAccountInfo( const Info: TAccountInfo ): BOOL; stdcall;

1.2.14.0. type
  TTransactionInfo = packed record
    Size      : Word;    // Size of TTransactionInfo - fill in before calling
    Kind      : Word;    // 0-payment 1-discount 2-bonus 3-guest's expenses
    Summa     : Comp;    // Sum in copecks
    RestCode  : Word;    // restaurant code
    LogDate   : Integer; // check date (0 -> 30/12/1899)
    UnitNum   : Byte;    // Cash number
    CheckNo   : Integer; // Check number
    Comment   : Array[0..255] of Char; //comment - for manual transactions
  end;

1.2.14. {make cash transaction. Summa > 0 - direct action, Summa < 0 - cancel}
Function CashTransaction( Account: Integer; const Info: TTransactionInfo ): BOOL; stdcall;

1.2.15. {money deposit to account if sum is negative - money seize}
Function HandTransaction( Account: Integer; Sum: Comp; Comment: PChar ): BOOL; stdcall;

1.2.16.0. type  {procedure of call back for account transfer}
  TEnumAccounts = Procedure( const Info: TAccountInfo ); stdcall;

1.2.16. {return of all accounts}
Function GetAllAccounts( Proc: TEnumAccounts ): BOOL; stdcall;

1.2.17.0. type   {procedure of call back for folders transfer}

 TEnumFolders = Procedure( Id, ParentId: Integer; Deleted: Boolean; Name: PChar ); stdcall;

1.2.17. {return of all folders}
Function GetAllFolders( Proc: TEnumFolders ): BOOL; stdcall;

1.2.18.0. type  {Procedure of call back for transfer of found cards.    Reference Holder is lost after exit from the procedure!}
  TEnumFindAccounts = Procedure( Account: Integer; Card: Int64; Holder: PChar ); stdcall;

1.2.18. {search of cards and holders by mask, search results return through procedure Proc}
Function FindAccounts( Mask: PChar; Proc: TEnumFindAccounts ): BOOL; stdcall;

1.2.19.0. type  {procedure of call back for transfer of transactions}
  TEnumTransactions = Procedure( Account: Integer; When: TDateTime; const Info: TTransactionInfo ); stdcall;

1.2.19. {transfer of transactions by account, results return through procedure Proc}
Function GetAccountTransactions( Account: Integer; DateFirst, DateLast: TDateTime; Proc: TEnumTransactions ): BOOL; stdcall;

1.2.20. {transfer of all transactions, results return through procedure Proc}
Function GetAllTransactions( DateFirst, DateLast: TDateTime; Proc: TEnumTransactions ): BOOL; stdcall;

1.2.21.0. type  {procedure of call back for transfer of discount changes and bonus of the card   according to its current schedule}
  TEnumDBVar = Procedure( Start: TDateTime; Disc, Bonus: Integer ); stdcall;

1.2.21. {transfer of card discount and bonus changes according to its current schedule. search results return through procedure Proc}
Function GetHistL( Card: Int64; Start, Stop: TDateTime; Proc: TEnumDBVar ): BOOL; stdcall;

1.2.22. {disconnection from server}
Procedure Done;

1.3. implementation

1.3.1.
const DllName = 'CscLink.DLL';
Function Version; external DllName;
Function GetProtocol; external DllName;
Function Login; external DllName;
Function GetErrorText; external DllName;
Function GetCardUseInfo; external DllName;
Function GetAccountNumber; external DllName;
Function GetAccountMessage; external DllName;
Function SetAccountMessage; external DllName;
Function GetAccountImage; external DllName;
Function GetAccountImageE; external DllName;
Function GetAccountInfo; external DllName;
Function SetAccountInfo; external DllName;
Function CashTransaction; external DllName;
Function HandTransaction; external DllName;
Function GetAllFolders; external DllName;
Function FindAccounts; external DllName;
Function GetAllAccounts; external DllName;
Function GetHistL; external DllName;
Function GetAccountTransactions; external DllName;
Function GetAllTransactions; external DllName;
Procedure Done; external DllName;
end.

2. Installation

2.1. Copy CscLink.dll and CscLink.Ini to the folder with CardServ.exe (or any other location, but make sure that CscLink can access files RTCP.DLL, RNETBIOS.DLL, RLOCAL.DLL)
2. Set in CscLink.ini:

3. Link with R-Keeper 7

3.1. This link is used, in particular, for cube [All] - [Receipt payments] - [Payment cards].

3.2. You need to connect report server to cardserv (PDS - CardServ.exe).

3.3. Download CSCLINK from UCS FTP (ftp://ftp.ucs.ru/r-keeper/versions/PERSCARD/CSCLINK/cscl127.7z)

3.3.1. Extract files in report server folder. Create text ini file.

3.3.2. Set 'csclink.ini' sections as follows (DLL anme, gate number, client name, server address and port):

3.4. Config RK7 PDS interface (logical) in manager:

3.4.1.specify ini file name CscLink.ini;

3.4.2. specify login name (set in cardserv DB) for user who has right there to view card list

3.4.3. specify password of that user

3.5. add network module to folder. in case you set as above: RTCP, put Rtcp.dll to the same folder with CscLink.ini;

3.6. You must also set currency in RK7 manager (pay card, if not yet) and link to mentioned interface

3.7. Restart report server.

3.8. Use like:

3.8.1. pay order with that currency.

3.8.2. recalculate cube "Payment cards".