Clarion IPDS Reference Guide

Transcription

Clarion IP Driver and Server Reference
2
IP Driver and Server Reference
© COPYRIGHT 2005 SoftVelocity Incorporated. All rights reserved.
This publication is protected by copyright and all rights are reserved by SoftVelocity Incorporated. It may not, in whole or
part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form
without prior consent, in writing, from SoftVelocity Incorporated.
This publication supports Clarion. It is possible that it may contain technical or typographical errors. SoftVelocity
Incorporated provides this publication “as is,” without warranty of any kind, either expressed or implied.
SoftVelocity Incorporated
2335 East Atlantic Blvd. Suite 410
Pompano Beach, Florida 33062
(954) 785-4555
www.softvelocity.com
Updated for Version 2.0
Trademark Acknowledgements:
SoftVelocity is a trademark of SoftVelocity Incorporated.
Clarion™ is a trademark of SoftVelocity Incorporated.
Microsoft®, Windows®, and Visual Basic® are registered trademarks of Microsoft Corporation.
All other products and company names are trademarks of their respective owners.
Printed in the United States of America (1005)
3
Contents:
IP Driver and Data Server - Overview
7
What’s New in Version 1.3/1.4
8
New Timeout setting on the server for sessions ........................................................................................................ 8
Forced disconnect on a new Remote Administrator session..................................................................................... 8
Guest User Administration ......................................................................................................................................... 8
Improved Connection Handling.................................................................................................................................. 8
What’s New in Version 2.0
9
Server Side VIEWS.................................................................................................................................................... 9
Multiple Request Packets........................................................................................................................................... 9
Template Support for Remote Variables.................................................................................................................... 9
New “From List” Connection Option........................................................................................................................... 9
Installation
10
Register the Driver and Templates .......................................................................................................................... 10
Install the Java runtime (1.4 or higher) .................................................................................................................... 11
Install Notes
12
Fast Start.................................................................................................................................................................. 12
Online Tutorials ........................................................................................................................................................ 12
Server Directory structure ........................................................................................................................................ 12
RMAdmin ........................................................................................................................................................... 12
SoftVelocity IP Data Server Service ........................................................................................................................ 12
IP Data Server Manager .......................................................................................................................................... 13
Architecture
15
How to IP-enable a FILE
15
An IP-enabled Application in 10 minutes (or less)
17
Summary: ................................................................................................................................................................. 22
A Multi-DLL example
23
IPS File Defined................................................................................................................................................. 23
IPC File Defined................................................................................................................................................. 24
Deployment Checklist
26
Server Security Settings........................................................................................................................................... 28
SSL Deployment Considerations ............................................................................................................................. 29
Optional Dictionary Settings
31
IP Driver Template Support
32
IP Server Template .................................................................................................................................................. 33
The IPS file ........................................................................................................................................................ 33
General tab ........................................................................................................................................................ 33
File Control tab .................................................................................................................................................. 34
IPServer Version................................................................................................................................................ 34
Data Manager DLL Wizard....................................................................................................................................... 35
IPDRV Extended Server Support Extensions .......................................................................................................... 38
Technical Notes ................................................................................................................................................. 38
IP Server Extension – IPDRV Extended ........................................................................................................... 39
IP Server Extension – Runtime Names............................................................................................................. 40
IP Server Extension – Server Variables ............................................................................................................ 40
IPEXEC Source Procedure Template...................................................................................................................... 41
IP Client Template.................................................................................................................................................... 42
The IPC File....................................................................................................................................................... 42
Select IPS File ................................................................................................................................................... 43
4
Connection Type................................................................................................................................................ 43
Extended Server Support Extensions – Client......................................................................................................... 47
IP Client Extension – General ........................................................................................................................... 47
IP Client Extension – Imported Procedures ...................................................................................................... 47
IP Client Extension – Remote Variables ........................................................................................................... 48
IPDriver Code Templates – Client Application......................................................................................................... 49
IPChangeFileName Code Template ................................................................................................................. 49
IPEXEC Code Template.................................................................................................................................... 50
IPTransferFileCode Code Template.................................................................................................................. 51
IPIsAlive Code Template ................................................................................................................................... 52
IPKeepAlive Code Template ............................................................................................................................. 53
IPSetRemoteVariable Code Template .............................................................................................................. 54
IPGetRemoteVariable Code Template.............................................................................................................. 54
IPTransferFile Control Template – Client Application.............................................................................................. 55
Extended Server Support Extensions Examples ..................................................................................................... 56
File Transfer....................................................................................................................................................... 56
Multidataset ....................................................................................................................................................... 56
Server-side Embeds and Procedures
57
GetFName (change the name of the data file or path)...................................................................................... 58
Program Setup access ...................................................................................................................................... 59
BeforeOpen (called prior to the server opening the file) ................................................................................... 59
Calling the Server-side Remote Procedure....................................................................................................... 60
IPDRV Extended Server Embeds ............................................................................................................................ 62
IPEXEC Dispatch Procedure............................................................................................................................. 62
IPSetFilename Procedure ................................................................................................................................. 63
IPGetFilename Procedure ................................................................................................................................. 63
Client-side Embeds and Procedures
64
File Transfer Embed Points...................................................................................................................................... 64
Advanced Server Support
65
Multiple Request Packet (MRP) support for ADD, APPEND, NEXT and PREVIOUS statements.......................... 65
MRP Property:.......................................................................................................................................................... 65
IPRequestCount ................................................................................................................................................ 65
FAQs ........................................................................................................................................................................ 67
Error Handling .......................................................................................................................................................... 67
MRP Conceptual Examples ..................................................................................................................................... 68
Example 1: How to create a packet with multiple ADD requests. ..................................................................... 68
Example 2. How to send a packet immediately................................................................................................. 68
Example 3. How to create a packet with an unknown number of requests....................................................... 68
Example 4. How to kill the current packet. ........................................................................................................ 69
Example 5. How to create a packet with multiple NEXT requests. ................................................................... 69
Example 6. How to create a packet with multiple PREVIOUS requests. .......................................................... 70
Example 7. How to kill a received packet.......................................................................................................... 70
Example 8. Adding NOMEMO support.............................................................................................................. 71
Server Side VIEW support ....................................................................................................................................... 72
Filtering Rules.................................................................................................................................................... 72
IP Driver Class Library Reference
73
Overview .................................................................................................................................................................. 73
IPFileTransfer and IPExtender Class Source Files ................................................................................................. 73
Template Support..................................................................................................................................................... 73
IPExtender methods:................................................................................................................................................ 74
SetConnectionString (set OWNER attribute of IP file) ...................................................................................... 74
GetConnectionString (get OWNER attribute of IP file)...................................................................................... 74
Exec(call a remote procedure) .......................................................................................................................... 75
SetFileName (change remote file name)........................................................................................................... 76
GetFilename (read remote file name)................................................................................................................ 76
SetRemoteVariable (change remote variable) .................................................................................................. 77
5
GetRemoteVariable (read remote variable) ...................................................................................................... 77
IsAlive (is the IP Server connection active?) ..................................................................................................... 78
CloseConnection (close internal Server connection) ........................................................................................ 78
SetKeepAlive (activate internal KeepAlive mode) ............................................................................................. 79
IPFileTransfer Methods............................................................................................................................................ 80
SetConnectionString (set OWNER attribute of IP file) ...................................................................................... 80
GetConnectionString (get OWNER attribute of IP file)...................................................................................... 80
SetSourceFileName(Set the source file name) ................................................................................................. 81
SetTargetFileName(Set the target file name).................................................................................................... 81
GetRemoteFileName(Get the Remote File Name) ........................................................................................... 81
SetControls(Set pause and progress controls) ................................................................................................. 81
Init(Initialize the class) ....................................................................................................................................... 82
SetSilent(set visible error message).................................................................................................................. 83
GetSilent(get the silent error state).................................................................................................................... 83
InitSend(begin the SEND process).................................................................................................................... 84
InitReceive(begin the RECEIVE process) ......................................................................................................... 85
TakeEvent(monitor transfer process) ................................................................................................................ 86
Start(transfer started) ........................................................................................................................................ 87
Pause(transfer paused) ..................................................................................................................................... 87
Cancel(transfer cancelled)................................................................................................................................. 87
Aborted(transfer aborted) .................................................................................................................................. 87
Finish(transfer finished) ..................................................................................................................................... 87
Send(begin internal SEND) ............................................................................................................................... 87
Receive(begin internal RECEIVE)..................................................................................................................... 87
GetErrorCode(get transfer errorcode) ............................................................................................................... 88
GetError(get transfer error)................................................................................................................................ 88
SetBuffersPerCycle (set buffers read per cycle) ............................................................................................... 88
GetBuffersPerCycle (get buffers read per cycle)............................................................................................... 88
SetTimer(set transfer interval) ........................................................................................................................... 89
GetTimer(get transfer Interval) .......................................................................................................................... 89
SetAllowPause(set transfer pause action) ........................................................................................................ 90
GetAllowPause(get transfer pause action)........................................................................................................ 90
GetAction(get the transfer action)...................................................................................................................... 90
SwapPauseText(transfer control text) ............................................................................................................... 91
StartTimer(transfer interval started)................................................................................................................... 91
StopTimer(transfer interval stopped) ................................................................................................................. 91
Error Codes and Error Trapping
92
Socket Errors ........................................................................................................................................................... 92
Common Errors........................................................................................................................................................ 93
Detecting an invalid connection to the IP Data Server ............................................................................................ 94
SoftVelocity IP Data Server Service
95
Server Ports ............................................................................................................................................................. 95
UNC support for the SoftVelocity IP Data Server Service ....................................................................................... 96
A note about Mapped Drives.................................................................................................................................... 96
Remote Administration Application (RMAdmin)
97
Main Menu ......................................................................................................................................................... 98
Toolbar............................................................................................................................................................... 99
Tree-View Pane ................................................................................................................................................. 99
Details View Pane............................................................................................................................................ 100
Sessions View ................................................................................................................................................. 100
Active Table View ............................................................................................................................................ 101
Table View ....................................................................................................................................................... 102
Account Administration View ........................................................................................................................... 103
Table Permissions (Access Rights)................................................................................................................. 104
IP Server Settings............................................................................................................................................ 105
Data Manager Aliases ..................................................................................................................................... 105
Status Bar Information..................................................................................................................................... 105
6
Connect to IP Server ....................................................................................................................................... 106
Possible Connection Errors ............................................................................................................................. 107
Stored configuration properties ....................................................................................................................... 107
IP Driver Specifications
108
Files: ................................................................................................................................................................ 108
Data Types and File Specifications ................................................................................................................. 108
Driver Strings ................................................................................................................................................... 109
Supported Commands and Attributes ............................................................................................................. 109
DEBUGVIEW Support
110
Advanced Deployment Tips
111
Clarion Runtime Files ...................................................................................................................................... 111
Location of Data Managers and Data Files ..................................................................................................... 111
Distribution Guide
112
IP Data Manager Distribution ................................................................................................................................. 112
IP Client Applications ............................................................................................................................................. 112
IP Data Server (IPDS) Distribution......................................................................................................................... 112
How to Distribute the IP Data Server ..................................................................................................................... 113
Distributed Applications
114
Divided............................................................................................................................................................. 114
Separate Processes ........................................................................................................................................ 114
Advanced......................................................................................................................................................... 114
Globalization
115
Performance Tips
116
Troubleshooting
117
Index
119
7
IP Driver and Data Server - Overview
The IP (Internet Protocol) Driver enables any Clarion application to use familiar Clarion FILE access syntax to transmit
and receive data over the IP protocol from a “data server”. The client-side IP driver is a Clarion FILE driver, but instead of
using local physical files for storing data it communicates over IP to a server where the physical data is processed. The
SoftVelocity IP Data Server is a Win32 service running on the machine where the physical data files are located and
accessed.
The IP Driver is compatible with any application written using either the Clarion or ABC template chains. The client
application can make use of the entire Clarion runtime library, any Windows API functions, ActiveX controls, any
supported FILE driver, both MDI and SDI windows, and any 3rd Party tool set. The Client application can be configured to
be 100% remote database client, or can use a mix of both local physical files and remote data files. The Client application
can also use a mix of different FILE drivers.
The IP Driver and Server (IPDS) has three major components:
•
The IP Driver, which becomes part of the client application, requests and accepts data from the IP Data Server.
The communication stream can be performed with or without SSL (Secure Socket Layer) support.
•
The IP Data Server accepts requests for data from the client, processes the request and returns the data. The
IP Data Server can be installed on Windows NT, Windows 2000, Windows 2003 or Windows XP.
You may also install the IP Data Server on Windows 98/ME, however neither of these platforms are server
Operating Systems, so we do not support them for deployments. Your results with these O/S's will vary according
to various factors such as the amount of RAM installed, service packs installed, etc.
•
Remote Administrator: the Remote Administration Console application is designed for administrators, and allows
you to Shutdown the Server, Register/UnRegister Data Manager DLLs, monitor connections, specify USER
accounts and permissions for tables, and more.
To enable a Clarion application to function as a remote database client, there are only three steps; adding the IP Client
extension template to the client application(s), the creation of a server side Data Manager DLL, and registering the Data
Manager DLL on the server.
8
What’s New in Version 1.3/1.4
The following section documents key new features and changes in the IP Driver Version 1.3:
New Timeout setting on the server for sessions
•
See the Tools > ServerSettings menu item in the Remote Administrator. This affects both IP Client applications
AND the Remote Administrator sessions (anything that connects to the IP Driver Service).
Forced disconnect on a new Remote Administrator session
•
Forced disconnect on a new Remote Administrator session when a Remote Administrator is already connected
Guest User Administration
•
•
•
•
•
You can now delete the Guest user account for added security.
You can’t modify the Guest user (You can only delete it or add again).
Any password that you set for the Guest user is ignored.
It is not possible to assign administrative rights to Guest user.
Finally, the name “Guest” cannot be assigned to another account (when you are modifying it).
Improved Connection Handling
•
Re-establishing a connection is implemented in this release, when all FILEs are CLOSEd the next OPEN starts a
new connection. This is a change from previous versions, where the connection would remain opened even after
all files were closed, and only terminated when the client program was shut down.
•
There is also template and class support for this new feature. See the Extended Server Support Extensions –
Client in this PDF, and the new SetKeepAlive, IsAlive, and CloseConnection methods in the IP Driver Class
Library Reference. There are two new code templates available to help you implement more robust connection
handling, IPKeepAlive and IPIsAlive.
9
What’s New in Version 2.0
Version 2 has two important new features:
•
Support for Server-side VIEWS, and
•
Support for Multiple Request Packets (MRPs).
Server Side VIEWS
Up until Version 2, all VIEWs defined in the IP Client application were processed on the client side, which meant that all
ordering and filtering was also performed on the client side. This meant unwanted data traffic between the IP client
application and the Server side Data Manager.
Server-side VIEWS allow all ordering and filtering to be performed on the server side, and only the pertinent data is
returned to the Client application, resulting in better performance with this version.
Multiple Request Packets
In Windows terms, a request packet is defined as a data structure used to represent a single input/output request and
control its process. The I/O request packet structure consists of a header and one or more stack locations.
Version 2 of the IP Driver supports Multiple Request Packets, which means in Clarion terms that multiple requests for data
can be contained in a single packet. You can also include NOMEMO support for an even greater performance.
Both of these new features are designed to enhance the performance of your IP Client application with the streamlining of
the contents and amount of data packets transferred. The supporting templates in this release have also been updated to
support these new features.
Please see the Advanced Server Support section in this document for more detailed information.
Template Support for Remote Variables
There are two new code templates available in the IP Client application that allow you to achieve better control of remote
variables that are stored in the target server’s Data Manager DLL. IPSetRemoteVariable is used to prime the contents of
a target remote variable with a particular value. IPGetRemoteVariable is used to return the current value of a remote
variable that is defined in the Data Manager. See the IP Driver Code Templates – Client Application section in this
document for more details.
New “From List” Connection Option
In the IP Client Global template, you can now specify a “From List” Connection Option. The accompanying list contains a
list of different types of server connections that you specify, and you can select one type before compiling the application.
This allows you to store a “development” connection and a “production” connection, and maintain both easily.
10
Installation
There are two installation programs for the IPDS; one install for the IP Driver and another install program for the IP Data
Server. During the development cycle, the client application and IP Data Server may be run on the same machine, or you
can choose to install the server on a separate machine. The same is true when you deploy the application.
From your installation media run the following programs:
IPDriver_setup.exe
IPDataServer_setup.exe
Register the Driver and Templates
Register the IP Driver in the Clarion IDE. From the Clarion IDE main menu choose Setup-> Database Driver Registry.
Select the C60IPD.DLL and press the “Add” button.
Register the templates. This is accomplished by selecting the Template Registry menu item from the Clarion IDE Setup
main menu. You will register two template files; IPDRV.TPL and IPSERVER.TPL
Both the IP Client and Server templates are compatible with ABC and Clarion template family applications.
Install the Java runtime (1.4 or higher)
The RMadmin application requires Java 1.4 or higher. If you don’t have Java installed open this URL
http://www.softvelocity.com/java/index.htm and download the Java install.
11
12
Install Notes
The IP Driver ships with two example applications found in: \Clarion6\Examples\IPdriver\People and
\Clarion6\Examples\IPdriver\MultiDLL
Fast Start
This manual quickly guides you through both IP examples. It is very strongly recommended that you work through both
examples before proceeding with new projects.
Online Tutorials
See the online help file that ships with this product for a series of Flash tutorial movies that demonstrate the
implementation and design of an IP enabled application.
Server Directory structure
By default, the IP Data Server is installed into the \ClarionDataServer folder and RMAdmin is created as a subfolder :
\ClarionDataServer
This folder contains the engine, libraries and configuration files needed for the IP Data Server.
RMAdmin
This folder contains the Remote Administrator Console. The Admin console can be launched from the RUN.BAT batch
file, or by double-clicking the RMadmin.jar file.
You must have Java SDK or JRE versions 1.4 or greater installed on your development machine.
More information on this utility can be found in the Java Remote Administrator topic in this manual.
The installation program installs the SoftVelocity IP Data Server service by running:
\ClarionDataServer\IPREQ –i
You can manually install or uninstall the SoftVelocity IP Data Server service from the command line:
IPREQ –i
(the parameter is case sensitive, lower case “i”)
The –i switch indicates “Install”.
The –u switch uninstalls the data server.
13
IP Data Server Manager
The IP Data Server Manager (IPSRVMGR.EXE) is a handy utility that you can use to perform a number of operations on
the Data Server. It also displays the Machine IP Address and Port number assignments:
Install Service
Press this button to auto install the SoftVelocity IP Data Server Service. After accepting the license agreement, you will
receive a confirmation message that the service has been successfully installed.
To confirm the successful installation, navigate to the Control Panel > Administrative Tools > Services (in XP and
W2000), and verify that there is a SoftVelocity IP Data Server Service installed:
Remove Service
Press this button to automatically remove the SoftVelocity IP Data Server Service. You will receive a confirmation
message when it has been successfully removed from the Windows Services.
Start Service
Press this button to start the SoftVelocity IP Data Server Service. The service must be running before accessing the
Remote Administrator, or running any Client application. You should receive a confirmation message when the service is
started correctly.
14
Stop Service
Press this button if you need to stop the SoftVelocity IP Data Server service for any reason. You should receive a
confirmation message when the service is stopped.
Change Port
The IP Data Server Manager displays the current ports used for SSL and Non-SSL protocols. If these default port
numbers are in conflict with another application, press this button to change the port numbers if needed.
Delete Config File
The IPREQ.CFG file contains information regarding the Data Managers that you have installed, and authorized users. If
for some reason you would like to empty these values completely, press this button. You will receive a message to
confirm your delete action before actually deleting this file.
15
Architecture
The Clarion application program is linked with the IP Driver. When the client application issues an OPEN(file) for an IPenabled file, the IP driver transmits a request to the IP data server to load the specified Data Manager and OPEN the file.
If the request is successful the IP Data Server spawns a new thread for that client session.
How to IP-enable a FILE
To IP-enable any FILE structure, you only need to modify the OWNER attribute of the FILE structure, and change the
FILE driver to the IP Driver. For an IP-enabled FILE the OWNER attribute uses the following syntax to specify the
parameters to communicate with the IP Data Server:
DataManagerDLL@HostName:Port[:UserName:password]
The “DataManagerDLL” parameter is the name of a DLL that you create from your Dictionary using the IP Server
template. It is comparable to the traditional “Data DLL” commonly used by most multi-dll applications in that it represents
the tables in your dictionary.
The “HostName” parameter is the data server’s IP address or a hostname that can be resolved using DNS.
The “Port” parameter is the port number the IP Data Server is configured to listen on.
The “UserName:Password” are optional parameters to specify a user account you created on the server and the
associated password.
Let’s take a look at an example File Structure.
16
Here is the structure before IP-enabling the FILE
people
KeyId
KeyLastName
Record
Id
FirstName
LastName
Gender
FILE,DRIVER('TOPSPEED'),PRE(PEO),THREAD
KEY(PEO:Id),NOCASE,OPT
KEY(PEO:LastName),DUP,NOCASE
RECORD,PRE()
LONG
STRING(30)
STRING(30)
STRING(1)
END
END
and here it is after IP-enabling the FILE
people
KeyId
KeyLastName
Record
Id
FirstName
LastName
Gender
FILE,DRIVER('IPDRIVER'),PRE(PEO),THREAD,OWNER(‘ip_people.dll@localhost:2339)
KEY(PEO:LastName),DUP,NOCASE
RECORD,PRE()
LONG
STRING(30)
STRING(30)
STRING(1)
END
END
As you can see, the OWNER attribute was added to the FILE structure in order to specify the Data Manager DLL, IP Data
Server, and the Port. The DRIVER attribute is also changed to reflect the IP Driver. In this example, our Data Manager
DLL is named ip_people.dll , and the data server is running on our local machine (localhost), listening on Port 2339. This
single change (and a Data Manager) is all that it takes to access a remote data source.
The support template that ship with the IP Driver will handle all of this configuration process for you. This section is only to
describe what is happening behind the scenes.
17
An IP-enabled Application in 10 minutes (or less)
Now that you have a feel for the architecture of the IP Data Server (IPDS), we’ll build and deploy our first IP-enabled
application. If you haven’t already installed the IP Data Server and Driver please do so now. If you need help with the
installation process refer to the “Installation” chapter in this manual.
We’ll use the “People.app” that was installed with the IP Driver for this exercise. We’ve already done the work of adding
the extension templates for you, so the whole process will likely take less than 10 minutes.
1. Start Clarion and then open \Clarion6\Examples\IPdriver\people\IP_people.App
This is the “Data Manager” application. If you look at the Application Properties, you’ll see that it was defined to use the
People dictionary (people.DCT) and the IPServer application template.
2. The creation of the Data Manager DLL will be your first step when IP-enabling any application. Go ahead and
press the Make button. The compiler will create “IP_people.DLL”.
NOTE: All IP-enabled applications (Data Managers and Client Applications) must be linked in “StandAlone” mode.
You can also use the Data Manager DLL Wizard to help you to generate the Data Manager. See the Data Manager DLL
Wizard section later on in this PDF for more information.
3. Look in \Clarion6\Examples\IPdriver\people\ and copy the IP_people.DLL it to your data server directory.
4. Next, copy the physical data file to the server directory.
From \Clarion6\Examples\IPdriver\people\ copy “PEOPLE.TPS” to your data server directory.
NOTE: If your target server does not have Clarion installed, you will also have to copy the C60RUNX.DLL and
Database driver DLL (i.e., C60TPSX.DLL) to the target server’s directory root. See the Deployment Checklist section
in this PDF for a complete list of files to copy, or, if you have any problems running the completed Client application.
After you have deployed the necessary files to the target server , it is now time to register the newly created Data
Manager. You do this by running the Remote Administrator (rmadmin.jar) application.
NOTE: RMadmin requires Java 1.4 or higher is installed. If you don’t have Java installed yet, go to
http://www.softvelocity.com/java/index.htm right now for a convenient link to download the Java install.
5. Open Explorer. Navigate to \ClarionDataServer\RMadmin and double-click on the rmadmin.jar file. Make sure
that the SoftVelocity IP Data Server Service is started (see page 8).
TIP: If the RMadmin main window doesn’t appear, go to a command prompt in the same directory and execute “Run.bat”.
The batch file will report any problems locating the correct version of “Java .exe”.
18
6. Once you have the RMadmin console running from the main menu choose
Connection->Connect to IP Server…
You’ll see this dialog:
7. When the IP Data Server is first installed, use “Administrator” for the User name and leave the Password blank.
If you didn’t install the server on your local machine enter the correct IP address and if you changed the Port the
server is listening on, then set that to the proper value.
8. Press the “Connect” button.
9. Right-click on the Data Managers icon and from the popup menu choose Register Data Managers…
19
10. The dialog shown below shows available “Data Managers” and the IP_People.dll we just created is listed. Press
the “Register” button.
Next, expand the Data Managers node by clicking on the plus sign in the tree display. Select IP_people.dll in the tree list.
The right-hand panel display now looks like this:
20
11. Right-click on the PEOPLE table as shown here:
12. Choose Table Permissions from the popup menu. NOTE: In the following steps, your install program may have
already included the Guest and Administrator accounts with all permissions granted. However, it’s a good idea to
review this process at this time.
13. In the dialog shown below, press the “Plus (+) ” button.
14. From the list of users in the Select Accounts dialog, highlight the Guest user, and then press the Select button.
15. Finally, press the OK button to close the Permissions dialog.
21
22
Summary:
At this point we have done the following:
•
created the Data Manager “IP_People.dll” and deployed it to the server
•
copied the PEOPLE.TPS data file to the server
•
registered the Data Manager DLL “IP_People.DLL” on the server
•
granted access permissions to PEOPLE.TPS for the Guest and Administrator account (this was preset by the
install).
Now it’s time to build our IP client application. Switch back to Clarion6, and Open
\Clarion6\Examples\IPdriver\People\People.app. Press the Make and Run button.
When the application starts choose one of the Menu items to Browse the file.
You now have your first IP-enabled application up and running!
23
A Multi-DLL example
The first example was intentionally very simple. Now we’ll look at the steps needed to IP-enable a multi-DLL application.
1. Startup Clarion6 and open \Clarion6\Examples\IPdriver\MultiDLL\IP_country.app
This application is our Data Manager DLL for the server.
2. Open the Global Properties:
The global properties dialog displays:
IPS File Defined
The IPS file is a helper file generated by the IP Server template. It contains the name of the Data Manager DLL, a list of
all the tables that you have IP-enabled in this particular application, and a list of remote procedures available in the data
manager. The IP Client template reads the IPS file to obtain that list of IP-enabled tables so that you don’t have to
remember them.
The template constructs the name of the IPS file as applicationName.IPS.
3. Press the Make button. Copy the IP_Country.DLL to your data server directory.
4. Copy the country.tps file to your data server directory.
24
5. Run the RMadmin application and register the IP_Country.DLL. Refer to the previous quick start example if you
need help remembering how to register a Data Manager. Don’t forget to grant access permissions to the Guest
account.
6. We’re IP-enabling a multi-DLL app, so our next step is to open \Clarion6\Examples\IPdriver\MultiDLL\DataDLL.app
7. Open the Global Properties and click the Extensions button. You’ll see the following dialog:
Note that the template prompt, Select IPS File has the value IP_Country.IPS. Remember that the IPS helper file was
created when we built our Data Manager DLL.
But now we see there is something else new, the IP Client template informs us that the generated IPC File name is
DataDLL.IPC.
IPC File Defined
The IPC file is another helper file; the IP Client template generates this one. It contains the list of all the tables that you
have IP-enabled in your Data DLL application. The IPC Client template reads the IPS file to obtain that list of IP-enabled
tables, but you are free to override which files are IP-enabled for this application. So the IPC file is generally equivalent
to the IPS (IP server template generated) file. But it can also contain a subset of the files listed in the IPS file.
The template constructs the name of the IPC file as applicationName.IPC.
To review, the IPS file (S is for server) is generated by the IP Server template when you create your Data Manager DLL.
The IPC file (C is for client) is generated by the IP Client Template when your project is set to create a DLL. In other
words, it is created when you build the Data DLL for your multi-dll application. Don’t confuse the Data Manager DLL that
is deployed to the IP data server, with the traditional Data DLL that is deployed with the client application.
8. Press the Make button to build your IP-enabled Data DLL.
9. Open \Clarion6\Examples\IPdriver\MultiDLL\ProcsDLL.app
10. Open the Global Properties and click the Extensions button. You’ll see the following dialog:
25
Make sure that the IPC file is correctly named as shown above.
Are you wondering where the prompts for the Data Manager, Hostname, Port, etc. went? When the IP Client Template
detects that you have your Files defined as “All External” as shown here, the IP Client template only prompts for the IPC
file name.
The template has enough “brains” to know that all of the component DLLs in a multi-DLL application must share the same
Data Manager and server connection information. So the only thing the template needs is the list of tables that your Data
DLL has IP-enabled. The template reads that information from the IPC file.
11. Close the Global Properties dialog, and press the Make button.
12. Open \Clarion6\Examples\IPdriver\MultiDLL\Country.app
If you open the Global properties and check the settings for the IP Client template you’ll see that as expected in a
multi-dll application where all files are external, the IP Client template only prompts for the IPC file.
13. Finally, press the Make and Run button.
That’s all that is needed. You have now created and deployed your second IP-enabled application. The steps you
just went through are the same you’ll do for any application multi-DLL application.
26
Deployment Checklist
To deploy an IP-enabled application, always follow these guidelines:
•
Copy the Data Manager DLL to the IP Data Server folder. Run the RMAdmin application to Register the Data
Manager and grant file access permissions.
During the development phase, you will probably need to test locally on your machine. To expedite this,
create an entry in your Redirection file so that files named as IP_*.dll are created in your data server directory (by
default , \ClarionDataServer).
Example:
[Common]
IP_*.DLL = C:\ClarionDataServer
•
Copy the required data tables to the IP Data Server. For example, if you are testing locally, copy them to
C:\ClarionDataServer.
•
Copy the runtime libraries to the IP Data Server root folder.
Note: during development you can skip this step if your machine has a PATH setting that includes
C:\Clarion6\bin.
Both the server-side Data Manager and the Client application must be able to load the required Clarion
runtime DLLs and IP Driver support DLLs. An example of Clarion runtime files to copy to the server would
be as follows:
C60RUNX.DLL
C60TPSX.DLL (application is using TopSpeed tables)
Client Application:
LIBEAY32.DLL (IP Driver support library)
SSLEAY32.DLL (IP Driver support library)
OSSLWRAP.DLL (IP Driver support library)
NOTE: The following Microsoft system libraries must also be in the system path for both client and server
locations:
MSVCRT.DLL
MFC42.DLL
MSVCP60.DLL
(See the Advanced Deployment Tips and Distribution Guide sections in this manual for additional options)
•
Register the Data Manager DLL: From the menu select Tools->Register Data manager and select the Data
Manager DLL (IP_*.DLL) and then press the register button. Your Data Manager DLL will appear in the righthand panel of the console.
Select the registered data manager in the tree. The right panel will display all available tables.
Right-click on any table and select the Table Permissions… option from the popup menu.
In the Table Permissions dialog, press + and select Guest.
Specify the required access for the guest account. You can repeat this for each individual table, or press the
Apply to all Tables button to cascade these settings to all tables.
This completes the deployment setup! You can now run your Client application to begin testing.
27
28
Server Security Settings
If the client application does not specify a user name and password the connection is treated as anonymous, and the
server automatically assigns the 'Guest' account with an empty password for the session.
In the Administrative Console the "administrator" must assign permissions for the Guest account to the appropriate data
files in the Data Manager DLL (IPFiles.dll)
If the client application specifies a user name and password, the Administrator must specify account permissions for that
user as well.
In summary, the "Administrator" must register the data manager(s) before the client application is started and provide
appropriate permission for accounts to be used by client application. In the case that there is no account (no user name
and password) the Guest account is used.
29
SSL Deployment Considerations
This section discusses the setup of SSL connections used with the IP Driver and Server.
Enabling a SSL connection in your IP Client application is easy! All you need to do is modify the PORT number in the
Connection information setting in the template:
When the IP Data Server is installed the SSL port is set to 2340. To change or verify the SSL port setting, open
\ClarionDataServer\Claipsrv.ini and modify the SSL_PORT entry.
OpenSSL is a cryptography toolkit implementing the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security
(TLS v1) network protocols and related cryptography standards required by them. SSL can protect data in transit on a
live connection, but it cannot protect data before it is sent or after it arrives.
The Openssl.exe program is a command line tool for using the various cryptography functions of OpenSSL's crypto
library. You can obtain the OpenSSL utilities from various Internet download sites.
OpenSSL is available for download in source format from http://www.openssl.org/
There are also pre-built binary versions available for download, one source for a Win32 binary version is the Win32
OpenSSL Installation Project available from: http://www.slproweb.com/products/Win32OpenSSL.html
To make use of SSL with your Clarion IP-enabled application you need to deploy the key pair files. OpenSSL supports
two standard formats for storing and exchanging key pairs. The format used with the IP driver is PEM (Privacy Enhanced
Mail), which is defined in RFCs 1421,1422,1423 and 1424. PEM data is base-64 encoded and provides abilities to
encrypt the data before its encoded.
There are two example PEM files installed in \Clarion6\Examples\IPdriver, server.pem and client.pem. If you want to test
your application using SSL, copy the server.pem file to the root of the IP Data Server, and copy client.pem to the same
location as the IP Client application.
Documentation and further information on OpenSSL is available at:
http://www.openssl.org/related/
In addition, O'Reilly publishes a very good book on OpenSSL: Network Security with OpenSSL, by John Viega, Matt
Messier, and Pravir Chandra. ISBN: 0-596-00270-X
30
LEGAL NOTICE: This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit.
(http://www.openssl.org/). The OpenSSL toolkit is licensed under an Apache-style license, which basically means that
you are free to get and use it for commercial and non-commercial purposes subject to some simple license conditions. For
details of the license please refer to http://www.openssl.org/source/license.html.
Please remember that export/import and/or use of strong cryptography software, providing cryptography hooks or even
just communicating technical details about cryptography software is illegal in some parts of the world. So, when you
import this package to your country, re-distribute it from there or even just email technical suggestions or even source
patches to the author or other people you are strongly advised to pay close attention to any export/import and/or use laws
which apply to you. Neither SoftVelocity nor the authors of OpenSSL are liable for any violations you make here. So be
careful, it is your responsibility.
31
Optional Dictionary Settings
In the design and implementation of an “IP-enabled” application used with the IP Driver, the target dictionary does not
require any modifications. However, by specifying a special User Option setting on selected tables, you can define these
tables that are always to be IP-enabled by default, or never enabled by default.
To accomplish this, from any table add the IPDRV = TRUE setting in the Table Properties’ Options dialog (Boolean
value). The actual File “Driver” setting should remain unchanged (i.e. TopSpeed, Btrieve, etc).
The IPDRV option sets the table as a default IP-enabled table when the IPServer Template is applied. You can always
override this setting from the IP Server global properties if required.
To summarize, this setting is used to notify the IPServer application as to which tables it will include in the generated Data
Manager DLL by default. In the IP Server application’s Global Properties, you can always override this setting as needed.
32
IP Driver Template Support
There are two templates included with the IP Data Server. The Client side application support is located in the IP Client
Global Extension: IPDRV.TPL.
The Server-side application is created using the IP Data Server template: IPSERVER.TPL
33
IP Server Template
The IP Server template is used to create the “Data Manager” DLL. The Data Manager application defines the tables that
are allowed to be accessed by an IP-enabled client application. This template also includes a simple wizard interface that
allows you to quickly generate a new Data Manager DLL as needed. You only need to know the data dictionary, and
include the IPServer Application template in the appropriate prompt in the Application Properties window. The online help
file describes this wizard in detail.
When you generate an Application that has the IPSERVER template applied to it, the IP Server template creates an
associated (ApplicationName.IPS) file. The IPS file is used by the IP Client template to obtain the list of IP-enabled tables
available in the Data Manager application.
The IPS file
The IPS file is a helper file generated by the IP Server template. It contains the name of the Data Manager DLL and a list
of all the tables that you have IP-enabled in this particular application. The IP Client template reads the IPS file to obtain
that list of IP-enabled tables so that you don’t have to remember them.
The template constructs the name of the IPS file as applicationName.IPS.
Under the Global Properties of the application that uses this template, the following prompts are available:
General tab
If you check “Generate Table names using table labels” all of your files will be referenced with their table label, and the
NAME attribute will be ignored.
34
File Control tab
All the files in your data dictionary default to “IP enabled” unless you have used the IPDRV User Option (described in the
Dictionary Preparation section) to turn this option OFF. The File Control tab is used to override the default settings for
individual files.
To change the Default setting for the table, highlight the table and press the Properties button. You can specify Default
(use the dictionary’s setting), or you can override the dictionary setting by choosing Generate or Don’t generate.
The Don’t Export check box is enabled whenever the Generate option is selected. When checked, this option will not
generate this file declaration into the IPS configuration file. Use this option when you only need a dictionary table to be
visible to the Data Manager only. For example, you could have a remote procedure defined in the Data Manager that only
accesses a table defined on the server location. The Client application and the Remote Administartor will not be able to
“see” this table.
IPServer Version
The last tab control displays the version number of the IP Data Server templates.
35
Data Manager DLL Wizard
Although the process of creating a Data Manager DLL using the IP Server Application template is fairly straightforward,
we extend its ease of use with the addition of the Data Manager DLL Wizard.
Starting in the Application Properties dialog settings:
•
•
•
•
Set the server application Dictionary File to use your planned client application's Data Dictionary.
Clear the First Procedure entry field
Select DLL for Destination Type
In the Application Template entry field, press the ellipsis button and choose IPServer from the Select Application
Type dialog:
•
Check the Application Wizard. Press the OK button to begin the Data Manager DLL Wizard.
36
1. This first screen is merely an introduction. Press the Next button to continue.
2. This window allows you to control which files in your dictionary will be deployed to the target server, and
referenced by the Data Manager DLL. If you uncheck the above option, an additional dialog is available
through the Next button. Otherwise, you can click on the Finish button to create the application.
3. After selecting or deselecting the desired files to use, press the Finish button to create the application.
To complete this development phase, press the Make button to create the DLL.
37
38
IPDRV Extended Server Support Extensions
The IPDRV Extended server support global template extensions allow you to add new functions to your IP enabled
application with the help of template support.
These functions are:
•
Calling any Data Manager custom procedure from an IP-enabled Client application.
•
Automating the use of runtime file name variables in your IP-enabled application.
•
Allow any file type to be easily transferred from Client application to IP Data Server in both directions.
•
Support for multiple data sets in different locations can be easily supported.
There are two Global Extensions that are available in this template set. The first is used for the Data Manager application,
and the second is used for the Client application. We will look at the Data Manager application support first.
Examples for each of these techniques are demonstrated and found in your default examples that are included in this
install.
Technical Notes
Note: This template creates two file structures that will be used internally and should not be used or modified.
Both use the DOS file driver. IPSENDRemoteFile is used as the conduit for the IPEXEC method. This file will be created
in the Data Manager root DLL as "IPSEND.IPSEND." The other file is used to send and receive files from the client.
39
IP Server Extension – IPDRV Extended
This template adds some new embeds and functions in the Data Manager application that can be called from the IPenabled client application.
The IPDRV Extended options in the Data Manager application are as follows:
Enable support for Global Variables as file names
This option will automatically enable any file that is using a global variable as the file name to be supported in the
IPSetFileName procedure (see the Server Side Embeds and Procedures topic in this PDF). All other file can also be
supported by enabling them in the Runtime Names option.
If this option is on (checked), any file using a variable in the dictionary’s File name prompt will not appear in the Runtime
Names list box.
Enable secure file name(s) support
If this option is on (checked) any file name sent by the client application via the IPSetFileName procedure will be
automatically translated to be in the same directory of the Data Manager DLL location. For example, C:\people
example\people.tps will be translated to .\people example\people.tps in the Data Server root.
If the extra directory does not exist on the server, it will be automatically created.
With this option you can be sure that the user will never have access to a file that is restricted. The file name translation is
performed by the GetSafeName procedure. This procedure also supports TopSpeed super files.
Enable Debug using TRACE
Enable this option to include the TRACE prototype in your Data manager application for its use with the DebugView utility.
For more information, see the DebugView Support topic in this PDF.
40
IP Server Extension – Runtime Names
The Runtime Names tab control contains a list box of all tables used in the Data Manager application that does not have
a variable name defined in the dictionary table’s file name prompt (i.e.,!GLO:Peoplename):
Allow runtime Filename change
If a selected file does not use a variable in the File Name option in the data dictionary, you can still enable the file name to
be changed by enabling this option. For example, you use PROP:Name at runtime instead of a global variable.
Use different name for each thread
If your application requires a different filename each time a new thread is launched, check this option. You must make
sure that you set the file name on each thread prior to the file open.
IP Server Extension – Server Variables
If there is any defined variables in your IP Server application that need to be “visible” (or exported) to your IP Client
application or other DLLs, include them here. These variables will also be included automatically in the generated IPS file,
used to identify these Remote Variables in the IP Client application.
The description of the IPDRV Extended Options for the Client application is discussed just following the IP Client
Template section.
41
IPEXEC Source Procedure Template
Overview
The use of the IPEXEC Source Procedure Template in your Data Manager application provides an easy way to execute a
remote procedure. The procedure defined here will be called from the Client application with the use of the EXEC method.
The Client application calls the EXEC method from the IPExtender class as follows:
IPx.Exec('ProcedureName',Par1,Par2,[,..,Par20])
Up to 20 parameters are supported, and an optional return value is also available.
On the server side (in the Data Manager application) IPEXECDispatch handles any information received by the Client’s
EXEC method. It will parse the incoming string, check for the procedure, and call it with the appropriate parameters.
A remote procedure should always be created with the Procedure Template IPEXEC Source Procedure for the
IPEXECDispatch to be automatically called.
The source procedure template is nearly identical to a standard source procedure template ,but contains a single
additional option:
Enable Parameters Debug
As discussed in the DEBUGVIEW support section, the use of the built-in TRACE procedure is available to send
information to the DEBUGVIEW utility. This option simply enables the parameters passed to this procedure to be applied
to an embedded TRACE statement.
42
IP Client Template
The IP Client Global Extension template is used to make the client application IP-enabled. The prompts presented by the
template changes based on the application’s setting for the Global Properties->File Control->File Attributes->External
If the client application has its Files declared as “All External”,
The template dialog prompts for the name of the IPC file:
The IPC file is created by the template when you generate your traditional “Data DLL”. In other words the IPC file is
created whenever an application using the IP Client template has its target type set to DLL.
The IPC File
The IPC file is another helper file; this one is generated by the IP Client template. It contains the list of all the tables that
you have IP-enabled in your Data DLL application. The IPC Client template reads the IPS file to obtain that list of IPenabled tables, but you are free to override which files are IP-enabled for this application. So the IPC file is generally
equivalent to the IPS (IP server template generated) file. But it can contain a subset of the files listed in the IPS file.
The template constructs the name of the IPC file as applicationName.IPC
43
If the client application has its Files declared as “None External”, the IP Client template presents these prompts:
Select IPS File
Type in the name of the IPS file, or press the ellipsis button to select it.
Note: The IPS file was created when you built the “Data Manager” DLL using the IP Server template and lists all the FILEs
that are “IP Enabled”.
After the IPS file is selected, a list of IP-enabled tables will be available in the Tables dialog listbox.
Connection Type
The IP Client application needs to know the connection information to reach the IP Data Server. There are three options in
the dropdown list for the ways that connection information can be specified; Fix, Variable and Handcoded.
44
Fix
Use the Fix option when you know the IP address or Hostname of the data server before deploying the client application.
Data Manager
Enter the name of the “Data Manager” DLL that this client application will use. The full name of the DLL (including
the extension) is required (i.e., IP_FILES.DLL). In addition, if your Data Manager is stored in a sub folder of the
data server’s target folder, specify the sub folder here ((i.e., school\IP_School.DLL)
Host Name
Enter the name of the server here. This can be a hard coded IP address (i.e., 192.168.0.0), or a domain name
that resolves to the appropriate IP address (dataserver.MYdomain.com).
Note: If you are developing and testing on the same machine you can use the value localhost for the Host Name.
Port
Enter the port number the data server is running on. By default the install program specifies that the IP Data
Server uses port 2339 for non-SSL connections, and 2340 for connections using SSL protocol. The ports used by
the server are specified in the INI file: Claipsrv.ini located in the root directory of the IP data server.
Typical contents of Claipsrv.ini:
[REQUESTER]
PORT=2339
PORT_SSL=2340
To change the ports the data server uses, go to your system Services program and stop the SoftVelocity IP Data
Server service, then edit the port numbers and restart the service.
User Name and Password
If you leave these entry fields blank, the Client application will attach anonymously, and will be granted the
privileges associated with the “Guest” account.
Access to the IP Data Server can be controlled by specifying permissions for the Guest account and by creating
additional User Accounts on the data server and specifying User Name and Password in the connection
information template prompts.
The Remote Administrator application is used to create User accounts and set file access permissions.
The information specified in the Connection Information entry fields is used to construct the OWNER attribute
for all IP-enabled files in the application.
45
Variable
The connection type can also be specified as “Variable”.
The form of the connection information is as follows:
Examples:
[email protected]:2339
[email protected]:2340:superuser:mypassword
Variable Name
Enter the name of the variable that will contain the connection information. This variable should be a string data
type, like a STRING or CSTRING and must be defined as a Global data.
The variable used to store the connection information must be initialized in any embed point prior to the assignment of the
internally defined IPDRV::OWNER variable. You can also store the connection information in any preserved variable
stored in your program’s INI file.
Handcoded
The handcoded option for Connection Information allows you to enter a connection information string manually.
Connection String
Enter a complete connection string using the following format:
DataManager@HostName:Port[:UserName:password]
From List
The From List option for Connection Information allows you to enter a series of different fixed connection strings that you
can select and use at different times in the development cycle.
The most common use of this option will be to easily switch from a development server to a production server connection.
Press the Insert button to add a new connection. The standard connection information is exactly the same as the prompts
described in the Fix option discussed previously, with the exception of the Name prompt, which allows you to easily
identify the type of connection from the list (i.e., My Test Connection, Production Connection, Alternate Server
Connection, etc.).
46
Tables Tab
The Tables tab contains a list of all tables that have been “IP-enabled” in the Data Manager application. The tables listed
here are read in from the *.IPS file that you selected earlier.
You can override the settings in the IPS file. Any table selected in the list box will not be enabled for IP access in this
application but will be generated as a regular local physical file to the application.
47
Extended Server Support Extensions – Client
Extended support for a variety of special method calls used by the Client application is provided through the IPDRV
Global Extension. This template is only required if you are taking advantage of one of the following IP Driver features:
•
You want the template to automatically derive the appropriate IPX object from the IPExtender Class. This class is
documented in the IPDriver Class Library Reference topic in this PDF.
•
Use of the IPX.IPEXEC method to call a procedure in the target Data Manager. This method is documented in
detail in the IPDriver Class Library Reference topic in this PDF.
•
Use of the IPX.SetFileName method to change a file name located on the Data Server. This method is
documented in detail in the IPDriver Class Library Reference topic in this PDF.
•
You want the template to automatically derive the appropriate IPFileTransfer object from the IPTransfer Class.
This class is also documented in the IPDriver Class Library Reference topic in this PDF.
A series of code templates are provided by the IPDriver template to allow the syntactically correct execution of these
methods.
IP Client Extension – General
The General tab provides a brief description of the template’s functions (which were described in the section above), and
one important new template option (as of Version 1.3):
Keep Connection Alive
As of version 1.3, when all FILEs are CLOSEd in your Client application, the connection to the IP Server is also closed.
The next OPEN will start a new connection. This is a change from previous versions, where the connection would remain
opened even after all files were closed, and only terminated when the client program was shut down. To maintain the
same behavior as in prior versions, check this box to allow a persistent connection to the IP Server for the life of the Client
program.
IP Client Extension – Imported Procedures
The Imported Procedures tab control identifies remote procedures that exist in the target Data Manager. The procedures
listed here are READ ONLY, and loaded from the generated IPS file that contains the available procedures.
These procedures are intended to by called by the IPExtender class IPEXEC method. A code template is available to
allow you to easily prototype and execute this method.
48
IP Client Extension – Remote Variables
Remote Variables are defined as those variables that are exported by the IP Server Data DLL, and are available to be
referenced by the Client application. The IPS file loaded by the Client application contains the definition of these variables.
You have the ability to add new remote variables. These are usually hand-coded variables that were not automatically
exported by the Data Manager DLL. You can also remove selected remote variables. This is useful when different IP
Client applications share a single Data Manager, and not all variables need to be exposed in all Client applications.
49
IPDriver Code Templates – Client Application
When you include the Extended Server Support Extension for your IP-enabled client application, the following support
code templates are also available:
IPChangeFileName Code Template
The IPChangeFileName code template is used to modify the table name at runtime, prior to opening the file. With this
implementation, a user can have a secure and distinct data set to use with his application.
Connection String
Press this button if you wish to modify the default connection to the Data Server. Use this option if you have different data
sets in different Data Managers contained within the same application.
File
Select the file name to change from the drop list provided. The files listed here are those that you have IP enabled in your
application.
New Name
Enter a new name in the prompt provided. If the New Name is a variable or an expression, prepend the line with an
exclamation point.
50
IPEXEC Code Template
The IPEXEC Code template is used to call a remote procedure that is contained within the Data Manager. This procedure
should be created using the IPEXEC Source Procedure template.
Connection String
Procedure
Select a procedure name from the drop list provided. The procedure names that are listed here are stored in the IPS file
that you selected in the Global Properties of the IP Client extension.
Parameter 1 … Parameter 20
Enter up to 20 parameters using values extracted from the ellipsis buttons for each, or by simply entering a value.
NOTE: Variable parameter must be designated with a prepended exclamation point. If you do not use an
exclamation point, the parameter will be translated to a string constant.
Return Value
You can also enter a variable name to hold the value returned by the remote procedure.
51
IPTransferFileCode Code Template
The IPTransferFileCode Code Template is used to send and receive files between the Client application and Data
Manager via IP protocol. The prompts are simple and intuitive, and there is no restriction as to the type of file that you
need to transfer. This template can be used in any code embed point in your application, like the Accepted event of a
button.
Connection String
Send or Receive
From the drop list, select SEND or RECEIVE to specify the direction of file transfer to the Data Server. SEND a file to the
Data Server, or receive a file from the Data Server.
Source Name
The Source Name is always the source of the transfer. If you specify SEND, the source name is a file that is located at
the Client application. If you specify RECEIVE, the source name is a file that is located at the data server.
Target Name
The Target Name always specifies the destination of the transfer. If you specify SEND, the target name is a file that is
located at the data server. If you specify RECEIVE, the target name is the file that is located at the client application.
52
IPIsAlive Code Template
The IpIsAlive Code Template is used to detect if an IP Connection is still alive (i.e. active). If the connection is not active,
this template provides additional actions to perform. This code template is only available if you have the IP Client
Extended template active in your application. In any application that does not use a persistent IP Server connection, this
template is not needed because by default when all files are closed, the connection is closed, and only reopened when
the first file is again reopened.
The following actions are available:
Connection String
sets in different Data Managers contained within the same application. Use the default Global Connection String, or set a
new string from a Fixed (template guided) value, Variable value, or a Hand Coded connection string.
Action:
Store Alive Value
Use this option to select a variable that holds the value returned by the IPExtender Class IsAlive method. Simply stated,
you can name a variable here that holds the status of the active IP Server connection, and execute additional code based
on that condition. This action is always generated, whether the IP Connection is active or not.
If an IP connection is not available, you can alternatively:
Reconnect
This option attempts a reconnection to the IPServer based on the Connection String settings.
Execute Routine
Enter the name (or label) of a defined ROUTINE. If an IP Server Connection is NOT active, this ROUTINE will be
executed.
Execute Code
Enter valid source code that will be executed if an IP Server Connection is NOT active. For multiple lines of code, use a
semicolon to separate source lines. For example:
DISABLE(?tbAccounts);MESSAGE('The server time out|Select a new Ledger year to continue.','Attention')
Call a Procedure
Finally, if an IP connection has become inactive, you can execute a procedure.
53
IPKeepAlive Code Template
The IPKeepAlive Code Template is used to maintain a persistent connection to the IP Server Data Manager. This
template is only available if you have the IP Client Extended template active in your application.
This template is handy if a user needs to keep open a browse that could possibly timeout, where any action on that
browse could return an error. The solution is to add this code template to a timer event embed on that procedure or on the
parent frame.
The difference between the IPKeepAlive and IPIsAlive code templates is that the IpKeepAlive always tries to establish a
connection, whether a connection is active or not. The logic for controlling this is handled by the support IpExtenderClass
methods.
54
IPSetRemoteVariable Code Template
The IPSetRemoteVariable code template is designed to allow you to set the value of any Remote Variable defined in the
target server Data Manager DLL. Here is the process of setting up a remote variable:
1. Define the variable in the Data Manager DLL, and using the Global IP Server Extension, select the appropriate
variable for export. (For more information see the IP Server Extension – Server Variables section in this
document.) This variable will be generated in the template IPS file used by the IP Client application.
2. Verify that the target Remote Variable is available via the Extended Server Support Extensions – Client (note, this
extension is not required to use this template, it simply shows you an easy way to view all Remote Variables
defined via the template interface).
3. Select the Remote Variable to set in the Variable drop list provided. In the Value prompt, add a constant or
variable value. If specifying a value, make sure to prepend the variable name with an exclamation point
(i.e., !MyVariable)
IPGetRemoteVariable Code Template
The IPGetRemoteVariable code template is designed to allow you to get (or retrieve) the value of any Remote Variable
defined in the target server Data Manager DLL. The same rules apply as in the IPSetRemoteVariable code template
described above. The Remote Variable must be exported and visible to the IP Client application.
Select the Remote Variable to get in the Variable drop list provided. In the ReturnValue prompt, select a variable that will
receive the value of the selected Remote Variable. Check the Refresh window after getting the value check box to
force a window refresh after the value has been retrieved (this is useful for instantly displaying the result).
55
IPTransferFile Control Template – Client Application
The IPTransferFile Control Template is used to send and receive files between the Client application and Data Manager
via IP protocol. The prompts are simple and intuitive, and there is no restriction as to the type of file that you need to
transfer. This template can be used in any window in your application. It populates a Transfer button, which starts the
transfer process, a progress control to keep track of the transfer progress, and a cancel button to abort the transfer if
needed.
Connection String
Pause Text
Enter a string that will be used on the Transfer button control while the transfer process is active. The default value is
“Pause”
Window Timer
This number is a value assigned to the TIMER attribute of the window. It allows you to control how “process intensive” the
file transfer will be. Enter a low value if you need little or no control of the window during transfer, or a higher value
otherwise.
Send or Receive
From the drop list, select SEND or RECEIVE to specify the direction of file transfer to the Data Server. SEND a file to the
Data Server, or RECEIVE a file from the Data Server.
Source Name
The Source Name is always the source of the transfer. If you specify SEND, the source name is a file that is located at
the Client application. If you specify RECEIVE, the source name is a file that is located at the data server.
Target Name
The Target Name always specifies the destination of the transfer. If you specify SEND, the target name is a file that is
located at the data server. If you specify RECEIVE, the target name is the file that is located at the client application.
56
Extended Server Support Extensions Examples
Your install in this version includes two example applications that demonstrate the raw power and ease of use of the
Extended Server templates. These examples can be found in the Examples\IP Driver folder located in your Clarion root.
File Transfer
This folder contains two applications; the IP_Transfer application is used to create the data manager, and the
Transfer_Example application is the IP-enabled Client application.
Start by making the Data Manager (IP_Transfer.APP). Deploy it to your IP Data Server location and register the Data
Manager (IP_Transfer). You should notice two files that are created internally by the templates. These files will handle the
housekeeping of your file transfers. Also, examine the application and you will notice that there are two remote
procedures defined, and both are using the IPEXEC Source Procedure template.
Next, compile and run the Transfer_Example application. This application demonstrates two powerful functions, calling a
remote procedure and performing a file send/receive to/from the server.
Note that during a SEND, the target file designates the name and destination of the file uploaded to the server. If your
target string is “C:\Upload\Myfile.txt”, the location of the transferred file will be in a folder named “\Upload” in your Ip Data
Server location, and the file contained in that folder will be “MyFile.TXT”.
Study all embeds and template prompts in this example, and refer to the template help when necessary.
Multidataset
This folder contains two applications; the IP_Ledger application is used to create the data manager, and the Ledger
application is the IP enabled Client application.
Start by making the Data Manager (IP_Ledger.APP). Create a folder named LEDGER on your IP Data Server location,
deploy the IP_Ledger.DLL to the new LEDGER folder and register the Data Manager (IP_Ledger).
Next, compile and run the Ledger application. When you select a Year, the program will create a folder in the Server
Ledger that names the year you selected (Example: \2003). For each year that you select, a separate folder will be
created with a unique data set!
Examine the Ledger application again, and you will notice the use of the new Change Filename template, which
concatenates a valid year to the default file names used in the application.
57
Server-side Embeds and Procedures
The IP Server template embeds
The code that you embed in your Data Manager DLL executes on the server, so it is critical that you do not embed code
that displays a user interface and requires user intervention to continue. This includes the use of the MESSAGE()
and STOP() functions. You should never use HALT(), as this prevents the server from properly closing the session.
The IP Server template provides some new embed points to take advantage of procedures that execute on the data
server.
58
GetFName (change the name of the data file or path)
GetFName() is called for each file used by the client application, and is intended to allow the user to change the name of
the file at runtime. It receives the original strSrcName name and returns the new name set by pstrNewName. This is the
best and recommended place where changes in any IP enabled filename should be performed.
If the function returns TRUE, the name will be changed, if it returns FALSE (the default) the new name designated by the
pstrNewName parameter is ignored. You need to set the ReturnValue to TRUE for the filename change to be activated.
Implementation: Access to the GetFName procedure is available in the IPServer application’s Change FileName Data
and Code embed points.
GetFName(strSrcName, pstrNewName),LONG
strSrcName
A string constant or variable that identifies the original file name to change.
pstrNewName A reference to the new file name to process.
Examples:
!code in BLUE is embedded code
GetFName
PROCEDURE(STRING strSrcName, *STRING pstrNewName)
ReturnValue
LONG
CODE
!Change FileName - strip out hard coded path
IF LEFT(strSrcName,3) = 'C:\'
pstrNewName = '.' & SUB(strSrcName,3,LEN(CLIP(strSrcName)))
ReturnValue = TRUE
! change filename
END
RETURN ReturnValue
*********************
!here is an example of changing the path of the data files at runtime
!Code in
LOC:Path
LOC:Dir
LOC:File
LOC:Ext
DATA Embed
CSTRING(FILE:MaxFileName+1)
!Code in the CODE embed
LOC:Path = strSrcName
!call internal PathSplit function to extract components
PathSplit(LOC:Path,, LOC:Dir, LOC:File, LOC:Ext)
!assign new path passed to GLO:DataDir via remote procedure
pstrNewName = GLO:DataDir & '\' & LOC:File & LOC:Ext
!debug just in case
TRACE(pstrNewName)
!use internal GetSafeName function to create folder if it does not already exist
pstrNewName = GetSafeName(pstrNewName)
!Finally, force a return value of TRUE to activate new path change
RETURN TRUE
59
Program Setup access
Although there is no specific server procedure associated with this embed point, this area allows access to any setup
option that you need to execute (i.e. – data path setup):
!embed code to read from INI file.
DATAPATH = GETINI('Locations','DataPath','','.\People.ini')
IF DATAPATH <> ''
SETPATH(DATAPATH)
ELSE
PUTINI('Locations','DataPath','','.\People.ini')
END
BeforeOpen (called prior to the server opening the file)
BeforeOpen is called when the client application executes an OPEN command just before the server opens the file. If
BeforeOpen returns FALSE the target file is not opened.
Return Value: LONG
Implementation: Access to the BeforeOpen procedure is available in the IPServer application’s Before Open File Data
and Code embed points.
BeforeOpen( RemoteFile, sDrvString),LONG
RemoteFile
The label of a FILE structure included in the Data Manager DLL.
sDrvString
A string passed to the server side BeforeOpen procedure
Example:
BeforeOpen
PROCEDURE(FILE RemoteFile,STRING sDrvString)
ReturnValue
LONG
CODE
!Before Opening File
IF RemoteFile{Prop:Name} = ‘MyFile’
! do some work here
END
RETURN ReturnValue
60
Calling the Server-side Remote Procedure
The IP Driver provides support for executing code contained in your Data Manager DLL on the server. You accomplish
this using the SEND command in your IP Client application with the message parameter containing the string “IPEXEC ”.
The return value of the SEND command can be used to retrieve specific information from the Server DLL.
SEND Syntax to invoke the RemoteExecute() procedure
returnvalue = SEND(file,'IPEXEC stringValue')
file
the name of a file that is defined in the IPServer Data Manager DLL, which is used by the RemoteExecute
procedure
stringValue
a string value to be used in the RemoteExecute procedure.
When the SEND command is processed on the server the first 7 characters of the message parameter are checked, and
if the string “IPEXEC “ is found (including the space character) the RemoteExecute() procedure is called.
RemoteExecute() is passed a reference to the FILE and the stringValue beginning at position 8. The “IPEXEC “ is
stripped from the stringValue before its passed to the RemoteExecute() procedure.
NOTE: The SEND command for the IP Driver MUST be called AFTER THE TABLE IS OPENED, and not before.
The RemoteExecute() procedure allows the developer to execute code on the server and return a string value
(returnvalue variable) back to the client application.
61
RemoteExecute(RemoteFile, RemoteCommand)
RemoteFile a reference to the FILE parameter of the SEND command
RemoteCommand
process.
A STRING constant or variable passed to the procedure used as a condition or parameter to
Return Value: STRING (2048)
RemoteExecute receives the message parameter from the SEND command with the “IPEXEC “ string removed, and the
remaining string contents clipped and left justified.
The code you embed in the RemoteExecute procedure receives a reference to the FILE and the passed
RemoteCommand value.
To return a value to the client, the developer must set the value of the ReturnValue variable declared in the
RemoteExecute procedure.
Implementation: Access to the RemoteExecute procedure is available in the IPServer application’s Remote Execute
Procedure Data and Code embed points.
Example:
!Client sends the date to the server to determine if the data file needs
! to be backed up
SEND(MyImportantFile, ‘IPEXEC ’ & GLO:LoginDate)
62
IPDRV Extended Server Embeds
If you are using the IRDRV Extended Server Global Extension to perform file transfers, remote procedure calls, or runtime
filename changes, there are three new embed points that are added to the Data Manager application:
IPEXEC Dispatch Procedure
The IPEXEC Dispatch procedure is used by the Data Manager application to parse an incoming RemoteString sent by the
Client application and searching for the function name and the parameters and then call the correct IPEXEC Procedure.
After parsing, it looks for a valid procedure to execute. These procedures are those that are built in to the extended server
templates, or those that you have registered as remote procedures. If you are hand coding a remote call from the client,
you can use this embed point to launch the appropriate procedure.
Example:
IF lParTotal
TRACE('IPEXECDispatch Total Param:'&lParTotal&'|
Param1='&UPPER(UNQUOTE(sMsg[(lParStart[1]):(lParEnd[1])])))
CASE UPPER(UNQUOTE(sMsg[(lParStart[1]):(lParEnd[1])]))
OF 'IPGETRMT'
RETURN CLIP(GLO_FileName:IPRemoteFile)
OF 'IPGETNAME'
RETURN CLIP(IPGetFileName(UNQUOTE(sMsg[(lParStart[2]):(lParEnd[2])])))
OF 'IPCHNAME' !Built-in procedure
IPSetFileName(UNQUOTE(sMsg[(lParStart[2]):(lParEnd[2])]),UNQUOTE(sMsg[(lParStart[3]):(lParEnd[3])]))
OF 'SAYHELLO' !Custom Remote Procedure
RETURN SayHello(UNQUOTE(sMsg[(lParStart[2]):(lParEnd[2])]),|
UNQUOTE(sMsg[(lParStart[3]):(lParEnd[3])]),|
UNQUOTE(sMsg[(lParStart[20]):(lParEnd[21])]))
ELSE
!Call your custom procedure here
END
63
IPSetFilename Procedure
The IPSetFileName Procedure is called any time the Client application sends a Change FileName request to the server.
In the appropriate embed point of the client application, you can issue a SEND command from the Client and control your
target file name here.
Example:
IPSetFileName PROCEDURE(STRING FileLabel,STRING RemoteFileName)
CODE
TRACE('IPSetFileName FileLabel='&FileLabel&' RemoteFileName='&RemoteFileName)
CASE UPPER(FileLabel)
OF 'IPREMOTEFILE'
GLO_FileName:IPRemoteFile = GetSafeName(RemoteFileName)
ELSE
TRACE('IPSetFileName Unknown FileLabel='&FileLabel)
!Set a filename here – this is the embed point
END
IPGetFilename Procedure
The IPGetFileName Procedure is called any time the Client application sends a Get FileName request to the server. In the
appropriate embed point of the client application you can issue a SEND command from the Client and extract and process
your target file name here.
Example:
IPGetFileName PROCEDURE(STRING FileLabel)
CODE
TRACE('IPGetFileName FileLabel='&FileLabel)
CASE UPPER(FileLabel)
OF 'IPREMOTEFILE'
RETURN GLO_FileName:IPRemoteFile
ELSE
TRACE('IPGetFileName Unknown FileLabel='&FileLabel)
!Get a filename here – this is the embed point
END
64
Client-side Embeds and Procedures
If you have applied the IPDRV Extended Server Support extension template to your IP-enabled Client application, a
number of embeds are at your disposal to give you added control to a number of special actions:
File Transfer Embed Points
If you have added a file transfer template to a target window, the following embed points are available:
Each embed point allows you to add additional messaging or processing during a particular transfer action. Each action is
summarized briefly below. See the IPDriver Class Library Reference section in this PDF for more information.
Aborted
Indicates that an error occurred that halted the transfer process
Cancel
Indicates that the program user has halted the transfer process
Finish
Indicates that the transfer process was completed successfully
Pause
Indicates that the user has stopped the transfer temporarily.
Start
Begins the actual transfer process
StartTimer
Sets the TIMER attribute of the target window.
StopTimer
Clear the TIMER attribute of the target window
SwapPauseText
Performs the logic of swapping the text of the transfer control button when a pause action is detected.
65
Advanced Server Support
This section documents two important server side features of the IP Driver. These features are design to streamline and
enhance the speed and power of your IP Client applications.
Multiple Request Packet (MRP) support for ADD, APPEND, NEXT and PREVIOUS
statements
An IP packet is a chunk of data transferred over the Internet using standard Internet protocol (IP). Each packet begins
with a header containing addressing and system control information. IP packets vary in length depending on the data
being transmitted.
Version 2 of the IP Driver now has the ability to create Multiple Request Packets (MRP), defined as a single IP packet that
contains multiple requests for information. Version 2 of the IP Server now has the ability to process MRPs containing
multiple requests from the IP Client application.
The use of MRPs is designed for the acceleration of Browse procedures with LIST controls, by allowing them to be filled
using only one IP packet from the Server. Other possible uses could be with the Clarion In-Memory Database Driver (and
other drivers) to quickly add/append blocks of data (records) back to the server. The use and support of MRPs are built in
to all template based Browse procedures.
There is only one important rule to this usage of MRPs:
Any given MRP can only contain a single type of I/O statement.
In other words, you cannot mix NEXT, PREVIOUS, ADD or APPEND into one MRP. An MRP can only have a specific
number of I/O requests using only one of these statements per packet.
MRP Property:
The following property is used in the implementation of MRPs
IPRequestCount
entity{PROP:IPRequestCount} = number
entity
the label of a FILE or VIEW
number
the number of requests to be sent to the server in a single MRP. The maximum value is 1,000,000.
IPRequestCount is a read/write property that sets the number of requests to be sent to the server in a single MRP. The
server will then execute the specified number of statements, and return the results in an MRP packet to the client. If this
property is set to –1, the current packet is immediately sent. If this property is set to zero, the current packet is reset, and
nothing is sent to the server.
This property can also be used to determine how many records were actually read.
Example:
entity{PROP:IPRequestCount} = 20
NEXT(entity)
nRecNum = entity{PROP:IPRequestCount}
! create packet with 20 requests
! send packet to server with 20 NEXTs
! get number of records in MRP packet
66
The nRecNum value holds how many records were actually read from the database. We can use the nRecNum value
later to extract the information like this:
LOOP nRecNum TIMES
NEXT(entity)
! get cached record from received packet
IF ERRORCODE() <> 0
BREAK.
END
! add new record to list-box in Browse dialog
END
IPRequestCount should be used for each packet explicitly. Therefore if the user wants to send two MRP packets, then
the code will look like:
NEXT(entity)
!handle MRP packet
…
NEXT(entity)
!handle MRP packet
Finally, when an IP-enabled table contains MEMOs or BLOBs, you can improve the speed of the loading of browses and
reduce network traffic with the use of the NOMEMO statement.
The NOMEMO statement arms "memoless" record retrieval for the next GET, REGET, NEXT, or PREVIOUS statement
encountered. The following GET, REGET, NEXT, or PREVIOUS gets the record but does not get any associated MEMO
or BLOB field(s) for the record. Generally, this speeds up access to the record when the contents of the MEMO or BLOB
field(s) are not needed by the procedure.
Example:
CODE
...
NOMEMO(file)
file{PROP:IPRequestCount} = 1000
NEXT(file)
...
67
FAQs
How does the driver know when to request a new packet instead of reading from an already received packet?
When the IP Driver receives a packet from server, it initializes an internal counter with the number of records in the
packet. Each time the user issues a NEXT/PREVIOUS statement, the IP Driver checks the counter for 0, and
automatically determines whether to get the record from the received MRP packet, or decides it is time to send a new
request to the server.
If the packet received from the server contains less records than what was requested using IPRequestCount, then the
error code will be returned on the following NEXT/PREVIOUS, after the last record is read from the packet.
For example:
LOOP 20 TIMES
NEXT(entity)
! after 8 records, 9th NEXT sets error code
IF ERRORCODE() <> 0
BREAK
END
END
What if user receives a packet with 20 records from server, but did not issue 20 NEXT statements?
Data may be lost in this case. For example, let’s assume that after 5 NEXT statements, a BUILD statement is issued. In
this case, the IP Driver will free the last MRP packet and send a new request to the server with the BUILD statement. This
means that after the BUILD is issued, the user will not be able to read the other 15 records.
Error Handling
There are two methods that you can take to check for errors contained within an MRP packet. In the first method, check
immediately to see if the number of records in the packet matches the request, and if it does not, get the error right away.
The second method is to write your code as if you are not using an MRP. Here are two examples:
Method 1:
! check for any error immediately
NEXT(entity)
nRecNum = entity{PROP:IPRequestCount}
IF nRecNum < 20
nError = ERRORCODE()
END
LOOP nRecNum TIMES
NEXT(entity)
END
! test if error
IF nError <> 0
! handle error
END
! send packet to server
! get number of records
! save error code for later use
! get cached record from received packet
Method 2:
! check error as usual
entity{PROP:IPRequestCount} = 20 ! create packet with 20 requests
NEXT(entity)
! send packet to server
LOOP 20 TIMES
NEXT(entity)
! after 8 records, 9th NEXT sets error code
IF ERRORCODE() <> 0
BREAK
END
END
You can use whatever is more appropriate in a given situation.
68
MRP Conceptual Examples
The following section demonstrates a number of techniques when using MRPs. The support of MRPs are built in to all
template based browse procedures, but there may be occasions when you need to customize the handling of MRPs.
Example 1: How to create a packet with multiple ADD requests.
! prepare packet with 10 requests
LOOP 10 TIMES
! fill new record
…
ADD(entity) ! cache request in IP Driver, or
! send packet to server on 10th request
END
IF ERRORCODE()
! get number of requests actually sent to server
nSentRequests = entity{PROP:IPRequestCount}
! handle error
…
END
Example 2. How to send a packet immediately.
! step 1, prepare packet with 1000 requests
! add 7 records
LOOP 7 TIMES
! fill new record
…
ADD(entity) ! cache request in IP Driver
END
! step 2, send the current packet to server right now
entity{PROP:IPRequestCount} = -1
IF ERRORCODE()
! get number of actually sent requests to server
! handle error
…
END
Example 3. How to create a packet with an unknown number of requests.
! step 1, prepare packet with unknown number of requests
! MAX allowed number is 1,000,000,000
LOOP 1000000 TIMES
! obtain data from some source
IF ObtainDataFromOtherSource( ) <> 0
BREAK
END
! fill new record
…
APPEND(entity)
! cache request in IP Driver
END
! step 2, send packet to server right now
entity{PROP:IPRequestCount} = -1
IF ERRORCODE()
! get number of actually sent requests to server
! handle error
…
END
69
Example 4. How to kill the current packet.
a) Using property syntax:
! add 7 records
LOOP 7 TIMES
! fill new record
…
ADD(entity) ! step 2, cache request in IP Driver
END
! step 3, reset number of requests, will NOT send cached data, just deletes the packet
b) Kill the current packet by using another statement:
! add 7 records
LOOP 7 TIMES
! fill new record
…
ADD(entity)
! step 2, cache request in IP Driver
END
! step 3, issue any kind of statement other than on step 2
CLOSE(entity)
! doesn’t send cached data, deletes the packet, sends a close request
c) Kill the current packet by using a new packet request:
LOOP 7 TIMES
! step 2, fill new record
…
APPEND(entity)
! cache request in IP Driver
END
! step 3, initialize packet request number with the new value
entity{PROP:IPRequestCount} = 5 ! doesn’t send cached data, deletes the
LOOP 5 TIMES
! fill record
APPEND(entity)
! cache request in IP Driver, or
! send packet to server after 5th request
END
Example 5. How to create a packet with multiple NEXT requests.
LOOP 20 TIMES
! sends packet on 1st request and primes the record buffer with 1st record
! otherwise it reads the cached record
NEXT(entity)
IF ERRORCODE()
! handle error
…
BREAK
ELSE
! process the record from cache
…
END
END
old packet
70
Example 6. How to create a packet with multiple PREVIOUS requests.
PREVIOUS (entity)
! send packet to server and read 1st rec in to buffer
IF ERRORCODE()
! handle error
…
ELSE
! handle first record
…
! get number of remaining records
nReadRec = entity{PROP:IPRequestCount}
LOOP nReadRec TIMES
! get cached record from packet
PREVIOUS (entity)
! handle received record
…
END
END
Example 7. How to kill a received packet.
a) Using property syntax:
LOOP 100 TIMES
NEXT(entity) ! step 2, send packet for the 1st record, otherwise get cached record
IF ERRORCODE()
! handle error
…
ELSE
…
END
BREAK
END
! step 3, reset number of requests, delete cached packet
b) Using another statement:
LOOP 100 TIMES
NEXT(entity) ! step 2, send packet for the 1st record, otherwise get cached record
IF ERRORCODE()
! handle error
…
ELSE
…
END
BREAK
END
! step 3, issue any kind of statement other than on step 2
CLOSE(entity) ! delete cached data, send CLOSE request to server
71
c) Using a new packet request:
LOOP 100 TIMES
NEXT(entity)
! step 2, send packet on 1st record, otherwise get cached record
IF ERRORCODE()
! handle error
…
ELSE
…
END
BREAK
END
! step 3, initialize packet request number with the new value
entity{PROP:IPRequestCount} = 50 ! delete cached data, createnew MRP packet
PREVIOUS(entity)
! send new packet to server
Example 8. Adding NOMEMO support.
You can also add the NOMEMO statement to any IP-enabled table to defer the reading of any MEMOS when processing
MRPs:
Example:
CODE
…
NOMEMO(file)
File{PROP:IPRequestCount} = 1000
NEXT(file)
This results in a faster loading of selected browses, in addition to a reduction of network traffic.
72
Server Side VIEW support
A VIEW structure is defined in Clarion as a virtual file (or table). Just like a real table, a view consists of rows with
columns, and you can retrieve data from a view (and even update data in a view). The fields in the view’s virtual table are
the fields of one or more real tables defined in the dictionary. See the online help and specifically the VIEW topic for more
information.
VIEWs are used throughout the application templates in many ways. You can use views to join two tables in your
dictionary and present the underlying data as if the data were coming from a single table, thus simplifying the schema of
your database for users performing ad-hoc reporting. You can also use views as a security mechanism to restrict the data
available to end-users. Views can also aggregate data (particularly useful if you can take advantage of indexed views),
and help partition data. In this article we will look at these different types of view to see when we can take advantage of a
view for our application.
With this latest version of the IP Driver, as you open a VIEW, the structure information is sent to the server to be created
there. All processing of the VIEW, including the joining of tables and any filters applied, are now processed on the server.
Only the results that you need are sent back to the IP Client application. This results in a big improvement of speed and
performance in any part of your application that is using VIEWs (i.e., Browses and Reports).
The IP Extender templates, specifically the Remote Procedures that are used to set variables in the server can now be
used to set a variable that is in a filter on the server.
The Version 2 templates also allow you to set/get values of global variables in the server. There is also support to BIND
those variables in the server so they can be used in any server side filter.
Filtering Rules
All VIEW structures may be filtered. With server side VIEWs, the support for filtering with the IP Driver is virtually
automatic. Using the template based VIEWs in Browses and Reports, modifications required by the developer are
minimal.
Here is a detailed summary of filtering rules as they apply to server side VIEWs:
•
If a filter uses only dictionary based table fields, the RECORD structure is bound (BINDed) on both sides
automatically (IP Client and the IP Server Data Manager DLL).
•
If a filter uses local and/or global variables, these variables need to be bound (BINDed) in the IP Client application
(this is done automatically by the templates using the “AutoBind” option).
•
If a filter use hand coded variables, the variables need to be bound (BINDed) in the IP client application, by hand
coding with the BIND statement, or using the procedure template prompts.
•
If a filter uses any runtime library function (TODAY(), INSTRING(), etc.), no action is needed. The filter engine
automatically recognizes all runtime library functions.
•
If a filter uses any user defined function, this function need to be defined and bound (BINDed) in both IP client
application and the IP Server Data Manager DLL. The actual user defined function that will be executed is the one
located in the IP Server Data Manager DLL. The client function can optionally be an “stub” function.
If the IP client application does not BIND the function, the filter will be ignored. If the function is bound on the
client but not on the server, the NEXT statement will return an ERRORCODE 90, the FILEERRORCODE returns
“1011”, and the FILEERROR returned will be a standard “BIND error”.
73
IP Driver Class Library Reference
This section documents two classes that are used to provide additional functionality to the IP-enabled Client application
and its target Data Manager application.
Overview
The IP Driver has powerful logic built into the runtime library that helps you transfer data from a Data Manager to the IPenabled Client application via IP protocol. There are two classes that are also provided to allow additional functions to any
application.
The IPExtended Class is used to simplify remote procedure calls and runtime filename assignment between the IPenabled client application and the Data Manager.
The IPFileTransfer Class is used to simplify the transfer of files between the IP-enabled client application and the Data
Manager.
IPFileTransfer and IPExtender Class Source Files
The source code for the IPFileTransfer and IPExtender classes is installed by default to the Clarion \LIBSRC folder. The
source code and their respective components are contained in:
IPExtend.INC
IPExtend.CLW
Class declarations
Class method definitions
Template Support
A robust set of Extender templates are provided to allow easy implementation of these classes into your applications. See
the Extended Server Support Extension sections in this PDF for a detailed description of these template tools.
Essentially, global extensions in the IP-enabled Client application and the Data Manager (IP server) application include
the proper class derivations needed. Other templates implement the appropriate methods needed for file transfer, remote
procedure calls, and runtime filename modifications.
74
IPExtender methods:
There are four methods available in the IPExtender Class. The extender template will create a global object that
instantiates this class:
IPx
IPExtender
SetConnectionString (set OWNER attribute of IP file)
GetConnectionString (get OWNER attribute of IP file)
SetConnectionString(ConnectionString)
GetConnectionString()
ConnectionString
A string constant, variable, or EQUATE that contains the parameters to communicate with the IP
Data Server.
Normally, a connection string is the same as the IPDRV::OWNER global setting, but you can also modify the connection
string if necessary to attach to another Data Manager.
These methods are used to set and get that information. Connection information must be set before calling any other
method in this class.
Implementation:
SetConnectionString and GetConnectionString methods are called using the IPx object, when the extender template is
included in the IP-enabled Client application.
Example:
CODE
LOOP
! This method receive all EVENT:Accepted's
IF Looped
RETURN Level:Notify
ELSE
Looped = 1
END
CASE ACCEPTED()
OF ?SayHello
IPx.SetConnectionString(IPDRV::OWNER) !Set Connection before remote proc call
LOC:Message = IPx.Exec('SAYHELLO',LOC:Name,,,,,,,,,,,,,,,,,,,)
MESSAGE(LOC:Message,'Value Returned From IPDRV')
END
75
Exec(call a remote procedure)
Exec(RemoteProcedureName,<parameter1>…<parameter20>) ,<returnvalue>
RemoteProcedureName
A string constant that identifies the name of a remote procedure that is defined in the
target Data Manager.
Parameters
A string constant, variable, or EQUATE that identifies up to 20 possible parameters to
pass to the remote procedure.
Returnvalue
If the remote procedure defined on the Data Manager returns a value, return value is a
string that is returned to the IP-enabled Client application
The Exec method calls a remote procedure in the Data Manager. It internally executes a SEND command that is parsed
by the Data Manager, and executes the remote procedure (if it exists in the Data Manager) and returns a return value (if it
exists).
The parameter count will stop with the first omitted parameter, because there is no way to differentiate between an
omitted parameter and a null parameter. Therefore, if you call IPx.Exec('MyProc',1,2,3,,5) is it equivalent to
IPx.Exec('MyProc',1,2,3). If you need the 4th parameter, use IPx.Exec('MyProc',1,2,3,'',5). To use a single quote, you
should use a double single quote.
Implementation:
The Exec method is called using the IPx object, when the extender template is included in the IP-enabled Client
application.
Example:
CODE
LOOP
IF Looped
RETURN Level:Notify
ELSE
Looped = 1
END
CASE ACCEPTED()
OF ?SayHello
END
76
SetFileName (change remote file name)
GetFilename (read remote file name)
SetFileName(FileLabel, RemoteFileName)
GetFileName(FileLabel)
FileLabel
A label of the file that is located on the IP Data Server and defined by the Data Manager
RemoteFileName
A string constant, variable, or equate containing the new name of the target FileLabel.
SetFileName is a client side method that changes the name of the target file in the Data Manager.
GetFilename is a client side method that returns the value of a target file located in the Data Manager.
Implementation:
SetFileName should always be called after the SetConnectionString method and just prior to opening the file. The
GetFileName method can be called after the file is opened to retrieve and verify the active file’s name and location.
Example:
ThisWindow.Init PROCEDURE
ReturnValue
BYTE,AUTO
CODE
GlobalErrors.SetProcedureName('Main')
SELF.Request = GlobalRequest
! Store the incoming request
ReturnValue = PARENT.Init()
IF ReturnValue THEN RETURN ReturnValue.
SELF.FirstField = 1
SELF.VCRRequest &= VCRRequest
SELF.Errors &= GlobalErrors
! Set this windows ErrorManager to the global ErrorManager
SELF.AddItem(Toolbar)
CLEAR(GlobalRequest)
! Clear GlobalRequest after storing locally
CLEAR(GlobalResponse)
IPx.SetConnectionString(IPDRV::OWNER)
IPx.SetFileName('people',GLO:PeopleName)
Relate:people.Open
!File people used by this procedure,
!so make sure it's RelationManager is open
SELF.FilesOpened = True
SELF.Open(AppFrame)
! Open window
Do DefineListboxStyle
SELF.SetAlerts()
RETURN ReturnValue
77
SetRemoteVariable (change remote variable)
GetRemoteVariable (read remote variable)
SetRemoteVariable (VariableLabel, VariableValue)
GetRemoteVariable (VariableLabel),STRING
VariableLabel
The label of the variable that is located on the IP Data Server and defined by the Data Manager
VariableValue
A string constant, variable, or equate containing the new value of the target VariableLabel.
SetRemoteVariable is a client side method that changes the name of the target variable in the Data Manager.
GetRemoteVariable is a client side method that returns the value of a target variable located in the Data Manager.
Implementation:
SetRemoteVariable should always be called after the target variable has been initialized. The GetRemoteVariable
method can be called after the variable has been initialized to retrieve and verify its contents.
Return Value:
The GetRemoteVariable method returns a STRING
Example:
ReturnValue
BYTE,AUTO
CODE
GlobalErrors.SetProcedureName('Main')
SELF.FirstField = 1
IPx.SetFileName('people',GLO:PeopleName)
Relate:people.Open
!File people used by this procedure,
!so make sure it's RelationManager is open
SELF.FilesOpened = True
SELF.Open(AppFrame)
! Open window
SELF.SetAlerts()
RETURN ReturnValue
78
IsAlive (is the IP Server connection active?)
IsAlive( ), BYTE
The IsAlive method is used to detect if an IP Server connection to the target Data Manager is active. If active, the method
returns one (1), and if inactive, the method returns zero (0).
Implementation:
You can call this method at any time in the application to detect if a connection to the IP Server has been lost. This may
occur due to a loss in the IP connection, a server timeout, or all tables have been closed, and a persistent connection is
not active. A persistent connection is established by the SetKeepAlive method.
Return Value: BYTE
Example:
ThisWindow.TakeWindowEvent PROCEDURE
ReturnValue
BYTE,AUTO
Looped BYTE
CODE
LOOP
! This method receives all window specific events
IF Looped
RETURN Level:Notify
ELSE
Looped = 1
END
ReturnValue = PARENT.TakeWindowEvent()
CASE EVENT()
OF EVENT:GainFocus
IF NOT IPx.IsAlive()
DISABLE(?tbAccounts)
MESSAGE('The server time out|Select a new Ledger year to continue.','Attention')
END
END
RETURN ReturnValue
END
ReturnValue = Level:Fatal
RETURN ReturnValue
NOTE: THIS METHOD IS ALSO DUPLICATED IN THE IPFILETRANSFER CLASS.
See Also: SetKeepAlive
CloseConnection (close internal Server connection)
CloseConnection( )
The CloseConnection method is used to close an internal file used by the IPExtender or IPFileTransfer class, which is
maintaining a persistent connection with the Server Data Manager.
Implementation:
You can call this method at any time in the application to prepare to disconnect from the server Data Manager. The
connection will be closed only after all other tables are closed in your application, or the Client application itself is closed.
This method is useful and necessary when an error has occurred in a particular table connection, and you wish to shut
down and restart the connection again without closing the Client application.
NOTE: THIS METHOD IS ALSO DUPLICATED IN THE IPFILETRANSFER CLASS.
79
SetKeepAlive (activate internal KeepAlive mode)
SetKeepAlive(flag)
flag
A BYTE value that controls an internal KeepAlive setting.
The SetKeepAlive method is used to activate a persistent connection between the Client application and Server Data
Manager. It does this by keeping an internal table opened in the Data Manager. The end result is that all tables in your
Client application may be closed, but a connection is maintained with the Data Manager until the program is closed, the
CloseConnection method is called, or the Server has simply timed out.
Implementation:
When using the supporting Client IPDRV Extended Options template, the internal KeepAlive internal flag is defaulted to
ON. You should only need to call the SetKeepAlive method to explicitly turn off the persistent connection to the server.
The KeepAlive setting is only necessary if you are using an IPExtender object to set a global variable, call any
RemoteProcedure or activate any FileTransfer options. In a normal IP Client application not using the Extender Class, this
method is not needed and the application will close the server connection when there are no more files open.
Any IP Client application that uses variable file names, or anything that needs to be persistent in the server throughout the
application’s life, will need to set the internal KeepAlive flag to True (the default).
Note: Even with the KeepAlive mode active, an application will disconnect from the Server after a specified period of
client inactivity (whose value is set in the Remote Administrator).
NOTE: THIS METHOD IS DUPLICATED IN THE IPFILETRANSFER CLASS.
Example:
CODE
GlobalErrors.Init(GlobalErrorStatus)
INIMgr.Init('Ledger.INI', NVD_INI)
! Configure INIManager to use INI file
DctInit
IPDRV::OWNER = 'Ledger\IP_Ledger.DLL'&'@'&'localhost'&':'&'2339'
IPx.SetKeepAlive(False)
IPx.SetFileName('Year','YEAR.TPS')
SystemParametersInfo (38, 0, lCurrentFDSetting, 0)
! Configure frame dragging
IF lCurrentFDSetting = 1
SystemParametersInfo (37, 0, lAdjFDSetting, 3)
END
Main
INIMgr.Update
IF lCurrentFDSetting = 1
SystemParametersInfo (37, 1, lAdjFDSetting, 3)
END
INIMgr.Kill
See Also:
IsAlive
80
IPFileTransfer Methods
The IPFileTransfer Class contains a comprehensive set of methods that simply the process of transferring files with IPenabled applications. The IPTransferFileCode and IPTransferFileControl templates create a local object that
instantiates this class:
IPTransfer CLASS(IPFileTransfer)
END
SetConnectionString (set OWNER attribute of IP file)
GetConnectionString (get OWNER attribute of IP file)
SetConnectionString(ConnectionString)
GetConnectionString()
ConnectionString
A string constant, variable, or EQUATE that contains the parameters to communicate with the IP
Data Server.
Normally, a connection string is the same as the IPDRV::OWNER global setting, but you can also modify the connection
string if necessary to attach to another Data Manager.
These methods are used to set and get that information. Connection information must be set before calling any other
method in this class.
Implementation:
SetConnectionString and GetConnectionString methods are called using the IPTransfer object, when the appropriate
template is included in the IP-enabled Client application.
Example:
CODE
LOOP
IF Looped
RETURN Level:Notify
ELSE
Looped = 1
END
CASE ACCEPTED()
OF ?SayHello
END
81
SetSourceFileName(Set the source file name)
SetTargetFileName(Set the target file name)
GetRemoteFileName(Get the Remote File Name)
SetSourceFileName(SourceFileName)
SetTargetFileName(TargetFileName)
GetRemoteFileName()
SourceFileName
TargetFileName
A string constant or variable that identifies the name of the file to transfer.
A string constant or variable that identifies the destination of the file transfer.
SetSourceFileName sets the file name that will be transferred. The SetTargetFileName method sets the destination file
name that will receive the transfer. GetRemoteFileName is used to return the actual file name and path that is located on
the IP Data Server.
Source and destination locations are dependant upon the direction of transfer. The SourceFileName will be located on the
Client application when a SEND operation is executed, and located on the server in the event of a RECEIVE.
Implementation:
The SetSourceFileName and SetTargetFileName methods are called by other IPTransfer methods that initialize SEND
and RECEIVE transfer operations(i.e., InitSend, InitReceive, Send, Receive)
Example:
IPFileTransfer.InitSend PROCEDURE(STRING pSourceFileName,<STRING pTargetFileName>,LONG TransferIndex=0)
CODE
IF SELF.ProgressStatus = IPTransferNone
SELF.SetSourceFileName(pSourceFileName)
IF OMITTED(3) OR CLIP(pTargetFileName)=''
SELF.SetTargetFileName(pSourceFileName)
ELSE
SELF.SetTargetFileName(pTargetFileName)
END
SELF.InitSend(TransferIndex)
END
SetControls(Set pause and progress controls)
SetControls(ProgressControl,PauseControl,CancelControl)
ProgressControl
PauseControl
CancelControl
An unsigned integer that identifies the field equate number of a valid progress control used in the
transfer process.
An unsigned integer that identifies the field equate number of a valid pause button control used in
the transfer process.
An unsigned integer that identifies the field equate number of a valid cancel button control used in
The SetControls method is used to pass valid field equates to the other class methods If the class will be used with a
progress, pause and cancels controls.
Example:
IPFileTransfer.Init PROCEDURE(BYTE pAction,UNSIGNED pProgressControl,|
UNSIGNED pStartPauseControl,UNSIGNED pCancelControl)
CODE
SELF.SetError('')
SELF.Init(pAction)
SELF.SetControls(pProgressControl,pStartPauseControl,pCancelControl)
82
Init(Initialize the class)
Init(action)
Init(action, ProgressControl,PauseControl,CancelControl)
Action
ProgressControl
PauseControl
CancelControl
A BYTE value that identifies the direction of the imminent file transfer. A value of one (1 )
indicates a SEND action, and a value of two (2) indicates a RECEIVE action.
An unsigned integer that identifies the field equate number of a valid progress control used in the
transfer process.
An unsigned integer that identifies the field equate number of a valid pause button control used in
An unsigned integer that identifies the field equate number of a valid cancel button control used in
The Init method is used to initialize the appropriate IPFileTransfer class methods prior to starting any transfer. If the Init
method is called without passing the appropriate control equates, this implies that the transfer will be done without any
end user control. An overloaded method to initialize the class and assign the controls at the same time allows end user
interaction during the transfer process.
Example:
ReturnValue
BYTE,AUTO
CODE
GlobalErrors.SetProcedureName('TransferFileSend')
SELF.FirstField = ?LOC:FileName:Prompt
SELF.AddItem(?Close,RequestCancelled) ! Add the close control to the window amanger
SELF.Open(Window)
! Open window
IPTransfer.SetConnectionString(IPDRV::OWNER)
IPTransfer.Init(IPTransferSend,?Progress:Thermometer,?Transfer,?CancelTransfer)
IPTransfer.SetAllowPause(True,'Pause')
FileLookup1.Init
FileLookup1.ClearOnCancel = True
FileLookup1.Flags=BOR(FileLookup1.Flags,FILE:LongName)
! Allow long filenames
FileLookup1.SetMask('All Files','*.*')
! Set the file mask
SELF.SetAlerts()
RETURN ReturnValue
83
SetSilent(set visible error message)
GetSilent(get the silent error state)
SetSilent( value )
GetSilent ()
value
A BYTE value that sets the visible error mode. If the value is set to FALSE (0 – the default) a message will popup
if any error happens during the transfer process. If value is set to TRUE the process will stop without posting any
visible errors.
SetSilent sets the error display mode during the transfer process. The GetSilent method is used to retrieve the error
state prior to the transfer process. If the silent mode is active, the appropriate GetError or GetErrorCode methods can be
retrieved later for additional processing.
Implementation:
The silent mode if off by default. If you wish to override this, use the appropriate embed point to activate the silent error
mode.
84
InitSend(begin the SEND process)
InitSend ( TransferIndex)
InitSend (SourceFileName, TargetFileName, TransferIndex)
TransferIndex
SourceFileName
TargetFileName
A LONG value that is used to omit a specific number of bytes from the source before sending.
The default value is zero (0).
The InitSend method starts the SEND process. The SEND process always transfers the SourceFileName from the Client
to the Server. The overloaded InitSend method is used to initialize the send process and at the same time set the source
and target file name. If the TransferIndex value is not 0 the first TransferIndex bytes of the file will be omitted in the send
process.
Implementation:
InitSend is used to begin the file transfer process from client application to the IP Data Server designated location.
Example:
ThisWindow.TakeAccepted PROCEDURE
ReturnValue
BYTE,AUTO
Looped BYTE
CODE
LOOP
IF Looped
RETURN Level:Notify
ELSE
Looped = 1
END
CASE ACCEPTED()
OF ?Transfer
IpTransfer.InitSend(LOC:FileName,LOC:TargetName)
END
ReturnValue = PARENT.TakeAccepted()
CASE ACCEPTED()
OF ?LookupFile
ThisWindow.Update
LOC:FileName = FileLookup1.Ask(1)
DISPLAY
LOC:TargetName = LOC:FileName
END
RETURN ReturnValue
END
RETURN ReturnValue
85
InitReceive(begin the RECEIVE process)
InitReceive ( TransferIndex)
InitReceive (SourceFileName, TargetFileName, TransferIndex)
TransferIndex
SourceFileName
TargetFileName
The InitReceive method starts the RECEIVE process. The RECEIVE process always transfers the SourceFileName from
the Server side to the Client application location. The overloaded InitReceive method is used to initialize the receive
process and at the same time set the source and target file name. If the TransferIndex value is not 0 the first
TransferIndex bytes of the file will be omitted in the receive process.
Implementation:
InitReceive is used to begin the file transfer process from IP Data Server to the client application’s designated location.
Example:
ThisWindow.TakeAccepted PROCEDURE
ReturnValue
BYTE,AUTO
Looped BYTE
CODE
LOOP
IF Looped
RETURN Level:Notify
ELSE
Looped = 1
END
CASE ACCEPTED()
OF ?Transfer
IpTransfer.InitReceive(LOC:FileName,LOC:TargetName)
END
ReturnValue = PARENT.TakeAccepted()
CASE ACCEPTED()
OF ?LookupFile
ThisWindow.Update
LOC:FileName = FileLookup1.Ask(1)
DISPLAY
LOC:TargetName = LOC:FileName
END
RETURN ReturnValue
END
RETURN ReturnValue
86
TakeEvent(monitor transfer process)
TakeEvent()
The TakeEvent method will monitor the status of the class and execute the corresponding action if the window ACCEPT
loop is the choice of transfer implementation. This allows a user to better monitor and control a file transfer, andd provide
them with a progress control, pause and cancel buttons. The alternative is to use an internal loop that is contained in the
class.
Implementation:
The TakeEvent method is called within the standard TakeEvent method of the Window Manager.
Example:
ThisWindow.TakeEvent PROCEDURE
ReturnValue
BYTE,AUTO
Looped BYTE
CODE
LOOP
IF Looped
RETURN Level:Notify
ELSE
Looped = 1
END
IPTransfer.TakeEvent()
ReturnValue = PARENT.TakeEvent()
RETURN ReturnValue
END
RETURN ReturnValue
! This method receives all events
87
Start(transfer started)
Pause(transfer paused)
Cancel(transfer cancelled)
Aborted(transfer aborted)
Finish(transfer finished)
Start(TransferIndex)
Pause()
Cancel()
Aborted()
Finish()
TransferIndex
A LONG value that is used to omit a specific number of bytes from the source before sending. The default
value is zero (0).
Start, Pause, Cancel, Aborted, and Finish are virtual methods that are called when the corresponding action is
executed. Embed points are available through the template interface to allow you to add additional messaging or
processes as needed. See the Client-side Embeds and Procedures section for more information.
Send(begin internal SEND)
Send ( TransferIndex)
Send (SourceFileName, TargetFileName, TransferIndex)
TransferIndex
SourceFileName
TargetFileName
The Send method starts the SEND process. The SEND process always transfers the SourceFileName from the Client to
the Server. The overloaded Send method is used to initialize the send process and at the same time set the source and
target file name. If the TransferIndex value is not 0 the first TransferIndex bytes of the file will be omitted in the send
process.
Implementation:
Send is similar to the InitSend method, but uses an internal loop to perform the transfer. No user interaction is available.
Receive(begin internal RECEIVE)
Receive ( TransferIndex)
Receive (SourceFileName, TargetFileName, TransferIndex)
TransferIndex
SourceFileName
TargetFileName
The Receive method starts the RECEIVE process. The RECEIVE process always transfers the SourceFileName from the
Server side to the Client application location. The overloaded Receive method is used to initialize the receive process
and at the same time set the source and target file name. If the TransferIndex value is not 0 the first TransferIndex bytes
of the file will be omitted in the receive process.
Implementation:
Receive is similar to the InitReceive method, but uses an internal loop to perform the transfer. No user interaction is
available.
88
GetErrorCode(get transfer errorcode)
GetError(get transfer error)
GetErrorCode( )
GetError( )
The GetErrorCode and GetError methods are used to return the respective ERRORCODE or ERROR that was posted if
an error occurred during the send or receive process.
Implementation:
Any errors encountered during the transfer process are saved internally by the IPFileTransfer class. By using these
methods, any errors stored can be read if needed.
Example:
IPFileTransfer.Start
PROCEDURE(LONG TransferIndex=0)
CODE
IF SELF.Action = IPTransferSend
SELF.SourceFile &= IPLocalFile
SELF.TargetFile &= IPRemoteFile
ELSIF SELF.Action = IPTransferReceive
SELF.SourceFile &= IPRemoteFile
SELF.TargetFile &= IPLocalFile
END
SELF.SourceRecord &= SELF.SourceFile{PROP:Record}
SELF.SourceBuffer &= WHAT(SELF.SourceRecord,1)
SELF.TargetRecord &= SELF.TargetFile{PROP:Record}
SELF.TargetBuffer &= WHAT(SELF.TargetRecord,1)
OPEN(SELF.SourceFile,40h)
SELF.SetError('Source')
IF SELF.GetErrorCode()
SELF.Aborted()
RETURN
END
SetBuffersPerCycle (set buffers read per cycle)
GetBuffersPerCycle (get buffers read per cycle)
SetBuffersPerCycle(value)
GetBuffersPerCycle()
value
A BYTE value that sets the number of buffers read per cycle. The default value is five (5).
During every file transfer process, there are two LOOP structures. The outer LOOP is used to control the window
responsiveness during the transfer process, while the second loop controls how many fixed buffers are read per cycle.
The fixed buffer size is 64K less 512 bytes (65024).
Implementation:
Use these methods to set and get the number of buffers read per cycle. You can fine-tune your window response with the
amount of data transferred per cycle. For larger file transfers you should increase this setting.
Example:
IPFileTransfer.Init
PROCEDURE(BYTE pAction)
CODE
SELF.SetBuffersPerCycle(5)
SELF.SetControls(0,0,0)
SELF.Action = pAction!Must be IPTransferSend OR IPTransferReceive
89
SetTimer(set transfer interval)
GetTimer(get transfer Interval)
SetTimer(value)
GetTimer()
value
A LONG value that sets the TIMER attribute of the WINDOW used in the transfer process. The default value set
by the class is ten (10).
The SetTimer/GetTimer methods are used to query and set the TIMER attribute on a WINDOW that has the file transfer
controls populated. When using the window ACCEPT loop, the timer value can be changed. The larger the value, the
more responsive will the window be, but the whole file transfer process will take longer.
Implementation:
Use these methods to control the responsiveness of the end user in controlling the file transfer controls. SetTimer should
be set prior to opening the window.
Example:
IPFileTransfer.Construct
PROCEDURE
CODE
SELF.Extender &= NEW(IPExtender)
SELF.ProgressStatus = IPTransferNone
SELF.SourceFileOpen = False
SELF.TargetFileOpen = False
SELF.SetTimer(10)
SELF.Silent = False
90
SetAllowPause(set transfer pause action)
GetAllowPause(get transfer pause action)
SetAllowPause(AllowPause,PauseText)
GetAllowPause()
AllowPause
PauseText
A BYTE value that when set to TRUE (1), allows pausing the file transfer process
A string constant or variable that contains text to substitute on the target pause control when the pause
action is active.
When using the window ACCEPT loop (transfers using the InitSend or InitReceive methods) the process can also
support pausing the file transfer at any time, and later restarting it. The SetAllowPause method sets the pause capability.
Optional text to the target pause control will be applied when the pause action is active.
Implementation:
SetAllowPause is set in the WindowManager.Init method to activate the pause activity.
Example:
ReturnValue
BYTE,AUTO
CODE
GlobalErrors.SetProcedureName('TransferFileSend')
SELF.FirstField = ?LOC:FileName:Prompt
SELF.AddItem(?Close,RequestCancelled) ! Add the close control to the window amanger
SELF.Open(Window)
! Open window
IPTransfer.SetConnectionString(IPDRV::OWNER)
IPTransfer.Init(IPTransferSend,?Progress:Thermometer,?Transfer,?CancelTransfer)
IPTransfer.SetAllowPause(True,'Pause')
FileLookup1.Init
FileLookup1.ClearOnCancel = True
FileLookup1.Flags=BOR(FileLookup1.Flags,FILE:LongName)
! Allow long filenames
FileLookup1.SetMask('All Files','*.*')
! Set the file mask
SELF.SetAlerts()
RETURN ReturnValue
GetAction(get the transfer action)
GetAction()
The GetAction method returns a byte value that indicates what type of file transfer action is being executed. A value of
one (1) indicates a client to server SEND action. A value of two (2) indicates a server to client RECEIVE action.
SwapPauseText(transfer control text)
StartTimer(transfer interval started)
StopTimer(transfer interval stopped)
SwapPauseText ()
StartTimer()
StopTimer()
These virtual methods are called internally, and can be used during the transfer to monitor the progress or the
corresponding action.
Implementation:
SwapPauseText performs the text substitution when a pause action is detected.
StartTimer is used to reset the TIMER attribute of the target WINDOW.
StopTimer is used to completely clear the window of any TIMER attribute.
91
92
Error Codes and Error Trapping
There are two types of errors that the IP driver might report; standard Clarion errors as listed in ERRORS.CLW, and
communication errors. In both cases ERROR() and ERRORCODE() can be used to check for an error, but in the case of
a communication error ERRRORCODE() is set to 90, and you must check the FILEERROR() and FILEERRORCODE()
functions to retrieve the extended error information from the driver.
FILERRROR() returns the associated message text about the error. Here is a list of possible extended FileErrorCodes
that may be returned:
Condition
ACCESS DENIED
OBJECT NOT FOUND
FUNCTION NOT SUPPORTED
UKNOWN COMMAND
INVALID PACKET
INTERNAL ERROR
INVALID DATAMANAGER DLL
MISSING PARAMETER
TIMEOUT ON OPERATION
TABLE OPERATION FAILED
ADMIN RIGHTS REQUIRED
READ ONLY OBJECT
BUILD() IN PROGRESS
INVALID REQUEST
ADMIN CONNECTION ALREADY ACTIVE
INVALID PASSWORD
DELETE OF SYSTEM OBJECT FAILED
DELETE OF LOCKED OBJECT FAILED
INVALID USER NAME
INVALID OBJECT
TOO MANY OPENED SESSIONS
NEW SESSIONS DISABLED
HANDSHAKE FAILED
SOCKET CONNECTION FAILED
FileErrorCode
1
2
3
5
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
23
25
26
29
30
Socket Errors
The most common error will likely be a socket error in the event of lost communications.
Socket errors can be caused by a problem on the client, the server, or by a problem on the network itself.
The better prepared your application is for any error, the more gracefully you'll handle it, and the easier you'll make your
job.
Here are some handy links to help you evaluate a socket error when encountered.
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winsock/winsock/windows_sockets_error_codes_2.asp
http://www.sockets.com/err_lst1.htm - ErrorsInNumericOrder
93
Common Errors
Here is a short list of some common errors that you may encounter during the development cycle:
ERRORCODE (9) "Data Manager Not Found"
Data Manager is wrong. The Data Manager name passed by the Client application is not recognized by the IP Data
Server.
ERRORCODE (18) "Invalid User Password"
Password is set incorrectly.
ERRORCODE (21) "Unknown User Name"
User name is set incorrectly.
ERRORCODE (28) "Error: User Permissions not found"
The supplied User name & Password is correct, but Table Permissions are not set in the Remote Administrator.
ERRORCODE (30) "Socket Error 10054"
The Data Manager DLL is linked incorrectly (e.g. Local mode), or is missing a dependent DLL or for some other reason is
invalid.
Port number is wrong.
Host Name is wrong (irresolvable).
94
Detecting an invalid connection to the IP Data Server
people FILE,DRIVER('IPDRV'),PRE(PEO),CREATE,BINDABLE,THREAD,OWNER(IPDRV::OWNER)
KeyId
KeyLastName KEY(PEO:LastName),DUP,NOCASE
Record
RECORD,PRE()
Id
LONG
FirstName
STRING(30)
LastName
STRING(30)
Gender
STRING(1)
END
END
Code
IPDRV::OWNER = 'ip_people.dll'&'@'&'localhost'&':'&'2339'
The table is attempted to be opened, the code checks for extended FILEERRORCODE() 30 to verify whether the problem
is that the IP Data Server connection failed any reason:
OPEN(People)
IF Errorcode() = 90 AND FILEERRORCODE() = 30
MESSAGE('Unable to establish connection to IP Data Server,'Connection Error')
END
CLOSE(People)
This code above attempts to open the People file on the remote server and traps for the extended ERRORCODE 90 and
associated FILEERRORCODE 30.
To verify that the SoftVelocity IP Data Driver Service is started:
Open Control Panel > Administrative Tools > Services:
The ports used by the server are specified in the INI file Claipsrv.ini located in the root directory of the IP data server.
Typical contents of Claipsrv.ini
[REQUESTER]
PORT=2339
PORT_SSL=2340
Server Ports
To change the ports the data server uses, go to your system Services program and stop the SoftVelocity IP Data Driver
service, then edit the port numbers and restart the SoftVelocity IP Data Driver service.
The SoftVelocity IP Data Driver Service should be set to run on the Local System account and the Allow service to
interact with desktop option should be checked.
95
96
UNC support for the SoftVelocity IP Data Server Service
This section describes an alternate configuration for the SoftVelocity IP Data Server service.
By default, most Windows services run under a LocalService account, which does not have access to the network. By
default, the SoftVelocity IP Data Server service is installed under the LocalService account. If you need to use UNC
(Uniform Naming Convention, i.e., \\server\share\directory\program.exe) to access remote files on the network, you will
need to set the user account under which the service runs to an account that has access to the network.
In order to run a system service correctly using a user account, you must manually set the user account to have the "Log
on as a service" right. The method of doing this varies between versions of Windows NT and Windows 2000/XP/2003.
In the Services Control Panel, change the account of the IP Data Server service so that it is running under “your” account
instead of "Local System". Next, go to the System Security Policy editor in the Control Panel and make sure your account
has "Log on as a service" rights.
Your on-line help file has a special Flash movie that describes this setup in greater detail.
A note about Mapped Drives
A service shouldn't access local or network resources through mapped drive letters. Your IP Data Manager is executed by
the IP Server service and so it runs in a different security context. A service should only access a remote resource using
the Universal Naming Convention (UNC) name to access the resource.
97
Remote Administration Application (RMAdmin)
NOTE: In order to run the Remote Administrator Console you must have the Java SDK or JRE version 1.4 or
greater installed on your development machine.
The RMadmin console can be run from any machine capable of running a Java application, just copy the rmadmin.jar file
to the machine and double-click on it to launch it.
When initially installed use the following information to log into the RMadmin console:
User Name: Administrator
Password: <leave the password blank>
The first time you log in to the console use User name of Administrator, and leave the Password empty. After your initial
login, you can specify a password for the Administrator account.
Main Menu contains all primary commands and functions of the Remote Administrator Console
Toolbar contains graphical buttons to the most commonly used commands
Tree View Pane on the left side of the window groups different function levels.
Details View Pane on the right-hand side of the window lists detailed information for the selected function level
Status Bar to display session status
Popup menus contain the list of available commands for the selected element.
98
Main Menu
The main menu contains the following items/sub-items
Connection
Connect to IP Data Server
Refresh
Refresh Speed
Exit
establish a new connection from the RMAdmin with a Clarion IP Data Server
(see Connection to server dialog for details)
refresh the displayed data
provides possibility to choose the refresh mode
Actions
Sessions
CREATE Table(s)
BUILD Keys for Table(s)
menu item contains submenu with session related operations (Close Sessions,
Force Close Sessions, Prevent New Sessions, Allow New Sessions, Close
All Sessions)
create the physical file(s) for selected table(s)
build/rebuild keys for the selected table
Tools
Accounts
contains a submenu that provides user account related operations: (Add New
Account, Modify Account, Delete Account).
Table Permissions
provides a dialog to modify permissions for the selected table
Register/Unregister Data Manager
intended to register a new Data Manager DLL on the server, or un-register the
selected Data Manager DLL. Only registered Data Manager DLLs are available
for the user. (Note: It is responsibility of an administrator to manually copy the
necessary DLLs to the server).
Refresh Registrations/Refresh Data Manager
provide for refreshing information about the registered Data Manager. It is useful
in the case when the Administrator replaces a Data Manager DLL with a new
one. The First menu item refreshes all registered Data Managers. The second
item – refreshed just the selected Data Manager.
Data Managers Aliases
provides a dialog to add/remove/modify aliases for the Data Manager DLL’s.
Server Settings
provides the ability to specify the Maximum number of simultaneous connections
allowed, and a session timeout setting.
Help
In the current version only an About sub-item is supported
Note: The availability of the listed menu items depends on the node selected on the left hand tree-list and or the item
selected on the right table pane.
99
Toolbar
The toolbar provides easy access to the most common main menu actions.
From left to right:
Connect to IP Data Server
Refresh
Close Sessions
New Account
Register Data Managers
Server Settings
Tree-View Pane
The Tree View Pane contains the following nodes:
IP Data Server
Sessions
Data Managers
Accounts
high-level node corresponding to the current connection of the RMAdmin to a Data Server. This
node has the following child nodes:
corresponds to currently active user sessions. When the node is selected the right Details pane
contains the Session view. (See Sessions view section for details.). The child nodes of the node
represent the currently active sessions.
The child nodes of this node correspond to specific Data Manager DLL’s, installed (registered) on
the server. When you select the DLL under this node the right-hand Details pane displays the
tables available in that Data Manager DLL. For more details, see the Table maintenance view
section.
corresponds to the user accounts registered on the server. If this node is selected then the righthand Details pane lists the Accounts available on the data server. For more details, see the
Account administration view section.)
100
Details View Pane
The views presented in the right-hand Details pane are dependent on the items selected in the Tree View Pane.
Sessions View
The Sessions view is displayed in the details pane when the Sessions node is selected in the left-hand tree list. This view
displays information about currently active sessions on the server and provides access to a set of related operations. This
view is used to monitor and control IP client sessions.
ID
Status
User Name
Transaction (Status)
an internal ID for the session
displays the session status. This can be active or terminating.
name of the user that owns the session
this box is checked if a transaction is started or in progress.
The following operations are available when this view is active:
Close Sessions
Force Close Sessions
Prevent New Sessions
Allow New Sessions
terminate the selected session(s). If a transaction has been started by a session, the
session isn’t terminated until the transaction is finished.
terminate the sessions immediately even if a transaction in progress
prevent (disable) subsequent user connections to the server.
enable new sessions if they were disabled
101
Active Table View
The Active Table view is displayed in the Details pane when a node corresponding to a session is selected in the left-hand
tree list. This view displays information about tables currently used in the selected session. Its purpose is to monitor and
control IP driver sessions with the Remote Administrator.
This view is a table grid with the following columns:
Data Manager
Table
Table Status
Open Mode
Record Held
contains the name of Data Manager DLL used by the session
contains the name of the database table used in the session
can be opened and/or locked.
The table open mode. It can be any of the following pairs;
User Access( Read Only, Write Only, Read/Write)/
Other's Access ( Any Access, Deny All, Deny Write, Deny Read, Deny None)
Checked if a record is locked by the session
102
Table View
The Table view lists all tables for the selected Data Manager and provides for setting of access rights for the tables. You
can also perform some basic operations on the tables; CREATE() and BUILD().
NOTE: CREATE() and BUILD() will only succeed if the physical data tables are located in the root directory of the data
server and do not contain a NAME attribute.
The view is a grid with the following columns:
Prefix
Table
Status
Sessions
Locked by
Records Held
The table prefix (value of a FILE’s PRE attribute)
Table name that is used to store the table (value of a FILE’s NAME attribute or the label
of the FILE structure if the NAME attribute is empty).
The default value is ready. Status can change during a BUILD operation (build in
progress, build failed)
Holds the number of sessions working with the table at this time.
Holds the name of the user that locked the table (if locked).
Stores the number of records locked in the table
The following operations are available in this view:
CREATE Table(s)
BUILD Keys for Table(s)
Create or recreate the corresponding data file
Rebuild all keys for the selected table.
You can also use the following session operations available for any tables selected in the right pane:
Permissions dialog (see the Permissions dialog section that follows).
Close Sessions
Force Close Sessions
103
Account Administration View
The Account Administration view displays information about users currently registered on the server. It is used to specify
create user accounts and passwords, modify users and delete them.
Accounts are used to control specific data access from IP Client applications. One user account could be used for read
only access only, and another account can offer additional access.
The view is a grid with the following columns
User Name
Administrator
Identifies the name of the user account
A checked value means that the user account has administrative rights.
The following operations are available in this view:
Add New Account
User Name
Password
Confirm password
Administrative access
Modify Account
Delete Account
Create a new account. The operation displays the dialog to create a new user account.
Enter the name of the newly created user
Enter the password
Enter the password again, confirming the password
When checked, this account is granted access to the Remote Administrator Console.
This option provides the same dialog as in Add New Account to modify user’s data
Deletes the selected account.
104
Table Permissions (Access Rights)
The Table Permissions dialog allows you to set and change user access rights for a selected table. Whenever a new
account is established for an IP Client application, a User account must be specified and Table Permissions must
be granted to allow table access.
The Permissions dialog is called from the Table Permissions… menu or popup item when a selected table is highlighted.
The Permissions dialog is shown above. The first column contains a list of users allocated to access the selected table.
Other columns contain check boxes that enable specified access rights of the selected user for the table(s).
The list includes the following options (check boxes).
When checked:
Read
Write
Deny Read
Deny Write
Create
Build key
Lock
Hold record
Read access is permitted
Write access is permitted
Opening the file with Deny Read is permitted
Opening the file with Deny Write is permitted
CREATE, COPY, and REMOVE operations are permitted
BUILD and PACK operations are permitted
LOCK operation is permitted
Record locking is permitted
The dialog provides the possibility to apply the permission settings to all tables belonging to the selected Data Manager
(Apply to All Tables button).
105
IP Server Settings
The IP Server Settings dialog provides the ability to specify the Maximum number of simultaneous connections allowed,
and a session timeout setting. (Tools > Server Settings)
To modify the setting’s value double-click to use edit-in-place.
The following entries are available:
MaxConnectionNumber
SessionTimeoutMinutes
maximum number of simultaneous connections
time in minutes that the server will wait to automatically disconnect a session, if no client
activity is detected. The maximum value is 10000.
Data Manager Aliases
Data Manager Aliases are intended to simplify access to the Data Manager DLL. Each Data Manager DLL may have an
Alias. An Alias provides a convenient way to refer to the corresponding Data Manager DLL. A Client program may use a
Data Manager alias instead of the Data Manager DLL’s relative path, located in the OWNER attribute of the IP enabled
FILE structure.
The Data Manager Aliases dialog allows you to add/remove/modify aliases for a target Data Manager DLL.
The dialog contains an Edit-in-Place table with the following column options:
Alias
Contains the unique alias name for a target Data Manager
Data Manager Contains the Data Manager DLL (path and name)
The dialog works in two modes. If a specific Data Manager is selected, the dialog contains aliases only for that selected
Data Manager. Otherwise, the dialog contains all aliases registered in the system for all Data Managers.
Status Bar Information
The RMAdmin console has status bar that is used to display information about the current server status. The information
includes server state (Not Connected, Connected) and total number of active sessions.
106
Connect to IP Server
This dialog is used to connect to an IP Data Server.
User Name and Password
Enter a valid User Name and Password.
Only users with administrative access rights can connect to the server.
If the connection fails, a message box displays the type of error. On success this dialog is closed automatically. The
Connection dialog can be invoked at any time through the menu command, toolbar button or by hot key.
The Server entry for local testing should use localhost:2339 . The remote administrator uses its own internal encryption,
so do not use an SSL port in this entry.
107
Possible Connection Errors
The following errors may be posted:
Error in Communication with the specified IP Data Server. Connection Refused:
Connect.
Possible Cause: SoftVelocity IP Data Server Service not started, or a connection is already active from another location.
The Specified IP Data Server could not be found
Possible Cause: Invalid Host name or IP address
Communication Port is not defined
Possible Cause: Missing Port address in Server entry field
The User Name is either not specified or not recognized
Possible Cause: An invalid User Name, or leaving the User Name blank.
The Password you entered is not valid. Please try again. If you still
experiencing difficulties please refer to your System Administrator.
Possible Cause: An invalid Password, or leaving the Password blank when it is required.
Stored configuration properties
The Remote Administrator Console stores a variety of configuration properties such as the main window size and last
accessed hosts in the text file properties.txt located in the RMAdmin working directory.
108
IP Driver Specifications
The IP driver reads and writes data stored on a target server location. If no NAME is specified, then the label of the file is
used to find the data to be used.
Files:
C60IPDX.LIB
Windows Static Link Library
C60IPDX.DLL
Windows Dynamic Link Library
Data Types and File Specifications
BYTE
SHORT
USHORT
LONG
ULONG
SREAL
REAL
BFLOAT4
BFLOAT8
DECIMAL
PDECIMAL
STRING
CSTRING
PSTRING
DATE
TIME
GROUP
Notes:
1. Data Types and File Specifications are dependent upon the type of table that the IP Driver is enabling. For
example, if you IP enable a TopSpeed table, the IP enabled TopSpeed table has all of the characteristics of a
standard TopSpeed table.
2. Since Clarion’s In Memory Database Driver (IMDD) creates a file on the client’s local machine, and not the server,
the IP enabling of the IMDD is not supported.
109
Driver Strings
There are switches or "driver strings" you can set to control the way your application creates, reads, and writes files with a
specific driver. Driver strings are simply messages or parameters that are sent to the file driver at run-time to control its
behavior. More information regarding these strings can be found in the Language Reference PDF
Some driver strings have no effect after the file is open, so no SEND function syntax is listed for those strings. However,
the SEND function syntax to return the value of the switch is listed for all driver strings.
The IP DRiver supports the following Driver String:
IPEXEC
The IP Driver provides support for executing code contained in your Data Manager DLL on the server. You accomplish
this using the SEND command with the message parameter containing the keyword “IPEXEC”.
returnvalue = SEND(file,'IPEXEC stringValue')
file
the name of a file that is defined in the IPServer Data Manager DLL, which is used by the RemoteExecute
procedure
stringValue
a string value to be used in the RemoteExecute procedure.
When the SEND command is processed on the server the first 7 characters of the message parameter are checked, and
if the string “IPEXEC “ is found (including the space character) the RemoteExecute() procedure is called.
RemoteExecute() is passed a reference to the FILE and the stringValue beginning at position 8. The “IPEXEC “ is
stripped from the stringValue before its passed to the RemoteExecute() procedure.
NOTE: The SEND command for the IP Driver MUST be called AFTER THE TABLE IS OPENED, and not before.
Supported Commands and Attributes
The IP driver transmits Clarion language commands to the IP Data server where they are executed using the database
driver as specified in your Data Dictionary (TopSpeed, etc). To check whether a specific command or attribute is
supported refer to the documentation for the database driver you specified in your Data Dictionary.
110
DEBUGVIEW Support
Support is available for using the DEBUGVIEW utility. DEBUGVIEW lets you monitor debug output without the need to
run a debugger to catch the output you specify in your applications.
Support for the DEBUGVIEW utility is provided through the following built-in procedure:
TRACE( string )
string
A STRING constant, variable, or expression that contains information to send to the DEBUGVIEW utility.
TRACE is used to send debug information to the DEBUGVIEW utility.
You can download the debug viewer from the following link:
http://www.sysinternals.com/ntw2k/freeware/debugview.shtml
111
Advanced Deployment Tips
Clarion Runtime Files
When deploying IP Client applications to your users, you may find it useful to have the C60RUNX.DLL and the database
drivers you are using located in a common location on the PATH, so that all of your Client applications can share them.
Multiple IPServer DLLs are permitted, but we recommend that each DLL have a unique set of tables defined. If two IP
Data Server DLLs reference the same table, the table definitions must match exactly.
Location of Data Managers and Data Files
The simplest deployment places both the Data Manager DLL(s) and the associated data files in the root of the IP Data
Server. But you have flexibility in where you deploy both file groups.
Data in a subdirectory
If your FILE provides a NAME attribute such as NAME(‘DATA\MYFILE.TPS’), the Data Manager will attempt to OPEN the
FILE in the “Data” subdirectory relative to its own location. That means if the Data Manager is located in the root of the
data server install (e.g \ClarionDataServer) then the data files would be deployed to \ClarionDataServer\Data.
Data Manager in a subdirectory
You can place Data Manager DLLs in a subdirectory under the root of the data server.
If you do this the data files must be deployed to that directory, unless you are using the NAME attribute as explained
above.
112
Distribution Guide
This section discusses the key files and other steps needed to distribute your IP-enabled applications to your customers.
IP Data Manager Distribution
The Data Manager DLL that you create will also require the minimum files to be distributed:
C60RUNX.DLL
<any driver dll(s) specified in your dictionary>
For example, if your dictionary had some files defined as TopSpeed and others as ASCII
then you would distribute both C60TPSX.DLL and C60ASCX.DLL.
Please refer to the Clarion Database Drivers PDF for the names of other driver DLLs.
IP Client Applications
In addition to the files you would normally distribute, your client application also needs:
LIBEAY32.DLL (IP Driver support library)
SSLEAY32.DLL (IP Driver support library)
OSSLWRAP.DLL (IP Driver support library)
IP Data Server (IPDS) Distribution
In accordance with the license terms of the IPDS you can redistribute the IPDS files with your application. The license is
installed in the root directory of the IP Data Server (by default, C:\ClarionDataServer). Any distributions of the IP Data
Server must include the SoftVelocity IP Driver and Data Server license text as installed to IPDSlicense.txt.
The IP Data Server requires the following files:
Claipdat.exe
IPReq.exe
Libeay32.dll
Ssleay32.dll
IPDSlicense.txt
If you are using SSL connections you also need to ship an appropriate server.pem file. (See the SSL Deployment
Considerations section in this manual for more information).
You are also licensed to distribute the Java Remote Administrator Console (rmadmin.jar) and this PDF manual.
113
How to Distribute the IP Data Server
We recommend the use of Lindersoft's SetupBuilder tool for your installation program. Lindersoft's SetupBuilder 5 makes
it easy to properly distribute the IP Data Server, with built-in support for the IP server. The developer only has to enter the
location of his IP Data Server and all the required files are linked into the Setup.exe and the service is set to install.
More information regarding the use and purchase of SetupBuilder can be found at http://www.lindersoft.com/
You can "pre-register" the Data Manager DLL(s) that your applications use. To do this, follow these steps on your
development machine:
1.
2.
3.
4.
Stop the SoftVelocity IP Data Driver service. (see page 8).
Delete or rename ipreq.cfg (located in the root of the Data Server directory).
Start the SoftVelocity IP Data Driver service.
Using the RMadmin application, "Register" the required Data Manager DLLs, create user accounts (if needed),
and then set the appropriate file access permissions.
The ipreq.cfg you just created now contains the Data Manager DLL entries, and can now be deployed as part of your
installation of the IP Data server.
114
Distributed Applications
Divided
When you IP-enable your application, you are dividing your application to run in separate processes. The processes may
run on the same machine (if the machine is running the SoftVelocity IP Data Server service), or they may be run on two or
more machines.
Separate Processes
Keep in mind that the process (code) executing on the Data Manager DLL on the server does not have access to any
variables defined in your Client application, except for values in record buffers. You can however use the
RemoteExecute() procedure to “SEND” values of variables to the server.
Advanced
With some careful planning you can use the RemoteExecute() procedure to offload work to the server. RemoteExecute()
can also be used to spawn other processes, but remember that if you do start a new process it is detached from control
by your client application.
115
Globalization
Globalization (also known as internationalization) is also supported in your IP Driver Client applications as well as the
Data Manager you create for the IP Data Server.
An environment file contains internationalization settings for an application. On program initialization, the Clarion run-time
library attempts to locate an environment file with the same name and location as your application's program file (i.e.,
appname.ENV).
If you are using an environment file to specify internationalization settings for your application you will need to deploy the
.ENV file with both client and server applications. You can use the Program Setup embed point in the appropriate Data
Manager DLL to call the LOCALE() procedure.
Example:
LOCALE('ip_people.env')
LOCALE('CLACOLSEQ','DdCcBbAa')
Some Environment file options may not be applicable in an IP-enabled application:
•
•
Use of CLABUTTON
Errors returned by the client application are extended errors, and cannot be changed with the Environment file.
For more information regarding globalization, please refer to the Environment Files topic found in the Clarion online help.
116
Performance Tips
The real measure to look at for maximum performance is a result of several factors:
1. The number of "different" applications that run on the server (e.g., the Data Manager DLLs). The Windows operating
system shares the code sections from the "same" DLLs amongst running processes, so if the applications are all using
the same Data Manager then the OS will use less memory then it would if many clients each connected to unique Data
Managers.
2. The number of threads open in the client program (each thread in the client has a mirrored thread on the server)
There is a limit in the OS of ~32000 threads, but really the OS slows down well before that limit, if too many threads are
actively seeking time slices.
3. The amount of memory in the server (obviously the more the better).
4. The CPU in the server (obviously the faster the better).
5. If the data is local to the IP server then the hard drive access speed is also a factor
The IP architecture is superb for scalability because:
1. A client program can connect simultaneously to several IP servers, so memory usage and data loads can be spread
over different machines.
2. You can have several IP servers, and each server may access common data, and Data Managers may access data on
any machine in the network.
3. A combination of 1 and 2.
Performance over ADSL will be a direct function of the latency in the routers between the client and the server.
If you run a “traceroute” or a path ping you can see where any routers are slowing down the network connection from
client to server.
With the combination of the IMDD (in Version 2.0) you can also cache data in the client, thereby reducing the effects of
latency if it becomes an issue.
117
Troubleshooting
Problem: I am having a problem starting the Remote Administrator Console.
Solution: Make sure that you have the Java SDK or JRE versions 1.4 or greater installed on your development machine.
The JRE (Java Runtime Environment) is a free download available at www.java.com or java.sun.com
After installing, you should be able to run the rmadmin.jar program by simply double-clicking on it. The RUN.BAT file will
only run the console properly if the environment JAVA_HOME path variable is properly set.
Problem: I’ve started the Remote Administrator Console, but cannot log in (Connect to the IP Data Server)
Solution: The first time you use the Remote Administrator Console, enter a User name of Administrator, and leave the
Password entry blank. If you are already using the default port of 2339 in another service, you may have to modify the
claipsrv.ini entries to reflect a different port address.
EXAMPLE claipsrv.ini contents:
[REQUESTER]
PORT=2339
PORT_SSL=2340
Problem: I am running my first IP Client application, and receive the following message:
“Error: Entry Point not found for ordinal #### in LIBEAY32.DLL”
Solution: Both LIBEAY32.DLL and SSLEAY32.DLL are used by other products. Your client application is finding older
copies of these files on the system PATH. The correct copies are installed in the Clarion6/BIN folder. Copy both DLLs to
the folder that contains the IP Client application.
Problem: Can I use the IP Driver to connect to an ODBC data source?
Solution: When any application is running as a Windows service (as in the SoftVelocity IP Data Server), the ODBC data
source must be identified as a System Data Source (or System DSN).
Problem: Does the IP Driver support the UNC (Uniform Naming Conventions) for tables?
Solution: Yes, but you need to configure the SoftVelocity IP Data Server Service to allow access to the network. For
more details on how to do this, please refer to the UNC support for the SoftVelocity IP Data Server Service section in this
document.
Problem: What about using the IP Driver to connect to a mapped drive?
Solution: A service should not directly access local or network resources through mapped drive letters. Additionally, a
service should not use the WNetxxxx APIs to add, remove, or query any mapped drive letters. Although the WNetxxxx
APIs may return successfully, the results will be incorrect. A service (or any process that is running in a different security
context) that must access a remote resource should use the Universal Naming Convention (UNC) name to access the
resource.
118
Problem: I just installed the IP Data Server on a Windows XP (Service Pack 2) machine, and tried to connect to my data
from another machine, but I could not connect. What might be the problem?
Solution: Windows XP SP2 now has default firewall protection installed. There are two things that you can do:
1) Add the 2339 default IP Server port to the windows firewall "Exceptions" tab.
or
2) Add the IPREQ.EXE Data Server executable to the windows firewall "Exceptions" tab.
To add exceptions, go to Windows Firewall in Control Panel. To open Windows Firewall, click Start, click Control
Panel, and then double-click Windows Firewall.
Problem:
On occasion, my client application may receive a “Socket Error” when losing an IP connection. What is the best way to
handle this under program control? What must be done to re-establish a connection?
Solution:
The new connection protocol in Version 1.3 allows you to re-establish any connection easily if you should lose it for any
reason. Two steps are needed. First, make sure that all IP tables are closed in your application. This can be done by
calling a custom “CloseAll” procedure that checks the STATUS of each table, and closes them if needed. Second, reopening any table will establish a new connection if it is available.
Problem:
I have just reinstalled a new version of the IP Server, and now I cannot see any of my new Data Managers to register in
the pop up list?
Solution:
It is possible that your ipreg.cfg file needs to be re-initialized. Use the IPSRVMGR.exe (Delete Config File) to remove the
ipreq.cfg, and then restart the Remote Administrator.
Problem:
I have an executable located in the ClarionDataManager folder. The executable (backup.exe) may create a backup file on
another computer on the network. If the executable is run via RUN('Backup.exe') from the Data Manager DLL as a remote
procedure (called from the IP Client application) any attempt to create the file on another computer on the network or
create a new folder does not work. It is as if normal network permissions as far as file copying or folder creation are not
allowed when attempted from the Data Manager DLL.
Solution:
Make sure that the SoftVelocity IP Data Server service Log On option is using an account that has the proper
permissions set. Do not use the Local System account option.
119
Index
Aborted..........................................................................87
Account Administration view .......................................103
Active Table view ........................................................101
Aliases.........................................................................105
BeforeOpen ...................................................................59
Cancel ...........................................................................87
CloseConnection...........................................................78
Connection Errors .......................................................107
custom procedure .........................................................38
Customer Permissions ................................................104
Data Manager................................................................44
Data Manager Aliases.................................................105
Data Manager DLL Wizard............................................35
DebugView Support ......................................................39
deployment notes..........................................................28
Details pane ................................................................100
Driver, IP .........................................................................7
DynFile Class ................................................................73
Examples.......................................................................56
Exec ..............................................................................75
Extended Server Support Extensions – Client..............47
File Transfer ..................................................................56
File Transfer Embed Points...........................................64
file transfers...................................................................38
Filtering Rules ...............................................................72
Finish.............................................................................87
firewall .........................................................................118
From List
Connection Type .......................................................45
GetAction.......................................................................90
GetAllowPause..............................................................90
GetBuffersPerCycle ......................................................88
GetConnectionString...............................................74, 80
GetError...................................................................83, 88
GetErrorCode ..........................................................83, 88
GetFileName .................................................................76
GetFName.....................................................................58
GetRemoteFileName ....................................................81
GetRemoteVariable.......................................................77
GetSilent........................................................................83
GetTimer .......................................................................89
Globalization................................................................115
Imported Procedures.....................................................47
Init..................................................................................82
InitReceive.....................................................................85
InitSend .........................................................................84
Install Considerations....................................................12
IP Client Global Extension ............................................42
IP Data Server Service..................................................13
IP Driver ..........................................................................7
ODBC ......................................................................117
IPC File Defined ............................................................24
IPChangeFileName Code Template .............................49
IPDRV = TRUE .............................................................31
IPDRV Extended ...........................................................39
IPDRV Extended Server Embeds .................................62
IPDRV Extended server support................................... 38
IPEXEC................................................................. 60, 109
IPEXEC Code template ................................................ 50
IPEXEC Dispatch.......................................................... 62
IPEXEC Source Procedure Template........................... 41
IPExtended Class ......................................................... 73
IPFileTransfer Class ............................................... 73, 80
IPGetFileName ............................................................. 63
IPGetRemoteVariable................................................... 54
IpIsAlive ........................................................................ 52
IPKeepAlive .................................................................. 53
IPRequestCount............................................................ 65
IPS file defined.............................................................. 23
IPServer template ......................................................... 33
IPSetFileName.............................................................. 63
IPSetRemoteVariable ................................................... 54
IPTransferFile Control Template................................... 55
IPTransferFileCode Code Template ................. 51, 52, 53
IsAlive ........................................................................... 78
Java SDK or JRE versions ......................................... 117
LEDGER ....................................................................... 56
LIBEAY32.DLL.............................................................. 26
Mapped Drives.................................................... 117, 118
MFC42.DLL................................................................... 26
MSVCP60.DLL.............................................................. 26
MSVCRT.DLL ............................................................... 26
Multidataset................................................................... 56
Multiple Request Packets ......................................... 9, 65
NOMEMO ............................................................... 66, 71
ODBC.......................................................................... 117
OSSLWRAP.DLL .......................................................... 26
Pause............................................................................ 87
Performance Tips........................................................ 116
Receive ......................................................................... 87
Register
IP Driver .................................................................... 10
Templates.................................................................. 10
Remote Administrator ................................................... 97
Account Administration View................................... 103
Active Table view .................................................... 101
Customer Permissions ............................................ 104
Details Pane ............................................................ 100
Main Menu................................................................. 98
Server Settings........................................................ 105
Sessions View ......................................................... 100
Table Maintenance view ......................................... 102
Toolbar ...................................................................... 99
Tree View Pane......................................................... 99
remote procedure calls ................................................. 38
Remote Variables ......................................................... 48
runtime file name variables........................................... 38
Runtime Names ............................................................ 40
Send.............................................................................. 87
Server Settings ........................................................... 105
Server Side VIEWs ....................................................... 72
Server Variables ........................................................... 40
120
Server-side VIEWS .........................................................9
Services.........................................................................13
Sessions view..............................................................100
SetAllowPause ..............................................................90
SetBuffersPerCycle.......................................................88
SetConnectionString ...............................................74, 80
SetControls....................................................................81
SetFileName............................................................76, 79
SetKeepAlive.................................................................79
SetRemoteVariable .......................................................77
SetSilent ........................................................................83
SetSourceFileName ......................................................81
SetTargetFileName .......................................................81
SetTimer........................................................................89
Socket errors .................................................................92
SoftVelocity IP Data Server Service ............................. 13
SSL ............................................................................... 29
SSLEAY32.DLL ............................................................ 26
Start .............................................................................. 87
StartTimer ..................................................................... 91
StopTimer ..................................................................... 91
SwapPauseText............................................................ 91
Table Maintenance view ............................................. 102
Table Permissions ................................................ 27, 104
TakeEvent..................................................................... 86
thread...................................................................... 15, 40
Tree View Pane ............................................................ 99
UNC ............................................................................ 117
UNC support ................................................................. 96
Windows Firewall ........................................................ 118

Clarion IPDS Reference Guide

Transcription

Similar documents

AzureWave ARR5B95 Us..

RZR623 Fixing Wrong USB Devices in Windows 7

Teen Driver Contract

Instruction Manual

EFAS Wandtafel Mitte

nEar05 eXperience

Solutions for the Automotive Industry

autocar9may47 4 - MG

Austin Powell set to drive for Team 99 Motorsport Driver Development