Ping Enterprise Tool Introduction

PowerTCP Ping Enterprise Tool

Support Licensing Distribution

The PowerTCP Ping Enterprise Tool is designed for the following scenarios:

a) 24/7 reliability
b) high speed
c) scalability
d) low resource consumption

What Makes Ping Enterprise So Special?

There are many product options for integrating Ping into your application, including the version available with the PowerTCP Winsock Tool. What makes PowerTCP Ping Enterprise different is that it is designed for the highest performance and reliability standards. Using an internal multi-threaded design, the Ping ActiveX control is engineered to operate in an environment that requires 24/7 uptime while conducting continous pings against one or more devices. Using the asynchronous capability of the control, numerous pings can be conducted every second while tracking the number of outstanding pings at any point in time.

Features of the PowerTCP Ping Enterprise Tool

  • Multi-threaded internal architecture.

  • Engineered for low resource consumption and 24/7 uptime.

  • Does not use raw sockets so administrator account is not required for ASP.

  • Can conduct numerous simoultanteous ping operations per second. (total number dependent on system capabilities)

  • Tracks the number of outstanding pings.

  • Can be used in both blocking environments (such as ASP) and non-blocking (such as a Windows applications).

  • Automatic name-to-address (and reverse name resolution.

  • 100% .NET compatible using .NET COM interop, samples included.

  • Includes a royalty-free license.

  • Extended support for PowerBuilder

Controls

Control | Description
Ping Enterprise Control | Dependable high-performance ping.

Supporting Objects

Object | Description
PingReply | Contains response information from a synchronous ping operation .

Sample Projects

The following sample projects demonstrate how to use the Zip Compression Tool:

Project | Description
Asynchronous Ping Application | Demonstrates the use of Ping in an asynchronous operation. BCB5, Delphi5, VB.NET, C#, VB6, VC++, PB
ASP Ping Application | Demonstrates the use of Ping in a scripting operation. ASP
ListView Ping Application | Demonstrates continuous pings in a ListView control. VB6


PowerTCP Introduction

Welcome to PowerTCP, the market leader in Internet Application Development Tools.

The following topics provide a general overview of PowerTCP:

  • PowerTCP Introduction

  • PowerTCP Tools Overview

  • License Installation

  • Trial Operation

  • Support

  • Distribution

  • Debugging Notes

  • PowerTCP Visual C++ Notes


PowerTCP Overview

Dart has transformed its world-class Internet Toolkit into a Component Object Model (COM) – based set of ActiveX controls that are supported in more development environments than ever before. Our ActiveX (ATL) controls and sample applications plug into all popular development environments: Visual Studio, C++Builder, Delphi, PowerBuilder, Internet Information Server (ASP), JavaScript, FoxPro, and other VB script and VBA environments. New features include:

  • Multi-tier architecture that separates all processing into 3 layers—no competing product offers this level of flexibility and modularity:

  • Formatting tier converts bytes into objects

  • Upper-layer protocol tier (Telnet, FTP, SMTP, etc.) implements communication protocols

  • Winsock tier handles all communication tasks

  • Controls can be placed on forms OR dynamically instantiated, making this product perfect for both form-based environments like Visual Basic AND formless environments like ASP.

  • Blocking behavior is included, so you can write applications using blocking or non-blocking operation. Scripting languages such as VB and JavaScript are now fully supported.

  • 'Apartment Model Threading' provides multi-thread support for the most demanding applications.

  • Superior Object Model maximizes your effectiveness in your development environment—collection properties provide superior list handling, formatting objects make it easier to manipulate complex structures (like MIME and SNMP messages), and the use of enumerated types and objects makes your job as simple as it should be.

PowerTCP is a complete collection of Internet protocol controls and formatting objects. The controls provide concise programming models for the protocols and contain events to help monitor lengthy operations, and the formatting objects transform data between network bytes and COM objects with which your application can easily work.


PowerTCP Tools Overview

This topic describes the following PowerTCP Tools:

  • Emulation Tool

  • FTP Tool

  • Mail Tool

  • SSL Tool

  • Server Tool

  • SNMP Tool

  • Telnet Tool

  • Web Tool

  • Web Enterprise Tool

  • WebServer Tool

  • Winsock Tool

PowerTCP Emulation Tool

Build terminal emulation capabilities into your application with this visual VT52/100/220/320 control. The Emulation Tool consists of the following controls:

Telnet Control – Manage Telnet, Rexec, Rsh, and Rlogin sessions

VT Control – Concise visual VT-320 display viewing, including invisible screen-scraping

Back to Top

PowerTCP FTP Tool

Copy files between your client and any FTP server. The FTP Tool consists of the following control:

FTP Control – Transfer files

Back to Top

PowerTCP Mail Tool version 2

Create advanced Internet mail applications with these controls for extended SMTP, POP3, and IMAP4. The Mail Tool consists of the following controls:

SMTP Control – Superior high-performance mail delivery

POP Control – Ultimate control for downloading mail

IMAP Control – Objects make IMAP simple to use

Back to Top

PowerTCP SSL Tool

Automatically authenticate and encrypt/decrypt all data sent and received over a TCP connection using SSL2, SSL3, PCT, and TLS. The SSL Tool consists of the following controls:

CertificateList Control – Present the user with an interface to select certificates

Daemon Control – Accept connections

Service Control – Turn your server application into an NT service

SecureFtp Control – Establish secure FTP sessions

SecureFtpServer Control – Build into your application a secure fully-functioning standalone or custom FTP server

SecurePop Control – Download mail from secure POP servers

SecureServer Control – Daemon Control and a collection of SecureTcp Controls for superior "turn-key" secure server performance

SecureTcp Control – Send data securely over the Internet

Back to Top

PowerTCP Server Tool version 3

Enable the rapid construction of custom server applications. The Server Tool consists of the following controls:

DNS Control – Lookup names, addresses, mail servers

DnsServer Control – Enables the implementation of DNS Proxy Servers.

FtpServer Control – Build into your application a fully-functioning standalone or custom FTP server

Server Control – Daemon Control with a collection of TCP Controls for superior "turn–key" server performance

Service Control – Turn your server application into an NT service

TCP Control – Stream management

Back to Top

PowerTCP SNMP Tool version 2

Put the "simple" back into Simple Network Management Protocol. The SNMP Tool consists of the following controls:

SNMP Agent Control – "Drop-in" SNMP agent

SNMP Manager Control – "Drop-in" SNMP manager

Service Control – Turn your Agent application into an NT service

Back to Top

PowerTCP Telnet Tool

Manage Telnet, Rexec, Rsh, and Rlogin sessions. The Telnet Tool consists of the following control:

Telnet Control – Manage Telnet, Rexec, Rsh, and Rlogin sessions

Back to Top

PowerTCP Web Tool

Communicate with Web Servers using HTTP and HTTP/S. The Web Tool consists of the following control:

Web Control – Access Web page documents (supports secure HTTP)

Back to Top

PowerTCP WebEnterprise Tool

Communicate with Web Servers using HTTP and HTTPS with a server-optimized tool. Includes powerful Web parsing and resource grabbing objects.

CertificateList Control – Present the user with an interface to select certificates

Web Control – Wininet dependent control used to access Web page documents (supports secure HTTP)

WebASP Control – Wininet independent control used to access Web page documents using WebMessage Object (supports secure HTTP).

Back to Top

PowerTCP WebServer Tool

Build web applications in any familiar software development environment. The WebServer Tool consists of the following controls:

Service Control – Turn your server application into an NT service

WebServer Control – Add Web Server capabilities to any application

Back to Top

PowerTCP Winsock Tool version 2

A complete set of basic building blocks with controls for TCP, UDP, Daemon, DNS, Ping, and RAS. The Winsock Tool consists of the following controls:

Daemon Control – Accept connections

DNS Control – Lookup names, addresses, mail servers

Ping Control – Verify a host is reachable

RAS Control – Control system dial-up services

TCP Control – Stream management

UDP Control – Send and receive user datagrams and raw datagrams

Back to Top


PowerTCP Licensing

PowerTCP License Installation

Your PowerTCP License Agreement provides you with a single-seat development license and the right to distribute PowerTCP controls with NO ROYALTIES of any kind. Some PowerTCP objects are marked as licensed. This topic covers:

  • Trial Installation

  • Installing a Fully Licensed PowerTCP Tool

  • Re-installing a PowerTCP Tool

  • License Details

  • Special Notes on Tested Development Environments

Trial Installation

Installing a PowerTCP Tool as a fully–functional trial involves running the setup program (available from www.dart.com) without completing the Registration process. The trial will operate for 30 days after installation. Proceed to step 2 of Installing a Fully Licensed PowerTCP Tool when you are ready to license the product.

See Trial Operation for more information.

Back to Top

Installing a Fully Licensed PowerTCP Tool

Once you have downloaded the latest version, complete the following steps to register your PowerTCP Tool:

  1. From the Start menu, point to Programs, point to PowerTCP, point to the PowerTCP Tool you downloaded, and then click Registration.

  2. In the PowerTCP Registration dialog box, click Register.

  3. Enter your Serial Number, First Name, Last Name, and Organization information.

  4. Click Next.

  5. Enter your Email Address, Purchased From, and Purchased Date information.

  6. Click Next.

  7. Verify that the information is correct, and then click Next.

  8. When the registration process is complete, click Exit. (Note Clicking Done at this step displays your currently registered PowerTCP Tools. Click Exit to end the complete the registration process and close the dialog box.)

If you do not have Internet Access on your development machine, please follow these instructions:

  1. From the Start menu, point to Programs, point to PowerTCP, point to the PowerTCP Tool you downloaded, and then click Registration.

  2. In the PowerTCP Registration dialog box, click Edit.

  3. In the Currently Registered Products area, write down the number in the Key field (the fields appears dimmed).

  4. On a machine that has Internet access, log on to the Dart registration page (http://www.dart.com/register/).

  5. Enter all required information. Required information is bolded. Key is the number you wrote down in Step 3 above.

  6. Click Submit. A seven-digit registration code appears.

  7. On your machine (the machine on which you completed Steps 1-3), if necessary, access the PowerTCP Registration dialog box to display the Currently Registered Products area containing the Key number.

  8. Enter your serial number and the seven-digit registration number you obtained in Step 6.

  9. Click Update.

  10. Click Exit.

After either of the two registration procedures are complete, your PowerTCP Tool appears in the Registered Tools field of the registration form. Make sure you recompile your application after you register the PowerTCP Tool. For distribution instructions specific to your development environment, please view the Readme file. The Readme file is located in the Samples directory; for example, to locate the Readme file for the Winsock Tool in VB6, use the following path: Start>Programs>PowerTCP>WinsockTool>VB Samples>VB6>Readme.

If you do not register your PowerTCP Tool at this point, it will operate as a trial. Remember to distribute with your applications any necessary PowerTCP files and any dependent files. Dependent files are listed in the Introduction topic for each PowerTCP Control, and must be installed on each target system. See Distribution for more information on system requirements.

Back to Top

Re-installing a PowerTCP Tool

The Key provided by the Registration Program is derived from a system number that is changed when the C: drive is reformatted. If you reformat your hard disk, and need to re-install your PowerTCP Tool, follow the steps in Installing a Fully Licensed PowerTCP Tool. You will be prompted to complete a License Transfer form, and a new Registration Number will be generated.

If you need to re-install more than once, you will be prompted to complete a License Transfer form that will be sent to your sales representative for approval. Within two working days Dart will reset your Serial Number and notify you when you can re-register your product. The product will operate as a trial for up to 30 days.

Back to Top

License Details

When you insert a PowerTCP control into a project, most development environments verify that the control is licensed for development. The control will work if you correctly entered the PowerTCP Tool Serial Number. See Installing a Fully Licensed PowerTCP Tool for more information. When you compile your application, the development environment requests this Serial Number and embeds it in the application. When users run your application, the application submits this Serial Number to the control and the Serial Number is checked for validity. If the Serial Number is correct, then the application runs. This verification process occurs automatically.

Back to Top

Special Notes on Tested Development Environments

  • Visual Basic checks for a Serial Number when a PowerTCP control is first inserted on a form or first shown on a form. When a PowerTCP control is loaded as a reference and is dynamically instantiated (for example, Dim Tcp as New Tcp), the Serial Number is similarly checked.

  • Visual C++ obtains the Serial Number when you first insert a PowerTCP control on a form, and caches that number as a dialog resource. For this reason, Dart ships Visual C++ samples without inserted controls. You will need to insert them before you compile any of the samples. See the readme.txt file for more information. Information on dynamically creating objects using ClassFactory2 is included. License caching is MFC only; for our new C++ classes, you must specify the License as a parameter in the Create method.

  • Active Server Page deployment requires a Serial Number for each server because the environment checks for a development license each time a licensed control is used. If you deploy PowerTCP Tools for operation under IIS, install your development license into the registry as it appears on your development platform (check registry location HKEY_LOCAL_MACHINE / SOFTWARE / Dart / PowerTCP / License to see what should be installed). PowerTCP is royalty-free, including under IIS.

  • PowerBuilder also caches licensing information. See the readme.txt file for instructions on how to compile the sample applications.

  • Excel will cache licensing information when the control is originally inserted, so your spreadsheet will carry this information forward to any deployment platforms. You must use the control as a reference.

  • Delphi has special requirements. Before you can use the sample applications you MUST add the PowerTCP Tools that are in the sample to the Component Library. Refer to the readme.txt file for specific instructions.

  • C++ Builder is similar to Delphi. See the readme.txt file for specific instructions.

Back to Top


PowerTCP Trial Operation

If you install a PowerTCP product without registering a Serial Number, it operates as a fully–functional trial for up to 30 days. If you need more time to evaluate the product, reinstall it; the trial period will start over.

Trial Notification in Development Mode

When you insert a PowerTCP control on your form or dynamically create one, the control checks for a Serial Number. When it does not find one, a dialog box appears identifying the product as a trial. This dialog box does not appear if you are running under IIS; this allows the product to work within the ASP environment as a trial. After the trial period expires, you cannot insert the control without first reinstalling it.

Trial Notification during Compile

PowerTCP controls request a Serial Number when you compile your application. A dialog box appears warning you that the component is not licensed for deployment. Do not distribute your application using a trial product—the component will not work after the trial period! However, you may test your application during your trial period. To continue testing after the trial period, reinstall the product and recompile your application.

See License Installation for more information on product registration.


PowerTCP Support

Our mission at Dart is to deliver high quality Internet connectivity solutions to Internet application developers. Our goal is to supplement these solutions with timely support resources that can help at many different levels.

Related Links (you have an active connection to the Internet to view these links).

Paid Support Options

Discusses the paid support options available covering everything from single incidences, to extensive subscriptions.

Free Support Options

Provides access to free materials to help your development, including FAQS, online help files, tutorials, code snippets, online asp samples, and a free support forum.

Support Forum

Provides access to our support forum, monitored by our own development staff as time permits.

Dart Solutions

Discusses the custom development support offered by Dart Solutions.


PowerTCP Distribution

This topic covers:

  • System File Updates

  • Winsock version 2 System Support

  • PowerTCP Components

  • Distribution in Scripted Environments (such as IIS)

  • Troubleshooting

  • VT Control Distribution Note

System File Updates

Windows 95

DCOM95 version 1.3 must be installed before installing PowerTCP DLLs. You can redistribute DCOM95 with your product so your users can install it. Obtain DCOM95 from www.microsoft.com/com/dcom/dcom95/download.asp.

*Please note that at the present time the PowerTCP Ping Enterprise Tool does not support Windows 95. For Windows 95 users that require Ping, please contact Dart at support@dart.com. This does not affect higher versions of the Windows operating system.

Windows 98

DCOM98 version 1.3 must be installed before installing PowerTCP DLLs. Microsoft does not allow redistribution of DCOM98, so your users will need to obtain it from www.microsoft.com/com/dcom/dcom98/download.asp .

Windows NT4

Your system must be updated to a level of at least Service Pack 3 (the Secure DLL requires SP4) before installing PowerTCP DLLs. You must update the following OLE system files to the following levels:

DLL | Version
OLEAUT32.DLL | 2.40.4275 (or higher)
STDOLE2.TLB | 2.40.4275 (or higher)
ASYCFILT.DLL | 2.40.4275 (or higher)
OLEPRO32.DLL | 2.40.4275 (or higher)
COMCAT.DLL | 4.71 (or higher)

System updates are performed using the 4275-Ole.exe file, which is located in the Bin directory in your PowerTCP Tool install root directory. You can redistribute this file to your users. Note This system update file will not run under Win95/98 (see Windows 95 and Windows 98 for Win95/98 requirements).

Windows 2000

Windows 2000 requires no system file updates.

Windows XP

Windows XP requires no system file updates.

Back to Top

Winsock version 2 System Support

Windows 95 ships with Winsock version 1; all other operating systems (Win98/2000/NT/XP) ship with version 2. Version 2 is only required by applications that use raw datagrams and multicast features. Dart's Ping Control and UDP Control (multicast feature) are the only products that require version 2. This update was last available at www.microsoft.com/windows95/downloads/contents/wuadmintools/s_wunetworkingtools/w95sockets2/.

PowerTCP links to Winsock version 1, but the operating system redirects these calls to version 2 (if installed). Therefore, performance is optimal (no performance degradation occurs due to linking to Winsock version 1), while still allowing PowerTCP to be installed on Windows 95 systems that have not been updated to version 2.

If you use raw or multicast datagrams, make sure Winsock version 2 is available on your deployment platforms.

Back to Top

PowerTCP Components

Refer to each PowerTCP Control main topic in this Help system (for example, Telnet Control main topic) for a list of dependent DLLs. For example, DartFtp.dll (containing the FTP Control) is dependent upon DartSock.dll for all communications. You must install both DLLs when you distribute your application. Each DLL ships with a .dep file that lists these dependencies.

PowerTCP DLLs must be registered. Most installation utilities will do this automatically; however, you can also use Regsvr32.exe. See System File Updates for more information on system file support before registering PowerTCP Tools.

The following table summarizes PowerTCP DLL dependencies:

DLL | Dependent Upon
DartSock.dll | None
DartPing.dll | None
DartRas.dll | DartSock.dll
DartUtil.dll | DartSock.dll
DartFtp.dll | DartSock.dll, DartZip.dll
DartFtpServer.dll | DartSock.dll, DartServer.dll, DartFtpUtil.dll
DartDnsServer.dll | DartSock.dll
DartTelnet.dll | DartSock.dll
DartSnmp2.dll | DartSock.dll
DartVt.dll | DartSock.dll
DartWeb.dll | DartSock.dll
DartMail.dll | DartSock.dll, DartUtil.dll
DartServer.dll | DartSock.dll
DartSecure2.dll | DartSock.dll, DartCertificate.dll
DartSecureMail.dll | DartSock.dll, DartSecure2.dll, DartCertificate.dll, DartMail.dll
DartSecureFtp.dll | DartSock.dll, DartSecure2.dll, DartCertificate.dll, DartFtp.dll
DartSecureFtpServer.dll | DartSock.dll, DartFtpUtil.dll, DartSecure2.dll
DartWebASP.dll | Wsock32.dll (Winsock v. 1.1), DartSock.dll, DartSecure2.dll, DartWebUtil.dll, DartCertificate.dll
DartWebServer.dll | DartSock.dll, DartServer.dll, DartSecure2.dll, DartWebUtil.dll, DartCertificate.dll

Back to Top

Distribution in Scripted Environments (such as IIS)

If you are using PowerTCP in scripted environments (such as IIS or Excel) and you have not installed a Serial Number, the product will work for 30 days as a Trial, but will then cease operation. Scripted environment deployment requires a Serial Number for each server because the environment checks for a development license each time a licensed control is used. If you deploy PowerTCP Tools for operation in scripting environments, install your development license into the registry as it appears on your development platform (check registry location HKEY_LOCAL_MACHINE / SOFTWARE / Dart / PowerTCP / License to see what should be installed).

For most compiled applications, your PowerTCP Serial Number is automatically included when you compile, so no special license considerations are necessary. The only exception is Dart's C++ wrapper, in which the Create method takes your development license as a parameter.

Back to Top

Troubleshooting

If you receive "not licensed for distribution" messages, try removing the control from your project and then re-inserting it. If a trial was already installed and used to build a project, some development environments cache the licensing information even after registering the control. Refer to environment–specific readme.txt files for more information.

Back to Top

VT Control Distribution Note

Powervt.fon should be included in the distribution of the VT control.

Back to Top


PowerTCP Debugging Notes

Visual Basic

WARNING You can use breakpoints and the MsgBox function to stop your application at any point, but communications may not operate normally after program execution is resumed.

Visual Basic stops reporting events when execution halts at a breakpoint or upon the display of a modal dialog box. For example, suppose you place a breakpoint within the TCP State event and Receive event, and then connect to a server that sends data. You will break within the State event when the connection is established, but the Receive event will not fire. Visual Basic is "protecting" you from reentrancy. This can also occur if you display a message box after calling the Connect method, in which case no events fire. Modeless forms do not have this side effect.

Consequently, you should use:

  • A label or an edit box to display progress.

  • The Trace method to accumulate a data log. (Trace is not available with all ActiveX controls)

These techniques provide necessary debugging information without affecting the communication events being monitored.


PowerTCP Visual C++ Notes

Each development environment has it's own unique way of supporting ActiveX controls. Visual Basic, for example, offers superb support for using controls both on forms (by adding it to the component bar and dragging it onto a form) and off forms (by instantiating them at run-time using "Dim" and "Set" constructs). In Visual C++ it is a little harder, and there are different techniques possible using MFC and "straight" WIN32.

MFC Support for ActiveX

MFC provides direct support for placing a control on a form. Using the ClassWizard, you then reference the control ID, add a variable, and then add event handles for each event. This mechanism works well with Dart PowerTCP controls, but has the following shortcomings that require a workaround:

  1. When you insert a control, the resource file caches license information. When you use the control as a trial and subsequently purchases a license, you must manually remove the control and then read it so that the license information is properly included and passes the license check at run time.

  2. When Dart ships the sample as part of a PowerTCP Tool, it must be shipped with the control missing, so the application does not compile as shipped (the control must be added first, even to operate as a trial).

  3. You cannot use this technique for non-MFC or formless applications, such as console applications, service applications, ATL controls, "straight" WIN32 applications, and other C++ environments (such as Borland C++ and C++ Builder).

To work around these limitations, many Dart controls have already been upgraded to provide the following benefit.

Class Support for ActiveX

Dart has provided a "wrapper" class for many controls (and objects) that uses licensing, such that:

  1. Developers may not be familiar with using using the C function to create a licensed control (CoComCreateInstanceLic). Dart has provided a Create() method to handle the instantiation of a licensed control.

  2. Developers may also be unfamiliar with manually adding event support. Dart has provided code to create this connection within the class.

  3. You can uses these classes in any C++ environment, simplifying the use of our product in these environments.

  4. Samples will compile right out of the box.


Development Environment Overview

This topic addresses development environment specific quirks you may encounter while using PowerTCP in your particular development environment. If the topics in this section do not answer your question, please visit the Dart Support Forum for more information.

This topic covers:

  • Microsoft Access

  • Microsoft Excel

  • Borland C++ Builder 4

  • Borland C++ Builder 5

  • Delphi 4

  • Delphi 5

  • Visual FoxPro

  • PowerBuilder

  • Visual Basic 5

  • Visual Basic 6

  • Visual C++ 6.0

  • COM+/MTS

  • .NET Framework Interop


Access

Microsoft Access Environment

The Microsoft Access samples in this toolkit were created with Microsoft Access 97.

Using The Sample Applications

Each database has a Form called main. Start by opening that Form. If this is the first time you have opened the sample you will need to re-add any PowerTCP Tools that are in the project so that the licensing gets reset. To do this simply write down the name and type of each Dart control. Then, one at a time, delete each control and insert a new one with the same name.

Example:

Form Main contains a Dart FTP Control, whose name is FTP1. Select FTP1 and Delete it. Now insert a new Dart FTP control and name it FTP1. This will cause a new 30 day trial key to be generated and allow you to use the sample.

Environment Specific Quirks

Any mdb created with a PowerTCP control while in trial mode, will always be in trial. This is due to the fact that Access adds license key's directly into the database at the time of insertion. To solve this, use one of the following options:

  1. Start a new database project.

  2. Reference the control (instead of inserting on a form) and place the license registry key on any machine using the mdb. This does not work if the control is placed on a form.

More Information on Access 97 - 2000 and Licensing:

In Access, when you create a database and place the control on a form, if the machine is licensed, the control will be licensed (always). If the machine was in trial, the control will always be in trial, even after a license is installed on the machine. You can test this by creating a new database on your licensed development machine, and placing an Ftp control on it. If you use this database (on any machine) you will never get the trial. Therefore, to be clear, it is imperative that you start anew, creating a new database once you have installed the license on your machine.

There is a second option. If you use the control as a reference (instead of placing it on the form), you can place your license number in the registry of the machine where the database resides, and you will not see a trial (see the help file Distribution page, under "Distribution Under IIS" for the location of the license in the registry). This only works if you use the control as a reference. For example: Private WithEvents Ftp1 As Ftp Set Ftp1 = New Ftp

Access XP:

Microsoft has changed the license handling in Access XP to account for a trial component getting registered. If you currently have a trial component and register the product, you only need to cut the component from the Access form and paste it back on the form to cache the correct license code.


Excel

Microsoft Excel Environment

WARNING! Under most circumstances, a workbook is which a trial control is inserted will always be in trial. For that reason, it is not recommended to insert a control onto an Excel workbook. Add the control as a reference and use the distribution technique described under Distributing in Scripting Environments.


BCB4

Borland C++Builder 4 Environment

The Borland C++Builder 4 samples in this toolkit were compiled with Borland C++Builder 4.0 with NO updates applied. Due to the fact that wrapper code is not always backward compatible, some code may need to be changed if any other version is used to open these samples.

Using the Sample Applications:

Before you can use the sample applications you MUST add the PowerTCP Tools that are in the sample to the Component Library.

Adding PowerTCP Tools into the Component Library:

  1. Start BCB4 and Close any open projects.

  2. From the Main Menu choose Component | Import ActiveX Control.

  3. Choose the Tool to install:

Examples:

  • Dart FTP Control

  • Dart Telnet Control

  • Dart Server Control

  4. Click the 'Install' Button.

  5. Use the default dclusr40.bpk and click 'OK'.

  6. Answer 'Yes' to the rebuild.

  7. When the rebuilding process is done, close BCB4 saving the changes to dcluser.

Removing PowerTCP Tools from the Component Library:

  1. Start BCB4 and Close any open projects.

  2. Open the project where you installed the controls ( This is usually Lib\dclusr40.bpk ).

  3. Remove the dcr and cpp for the Control you wish to remove.

  4. Re-Compile the library.

  5. Close BCB4.

To ensure that all traces of the controls are removed from the library, delete the relevant source files from the Imports directory

Environment Specific Quirks

The samples were built by importing Dart controls via "Component / Import ActiveX Control". The wrapper code generated by the compiler was left untouched. Doing so has the following caveats (i.e., bugs) from the wrapper code created by the BCB wizard. (These may be fixed in a future BCB release):

  1. Control methods and property usage that generate run-time errors can be caught via a try/catch block that catches the Exception type in BCB 3. This is broken in 4 but works when using the global catch (...) syntax. In BCB 3 the Exception object Message property is set to the program name, source file, and line number. This is inconsistent with all other containers which set the error description to that generated by the control.

To get around this, trap the error description in the control's Error event and use that in the try/catch block.

  2. In BCB4, Control methods which do not return a value, such as the Telnet Connect method, do not get wrapped with ANY error checking whatsoever. To trap run-time errors when using these methods in blocking mode you must put in your own error wrapping as such:

try

{

....

Telnet->Connect(Rname,Rport,Lname,Lport);

if (TelnetError) throw new Exception(TelnetErrorDescription);

...

...any more lines of code to execute

...

}

catch (Exception &e)

{

Msgbox(e.Message);

}

where TelnetError and TelnetErrorDescription are String variables set in the Telnet Error event.

  3. To prevent an unwanted system messagebox popup when a control throws a run-time error:

In BCB3, put in the code:

bool TDebugHlpr<TCHAR>::PromptOnHrCheckFailure= false;

In BCB4, define the preprocessor definition: NO_PROMPT_ON_HRCHECK_FAILURE in the Conditional Defines of the project options.

  4. When using any Dart control that includes ErrorConstants, a compiler error for ambiguity between namespace conflicts may occur. You will need to physically modify the wrapper code for BCB3 and remove one of the ErrorConstants definitions or make some other such change. In BCB4, the ambiguity error is only generated if implementing the Error event.

To get around this and not modify the wrapper code: modify the client source to force the namespace in front of the ErrorConstants in the Error event in the .h and .c files like such:

void __fastcall TfrmMain::Telnet1Error(TObject *Sender,

Darttelnet_tlb::ErrorConstants Number, BSTR Description)

The IDE will complain every time a build is made with the popup: "The Telnet1Error method referenced by Telnet1->OnError has an incompatible parameter list. Remove the reference?" Always select "NO", otherwise the IDE will unlink the event and it will never occur at runtime.

This can be permanently fixed by modifying the ill-generated wrapper code in the components package where the control resides.


BCB5

Borland C++Builder 5 Environment

The Borland C++Builder 5 samples in this toolkit were compiled with Borland C++Builder 5.0 with Update 1 applied. Due to the fact that wrapper code is not always backward compatible, some code may need to be changed if any other version is used to open these samples.

Using the Sample Applications:

Before you can use the sample applications you MUST add the the PowerTCP Tools that are in the sample to the Component Library.

Adding PowerTCP Tools into the Component Library:

  1. Start BCB5 and Close any open projects.

  2. From the Main Menu choose Component | Import ActiveX Control.

  3. Choose the Tool to install:

Examples:

  • Dart FTP Control

  • Dart Telnet Control

  • Dart Server Control

  4. Click the 'Install' Button.

  5. Use the default dclusr50.bpk and click 'OK'.

  6. Answer 'Yes' to the rebuild.

  7. When the rebuilding process is done, close BCB5 saving the changes to dcluser.

Removing PowerTCP Tools from the Component Library:

  1. Start BCB5 and Close any open projects.

  2. Open the project where you installed the controls (This is usually Lib\dclusr50.bpk).

  3. Remove the dcr and cpp for the Control you wish to remove.

  4. Re-Compile the library.

  5. Close BCB5.

To ensure that all traces of the controls are removed from the library, delete the relevant source files from the Imports directory

Environment Specific Quirks

The samples were built by importing Dart controls via "Component / Import ActiveX Control". The wrapper code generated by the compiler was left untouched. Doing so has the following caveats (i.e., bugs) from the wrapper code created by the BCB wizard. (These may be fixed in a future BCB release):

  1. Control methods and property usage that generate run-time errors can be caught via a try/catch block that catches the Exception type in BCB 3. This is broken in 5 bu works when using the global catch (...) syntax. In BCB 3 the Exception object Message property is set to the program name, source file, and line number. This is inconsistent with all other containers which set the error description to that generated by the control.

To get around this, trap the error description in the control's Error event and use that in the try/catch block.

  2. In BCB5, Control Methods which do not return a value, such as the Telnet Connect method, do not get wrapped with ANY error checking whatsoever. To trap run-time errors when using these methods in blocking mode you must put in your own error wrapping as such:

try

{

....

Telnet->Connect(Rname,Rport,Lname,Lport);

if (TelnetError) throw new Exception(TelnetErrorDescription);

...

...any more lines of code to execute

...

}

catch (Exception &e)

{

Msgbox(e.Message);

}

where TelnetError and TelnetErrorDescription are String variables set in the Telnet Error event.

  3. To prevent an unwanted system messagebox popup when a control throws a run-time error:

In BCB3, put in the code:

bool TDebugHlpr<TCHAR>::PromptOnHrCheckFailure= false;

In BCB4, define the preprocessor definition: NO_PROMPT_ON_HRCHECK_FAILURE in the Conditional Defines of the project options.

  4. When using any Dart control that includes ErrorConstants, a compiler error for ambiguity between namespace conflicts may occur. You will need to physically modify the wrapper code for BCB3 and remove one of the ErrorConstants definitions or make some other such change. In BCB4, the ambiguity error is only generated if implementing the Error event.

To get around this and not modify the wrapper code: modify the client source to force the namespace in front of the ErrorConstants in the Error event in the .h and .c files like such:

void __fastcall TfrmMain::Telnet1Error(TObject *Sender,

Darttelnet_tlb::ErrorConstants Number, BSTR Description)

The IDE will complain every time a build is made with the popup: "The Telnet1Error method referenced by Telnet1->OnError has an incompatible parameter list. Remove the reference?" Always select "NO", otherwise the IDE will unlink the event and it will never occur at runtime.

This can be permanently fixed by modifying the ill-generated wrapper code in the components package where the control resides.


Delphi4

Delphi 4 Environment

The Delphi 4 samples in this toolkit were compiled with the Delphi 4.0 - Update 3

IMPORTANT - WHAT TO DO AFTER GETTING A SERIAL NUMBER

If you originally added your PowerTCP components during the trial period, you will need to remove and read the components after getting your serial number. Follow the directions below for removing the components, then follow the directions to read them. The next time you recompile your application, the correct runtime license will be inserted.

Using the Sample Applications:

Before you can use the sample applications you MUST add the PowerTCP Tools that are in the sample to the Component Library. See below for instructions.

Delphi Specific Problems

Delphi seems to have trouble recreating the DFM while our controls are displaying their trial license splash message. If you consistently get an error when loading the project, try loading Delphi before loading the project, as opposed to clicking on the DPR.

Adding PowerTCP Tools into the Component Library:

  1. Start Delphi4 and close any open projects.

  2. From the Main Menu choose Component | Import ActiveX Control.

  3. Choose the Tool to install:

Examples:

  • Dart FTP Control

  • Dart Telnet Control

  • Dart Server Control

  4. Click the 'Install' Button.

  5. Use the default dclusr40.dpk and click 'OK'.

  6. Answer 'Yes' to the rebuild.

  7. When the rebuilding process is done, close Delphi4 saving the changes to dcluser.

Removing PowerTCP Tools from the Component Library:

  1. Start Delphi4 and Close any open projects.

  2. Open the project where installed the controls. This is usually Lib\dclusr40.dpk.

  3. Remove the dcr and cpp for the Control you wish to remove.

  4. Re-Compile the library.

  5. Close Delphi4.

To ensure that all traces of the controls are removed from the library, delete the relevant source files from the Imports directory.

What To Do When Your Distributed App Displays a Trial Message:

This usually means that you originally added your PowerTCP components during the trial period and you did not remove and read the components. Follow the directions above for removing the components, then follow the directions to read them. The next time you recompile your application, the correct runtime license will be inserted.

Note about dynamic instantiation in non-VB/VBA environments (when not placing a control on a form):

PowerTCP uses what is known as ClassFactory2 licensing. This is a system developed by Microsoft as part of the COM architecture. All of the major development environments that we use support this type of licensing when a control is placed on a form, however, only VB or VBA type environments support it when the control is "created" without a form. By created, this mean using Dim as New, not CreateObject. Of the other environments, we currently only provide direct support only for dynamic usage in Visual C++. See the component wrappers for the code needed to instantiate an object with a license. ( Example: ITcp.h and ITcp.cpp included with the sample projects )

If you absolutely HAVE to use our products in a project without a form, you will need to get direction from the company that makes the environment ( Example: Borland, Sybase ) on how to use COM objects that require ClassFactory2 licensing.

If contacting them is not an option or is too costly, we may be able to assist you if you have one of the higher level support options or purchase incident support.


Delphi5

Delphi 5 Environment

The Delphi 5 samples in this toolkit were compiled with the Delphi 5. If you use any other version of Delphi, or Delphi 5 with a service pack, you may have to modify the samples to get them to compile. This is because Borland changes the naming convention in the wrappers they create with each update.

IMPORTANT - WHAT TO DO AFTER GETTING A SERIAL NUMBER

If you originally added your PowerTCP components during the trial period, you will need to remove and read the components after getting your serial number. Follow the directions below for removing the components, then follow the directions to read them. The next time you recompile your application, the correct runtime license will be inserted.

Using the Sample Applications:

Before you can use the sample applications you MUST add the PowerTCP Tools that are in the sample to the Component Library. See below for instructions.

Delphi Specific Problems

Delphi seems to have trouble recreating the DFM while our controls are displaying their trial license splash message. If you consistently get an error when loading the project, try loading Delphi before loading the project, as opposed to clicking on the DPR.

Adding PowerTCP Tools into the Component Library:

  1. Start Delphi5 and close any open projects.

  2. From the Main Menu choose Component | Import ActiveX Control.

  3. Choose the Tool to install:

Examples:

  • Dart FTP Control

  • Dart Telnet Control

  • Dart Server Control

  4. Click the 'Install' Button.

  5. Use the default dclusr50.dpk and click 'OK'.

  6. Answer 'Yes' to the rebuild.

  7. When the rebuilding process is done, close Delphi5 saving the changes to dclus.

Removing PowerTCP Tools from the Component Library:

  1. Start Delphi5 and Close any open projects.

  2. Open the project where installed the controls. This is usually Lib\dclusr50.dpk.

  3. Remove the dcr and cpp for the Control you wish to remove.

  4. Re-Compile the library.

  5. Close Delphi5.

To ensure that all traces of the controls are removed from the library, delete the relevant source files from the Imports directory.

What to do When Your Distributed App Displays a Trial Message:

This usually means that you originally added your PowerTCP components during the trial period and you did not remove and read the components. Follow the directions above for removing the components, then follow the directions to read them. The next time you recompile your application, the correct runtime license will be inserted.

Note about dynamic instantiation in non-VB/VBA environments (when not placing a control on a form):

PowerTCP uses what is known as ClassFactory2 licensing. This is a system developed by Microsoft as part of the COM architecture. All of the major development environments that we use support this type of licensing when a control is placed on a form, however, only VB or VBA type environments support it when the control is "created" without a form. By created, this mean using Dim as New, not CreateObject. Of the other environments, we currently only provide direct support only for dynamic usage in Visual C++. See the component wrappers for the code needed to instantiate an object with a license. ( Example: ITcp.h and ITcp.cpp included with the sample projects )

If you absolutely HAVE to use our products in a project without a form, you will need to get direction from the company that makes the environment ( Example: Borland, Sybase ) on how to use COM objects that require ClassFactory2 licensing.

If contacting them is not an option or is too costly, we may be able to assist you if you have one of the higher level support options or purchase incident support.


FoxPro

Visual FoxPro Environment

The Visual FoxPro Samples in this toolkit were compiled using Visual FoxPro 6.0 with SP3

Using the Samples

  1. Open the project's .pjx with FoxPro.

  2. Say "yes" to moving the project.

  3. From the Project Manager choose Document | Forms | Main.

  4. Press the "Run" Button.


Pb6

PowerBuilder Environment

The PowerBuilder Samples in this toolkit were compiled with PowerBuilder 6.5.

At the time this file was written, we were using build 585 EBF (Emergency Bug Fix) of the PowerBuider DLLs. This build is required to use most parts of PowerTCP Tools. If the build is not shipping by the time this toolkit is released, you will need to contact Sybase to obtain these updated DLLs.

The PowerBuilder samples are in <ROOT>\Samples\Pb6

Using the Sample Apps:

Due to the fact that PowerBuilder caches run-time licenses, there are some steps that you must take before you can run the samples apps. When you load the sample for the first time, you will need to:

  1. Copy and paste each Dart control to a new control.

  2. Delete the old control.

  3. Rename the new control to the original name.

30-day Trial Message Appearing After Control Is Licensed:

The license info is compiled into the program. If the trial message appears in a PowerBuilder app, and you believe you have done everything correctly, it means one of two things:

  1. The component is not inserted on a window (you used CREATE to instantiate it)

  2. The component was inserted on the window during the trial period.

If 1 applies to you, then you will have to either redesign your app so that the component is on a window or install the license key from your development machine manually on each machine that you are distributing your app to.

If 2 applies to you the solution is simple. On a licensed machine, open your PB project and, one at a time, find each Dart component , select it, hit ctrl-x followed by ctrl-v (cut and paste the component) then recompile your app. If you follow these steps and you still get a trialmessage when deploying your apps, it probably means the control is being created in a way that does not facilitate licensing. You can't dynamically create our controls and get the licensing into the EXE. You must insert the control onto a window or Userobject. When you insert a control make sure you use "Insert" and not "Create New"

Inserting PowerTCP Tools

  1. Choose "Controls" from the Window Painter menu.

  2. Choose "OLE".

  3. Click the "Insert Control" Tab.

  4. Choose the Tool you wish to insert.

Examples:

  • Dart FTP Control

  • Dart Telnet Control

  • Dart Server Control

Environment Specific Quirks

Telnet Only: Cmd Event not supported due to passing of Variant Pointer.


Vb5

Visual Basic 5 Environment

The Visual Basic 5 Samples in this toolkit were compiled using Visual Basic 5.0 with Service Pack 3.

PowerTCP may not work properly without Service Pack 3, so if you experience problems, please install it before contacting support.


Vb6

Visual Basic 6 Environment

The Visual Basic 6 Samples in this toolkit were compiled using Visual Basic 6.0 with SP3.


Vc6

Visual C++ 6.0 Environment

Samples that use Dart's Class Wrapper

Some of the sample applications were created using a wrapper that was written by Dart. The following is a list of these samples:

Emulation Tool

  • VT Emulator (wrapper for Telnet control only, uses MFC for VT control)

FTP Tool

  • GetUrl

  • ListView Client

Mail Tool

  • SMTP Client

  • IMAP Client

  • POP Client

  • SMTP Quicksend Client

Winsock Tool

  • TCP Client

  • UDP Client

  • TCP Blaster

  • DNS Client

  • Ping Client

  • DartChat

  • WebServer

Server Tool

  • EchoServer

SNMP Tool

  • SNMP Agent

  • SNMP VarChecker

  • MibViewer

  • SNMP Manager

Telnet Tool

  • Telnet Client

  • AutoLogin Demo

Web Tool

  • PageFetch

Web Enterprise Tool

  • PageFetch

These samples require no additional effort to compile and run.

A trial message will appear periodically while on the trial period.

To eliminate the trial message after you have purchased the Tool, follow these steps:

Find your license number in the registry under:

HKEY_LOCAL_MACHINE\SOFTWARE\Dart\PowerTCP\License\<Tool>

Use the value found there for the value of LICENSE:

Example:

#define LICENSE "Number:UnlockCode:CompanyName"

Executables compiled with a valid number will not display a trial message.

Samples Where PowerTCP Controls are Inserted Using MFC Appwizard

If you insert a control during your trial period and later register you will have to follow these steps to get the new license info into your project:

  1. Open the Project.

  2. Open the Window the control is on and remember it's resource ID.

  3. Delete the control and it's Resource ID.

  4. Build clean and let the error's happen.

  5. Reinsert the control and give it the same Resource ID.

The samples are supplied without any Dart controls. You will need to drop the controls onto dialog forms inside the projects as follows:

RAS Client

Load the Ras Simple Client project into VC, bring up the IDD_RAS dialog into the dialog editor. Insert a Dart Ras Control onto the form. Uncheck the Visible flag. Bring up the IDD_VCRAS_DIALOG dialog into the dialog editor. Insert a Dart Ras Control just below the "Phonebook Entry:" Caption, and set its width to fill the Connection GroupBox.

SNMP Explorer Sample

Load the SNMPExplorer Sample project into VC, bring up the IDD_SNMPEXPLORER_DIALOG dialog into the dialog editor. Insert a Dart Manager Control onto the form.

VT Emulator

Load the Emulator Client project into VC, bring up the IDD_TELNET_FORM dialog into the dialog editor. Insert a Dart Vt Control onto the form.

SecureEchoServer

Load the SecureEchoServer project into VC, bring up the IDD_CERT dialog into the dialog editor. Insert a Dart CertificateList Control onto the form. MAKE SURE YOU USE THE /A PARAMETER TO RUN THE SERVER AS AN APP!

SecureClient

Load the SecureClient project into VC, bring up the IDD_CERT dialog into the dialog editor. Insert a Dart CertificateList Control onto the form.


COM+/MTS

The following components support MTS/COM+: Tcp, Udp, Daemon, WebASP, Ftp, Smtp, Pop, Imap, Manager, Agent, Dns, Ping, Vt and Zip.

To install an MTS component:

  1. Open Component Services (typically, this can be found by doing something like Start --> Control Panel --> Administrative Tools --> Component Services).

  2. Navigate to the COM+ Applications node (for example, Component Services --> MY Computer --> COM+ Applications)

  3. Choose the node you wish to install into (for example, IIS In-Process Applications).

  4. Right-click on Components. Choose New --> Component. This should start the COM+ Component Installation Wizard.

  5. Choose Next

  6. Choose Import Component(s) That Are Already Registered.

  7. Choose the component(s) you would like to import and choose Next.

  8. Click Finish.


Dotnet Interop

.NET/COM Interop

When using the ActiveX controls in .NET dynamically (not placing them on a form), steps must be taken to ensure proper licensing. In the example below, Zip is used, but these steps apply to any of the controls:

  1. In the project, add a reference to AxDartZip by placing the control on a form. The control (and if necessary, the form) can then be deleted.

  2. Use the MS Reflection class to add your licensed control, as shown in the code below.

Private Withevents Zip1 As AxDartZip.AxZip

Private Const SERIAL_NUMBER = "" 'Add Your Serial Number

...

Zip1 = New AxDartZip.AxZip()

Dim fieldInfo As System.Reflection.FieldInfo

fieldInfo = GetType(System.Windows.Forms.AxHost).GetField("licenseKey", Reflection.BindingFlags.NonPublic Or Reflection.BindingFlags.Instance)

fieldInfo.SetValue(Zip1, SERIAL_NUMBER)

Zip1.CreateControl()

  • If you are using a licensed object that is not a control (ie, Message object, Mib object), you cannot create a new instance of it. Instead, use a control that has a property with the object as a data type (for example, AxAgent.Mib) and set the new instance to it (Dim Mib As SnmpMib, Set Mib = Agent1.Mib).

  • You will not be able to use this procedure in a .Net Windows Service, a .Net Web Service, or a .Net Web Application. For these applications, one should use DartZip.ZipClass (not AxDartZip.AxZip). For licensing, the ASP approach should be used (placing the license in the registry of the machine running the app).

  • If you use the control on a form, no special steps are required for licensing.


Quick Start Overview

Ping Enterprise Tool Quick Start

This section of the documentation is intended to get you developing using the Ping Enterprise Tool as quickly as possible. For this reason, only the most general usage scenarios are described. If you are looking for more specific functionality, please review either the Objects Reference or the samples included with the install.

This Quick Start uses Visual Basic as it has the least environment-specific code overhead. If you would like to see examples in C++, Delphi, ASP, or other environments, see the installed samples.

This topic covers:

  • Using Ping Synchronously

  • Using Ping Asynchronously


Using Ping Synchronously

Using the Ping Enterprise Control Synchronously

When working in a scripting environment such as ASP that requires code to be executed in a synchronous fashion, the Echo method is used rather than StartEcho. When calling a blocking method, the function will only return once a response to the ping has been received or an error has occurred. Also, when using Echo, all response data is returned as a PingReply object.

1. Issue a ping from any subroutine

Private Sub Command1_Click()
Dim PR As PingReply

Set PR = Ping1.Echo("www.dart.com")

'Check for errors and return information

If PR.Error = 0 Then

Text1.Text = PR.RemoteName & " (" & PR.RemoteAddress & "): " & PR.ElapsedTime & " milliseconds"

ElseIf Error = 11010 Then

Text1.Text = PR.RemoteName & " (" & PR.RemoteAddress & "): Ping timed out"

Else

Text1.Text = PR.RemoteName & " (" & PR.RemoteAddress & "): Error number: " & PR.Error

End If

End Sub


Using Ping Asynchronously

Using the Ping Enterprise Control Asynchronously

The true capability of the PowerTCP Ping Enterprise Tool is evident when used in an asynchronous fashion, which means that the function will return before receiving a reply from the remote host and the applicaiton will continue to execute. Use the StartEcho method to initiate the ping and the EchoComplete event will return information from the ping. When sending multiple pings in a loop, the Ping Enterprise control will properly match all the responses.

1. Issue a ping from any subroutine

'Pings www.dart.com with default settings. Passes "my ping" as state to return in the completion event.

Ping1.StartEcho "www.dart.com", "my ping"

2. Receive the reply in the EchoComplete event

Private Sub Ping1_EchoComplete(ByVal RemoteName As String, ByVal RemoteAddress As String, ByVal ElapsedTime As Long, ByVal state As Variant, ByVal Data As Variant, ByVal Error As Long, ByVal ErrorDescription As String)

'Check for errors and return information

If Error = 0 Then

Text1.Text = RemoteName & " (" & RemoteAddress & "): " & ElapsedTime & " milliseconds"

ElseIf Error = 11010 Then

Text1.Text = RemoteName & " (" & RemoteAddress & "): Ping timed out"

Else

Text1.Text = RemoteName & " (" & RemoteAddress & "): Error number: " & Error

End If

End Sub


Ping Enterprise Control

Properties Methods Events

Product Notes

The Ping Enterprise Control is a high-performance ActiveX control that is designed to asynchronously maintain a continously high rate of ICMP echoes to one or more specified devices using a powerful multi-threaded engine. A synchronous option is available for scripting environments such as ASP.

Miscellaneous

Product | PowerTCP Ping Enterprise Tool
Prog ID | DartPing.Ping.1
File | DartPing.dll
Dependencies | None
Threading | Apartment Model
Licensed | Yes


Count Property

The current number of outstanding ping requests.

Syntax

Object.Count

Part | Description
Object | Evaluates to a Ping_Enterprise Control

Data Type

Integer

Remarks

Read-Only. When the control is used asynchronously, multiple pings may be sent in a short period of time. This property will track how many ping requests are still outstanding. Once a response is registered by the control, this value is decremented by one. When no ping requests are outstanding, the value is 0.


Data Property

A value representing the data sent to and subsequently returned from the remote host.

Syntax

Object.Data

Part | Description
Object | Evaluates to a Ping_Enterprise Control

Data Type

Integer

Remarks

When a ping request is sent any data that is included as part of the packet is returned to the sender. By default no data is sent to the remote host.


PowerBuilderMode Property

Specifies whether PowerBuilder is the current development environment.

Syntax

Object.PowerBuilderMode

Part | Description
Object | Evaluates to a Ping_Enterprise Control

Data Type

Boolean

Remarks

Default is false. PowerBuilder requires unique event handling and when setting this property to True, the EchoCompleteEx event will be raised rather than the EchoComplete event in response to the asynchronous StartEcho method. All PowerBuilder users should set this property to True and use the EchoCompleteEx event.


ReverseLookup Property

Specifies whether a reverse lookup should be performed on an IP address.

Syntax

Object.ReverseLookup

Part | Description
Object | Evaluates to a Ping_Enterprise Control

Data Type

Boolean

Remarks

Default is False. By default, if an IP address is used when conducting a ping, reverse lookup will not occur to maximize performance.


Tag Property

Stores any text the user wants to associate with the control.

Syntax

Object.Tag

Part | Description
Object | Evaluates to a Ping_Enterprise Control

Data Type

String


TimeOut Property

The length of time (in milliseconds) to wait for an ping response before throwing an error .

Syntax

Object.TimeOut

Part | Description
Object | Evaluates to a Ping_Enterprise Control

Data Type

Long

Remarks

Default is 5000

If a response from a remote host is not received within the specified time, an error will raised.


TimeToLive Property

The maximum number of hops to take while attempting to reach the remote host.

Syntax

Object.TimeToLive

Part | Description
Object | Evaluates to a Ping_Enterprise Control

Data Type

Long

Remarks

Defaults to 100 . This value controls how many hops the echo will make before returning. This value should not be altered unless your application is designed to trace the path of the ping, such as a Trace Route utility.


Abort Method

Aborts the current operation.

Syntax

Object.Abort

Part | Description
Object | Evaluates to a Ping Enterprise Control

Remarks

This method can be used at any time to stop an operation.


Echo Method

Send a ping and wait for a reply.

Syntax

value = Object.Send RemoteHost

Part | Description
Object | Evaluates to a Ping_Enterprise Control.
RemoteHost | String. Name of the server to query. May either be an address in dot notation (nnn.nnn.nnn.nnn) or a name, such as host.dart.com.
Value | PingReply. The object containing all response information returned from the Echo.

Remarks

This method will send an echo request and block until the response returns. All response information will be returned as a PingReply object. This blocking method is recommended for simple requirements or scripting environments such as ASP. The recommended usage for high-performance situations is the asynchronous StartEcho method.


StartEcho Method

Send an asynchronous ping and don't wait for a reply.

Syntax

Object.Send RemoteHost, State

Part | Description
Object | Evaluates to a Ping_Enterprise Control.
RemoteHost | String. Name of the server to query. May either be an address in dot notation (nnn.nnn.nnn.nnn) or a name, such as host.dart.com.
State | Variant. Any data that should be returned in the EchoComplete event.

Remarks

This method will send an asynchronous echo request and immediately return, not waiting for the echo response. When a response is received the EchoComplete event will be raised. This non-blocking method is recommended for most operations and will provide the highest performance when multiple pings are required. For scripting environments such as ASP or simple usage, the blocking Echo method is used. If PowerBuilder is the development environment, set PowerBuilderMode to True and use the EchoCompleteEx event.


EchoComplete Event

Raised when an asynchronous ping operation is completed.

Syntax

Private Sub Object_Progress ([Index as Integer,] RemoteName as String, RemoteAddress as String, ElapsedTime as Long, State as Variant, Data as Variant, Error as Long, ErrorDescription as String)

Part | Description
Object | Evaluates to a Ping Enterprise Control
Index | Integer. Array index if the object is part of an array.
RemoteName | String. Name of the server queried.
RemoteAddress | File. The IPP address of the server queried. This will be in dot notation (nnn.nnn.nnn.nnn).
ElapsedTime | Long. Time between sending the ping request and receiving the response (round-trip time in milliseconds).
State | Long. Any user-defined data passed in the StartEcho method.
Data | Long. Optional data that is sent and returned with each ping request.
Error | Long. Any errors reported during the operation.
ErrorDescription | String. The description of any errors reported during the operation.

Remarks

This event will be raised when a ping operation has been started using the asynchronous StartEcho method.


EchoCompleteEx Event

Raised when an asynchronous ping operation is completed and PowerBuilderMode is used.

Syntax

Private Sub Object_ProgressEx ([Index as Integer,] RemoteName as String, RemoteAddress as String, ElapsedTime as Long, State as Variant, Data as Variant, Error as Long, ErrorDescription as String)

Part | Description
Object | Evaluates to a Ping Enterprise Control
Index | Integer. Array index if the object is part of an array.
RemoteName | String. Name of the server queried.
RemoteAddress | File. The IPP address of the server queried. This will be in dot notation (nnn.nnn.nnn.nnn).
ElapsedTime | Long. Time between sending the ping request and receiving the response (round-trip time in milliseconds).
State | Long. Any user-defined data passed in the StartEcho method.
Data | Long. Optional data that is sent and returned with each ping request.
Error | Long. Any errors reported during the operation.
ErrorDescription | String. The description of any errors reported during the operation.

Remarks

This event will be raised when a ping operation has been started using the asynchronous StartEcho method and PowerBuilderMode is True. A PoweBuilder specific event is required as certain COM interface implementations in PowerBuilder are mutually exclusive with other development environments.


PingReply Object

Properties

This object is the return value for the Echo method. All response information from the ping will be contained within.

Miscellaneous

Product | PowerTCP Ping Enterprise Tool
Prog ID | DartPing.PingReply.1
Create | Yes
File | DartPing.dll
Dependencies | None
Threading | Apartment Model
Licensed | No


Data Property

A value representing the data sent to and subsequently returned from the remote host.

Syntax

Object.Data

Part | Description
Object | Evaluates to a PingReply object.

Data Type

String

Remarks

When a ping request is sent any data that is included as part of the packet is returned to the sender. By default no data is sent to the remote host.


ElapsedTime Property

Time between sending the ping request and receiving the response (round-trip time in milliseconds).

Syntax

Object.ElapsedTime

Part | Description
Object | Evaluates to a PingReply object.

Data Type

Long

Remarks

When a ping request returns, this value will contain the round-trip time in milliseconds.


Error Property

The error number representing a problem with the requested operation .

Syntax

Object.Error

Part | Description
Object | Evaluates to a PingReply object.

Data Type

Long

Remarks

If any error occurs in the attempt to ping a remote host, the error number will be reported by this property. For the description of the error, see ErrorDescription.


ErrorDescription Property

The error number representing a problem with the requested operation.

Syntax

Object.ErrorDescription

Part | Description
Object | Evaluates to a PingReply object.

Data Type

Long

Remarks

If any error occurs in the attempt to ping a remote host, the error description will be reported by this property. For the error number, see ErrorDescription.


RemoteAddress Property

The address in dot notation of the remote host.

Syntax

Object.RemoteAddress

Part | Description
Object | Evaluates to a PingReply object.

Data Type

String

Remarks

The address is in the form of nnn.nnn.nnn.nnn.


RemoteName Property

The name of the remote host device that has been pinged.

Syntax

Object.RemoteName

Part | Description
Object | Evaluates to a PingReply object.

Data Type

String

Remarks

This property is the name of the device just queried.


Threading Model

Most PowerTCP Controls are marked as Apartment Model Threaded. PowerTCP Controls contain multi-threaded protection for all global and static variables, making it safe for use in applications that use the same component in multiple Single Thread Apartments (STAs).

Single-threaded Applications

Most application developers develop single-threaded applications (the application has only one STA). Most of the sample applications included with PowerTCP Controls are written using this model. When Timeout is greater than 0, the communication components process Windows messages for the thread, allowing the user interface and all other windows to function normally.

Multi-threaded Applications

In Visual Basic you can make a multi-threaded application by creating an ActiveX executable with special objects that are created using CreateObject(). The WebServer application, included with the PowerTCP Winsock Tool, was written using this technique. Each connection is managed within a unique STA, so busy threads do not interfere with the main STA that processes user interface messages and windows.

When you use PowerTCP on Active Server Pages, each page operates within its own STA, making IIS a multi-threaded application.

Within Visual C++, you can likewise create multiple STAs for your application, and safely use one or more PowerTCP Controls within each STA.


PowerTCP Getting Started

The following topics provide a general overview of information related to the entire PowerTCP product line:

  • PowerTCP Introduction

  • PowerTCP Tools Overview

  • License Installation

  • Trial Operation

  • Support

  • Distribution

  • Debugging Notes

  • PowerTCP Visual C++ Notes