Copyright: Copyright ® 1996 Progress Software Corporation


 Crescent Internet ToolPak Help

Copyright          Technical Support          Distribution

Thank you for purchasing the Crescent Internet ToolPak. It is a comprehensive collection of controls that provide Visual Basic programmers with a powerful and efficient tool for building applications and utilities for use with both the Intranet and the Internet.

From this topic, you can access the following information about the Crescent Internet ToolPak:

The Crescent Internet ToolPak product components

The Crescent Internet ToolPak Architecture

File distribution and application deployment

Hardware and software requirements

Technical Support

Glossary

For programmers new to the Internet or the Internet application development environment, we recommend that you read through the glossary to familiarize yourself with the terminology.


The Internet ToolPak Components
The Crescent Internet ToolPak Components

Related Topics

The Crescent Internet ToolPak consists of a collection of Visual Basic controls, an Internet Mail Wizard, and a comprehensive set of demonstration programs. The components are described in the following sections.

The Crescent Internet ToolPak Controls

This product contains the following controls:

Control Icon	Name	Control File	Description
	FTP Control (CIFTP)	CIFTP.OCX CIFTP16.OCX	Enables the programmer to build client applications that support file transfers to and from FTP servers.
	WEB control (CIHTTP)	CIHTTP.OCX CIHTTP16.OCX	Enables the programmer  to build applications that access HTTP servers.
	Simple Mail Control (CISMTP)	CIMAIL.OCX CIMAIL16.OCX	Enables the programmer to build client applications that can send mail using the SMTP protocol.
	Retreive Mail Control (CIPOP)	CIMAIL.OCX CIMAIL16.OCX	Enables the programmer to build client applications that can retrieve mail from POP3 mail servers.
	MIME control (CIMIME)	CIMIME.OCX	Enables the programmer to build client applications that encode files that you intend to mail, or decode files that have been encoded using the MIME standard.
	NEWS control (CINEWS)	CINEWS.OCX CINEWS16.OCX	Enables the programmer to build client applications that can retrieve or post articles from or to NNTP servers.
	RAS control (CIRAS)	CIRAS.OCX CIRAS16.OCX	Enables the programmer to build client applications that can provide programmatic dial-up access to a network via SLIP, PPP, or the RAS proprietary protocol.
	Client/Server Control (CITCP)	CITCP.OCX CITCP16.OCX	Enables the programmer to build both client and server applications that support general purpose TCP/IP messaging and file transfer.
	TELNET Form (CITelnet)	CITelnet.FRM	Enables the programmer to provide programmatic access to the Telnet protocol.
	UUEncode/Decode Control (CIUU)	CIUU.OCX	Enables the programmer to build client applications that can encode files that you intend to mail, and decode files that have been encoded using the UUEncode/Decode standard.
The Internet Mail Wizard

The Internet Mail Wizard provides a convenient way to build simple applications with the Mail control.

Simply complete the textboxes displayed on the form as prompted by the wizard. Once youve answered the questions, the wizard builds a working application and ends itself. You can use the applications as built by the wizard, or as a stepping stone to building more complex applications. By default, they are installed in the CITPAK/WIZARD directory.

You access the Internet ToolPak Wizard from the Add-In Menu.

NOTE  	The Internet Mail Wizard is supported in 32-bit environments only.

The Demonstration Programs

The demonstration programs illustrate some programming uses for the controls. By default, they are installed in the CITPAK/DEMOS directory. See the ReadMe file for the list of demonstration files.


The Crescent Internet ToolPak Architecture

Related Topics

The Crescent Internet ToolPak controls enable you to develop client applications for Internet servers that include HTTP, NNTP, FTP, SMTP, TCP/IP and POP3 servers. (Note the TCP/IP control also enables you to create server applications.)

The client application create requests for data from the server. The server responds to the request by returning data to the control, or by returning no data to the control to indicate that the request failed.

Each of the Internet ToolPak controls support a unique set of methods that, when called, construct a request that complies with the servers requirements. (The servers requirements depend on the protocol or service that the server is providing.) The control constructs the request by taking the data from the properties. Once the request is constructed and sent to the server, the method is complete, and control returns to the application which can call another method and send another request to the server. When the client application receives a response from the server, the control internally parses the data, updates the appropriate properties and fires an event to indicate that the servers response was received. This is known as asynchronous programming.

If the application built and sent the request to the server, then waited for the server to respond by polling for the response, it would be called polled or synchronous programming.The application would be blocked, or suspended, until the server responded. In the asynchronous model, you simply send a request, and when the data is received from the server, the control fires an event to indicate that the data was received. You must place code in the event to process the data as it is received.

The advantage of the asynchronous structure is that your application continues with other tasks as it waits for data from the server. Once the server returns the data to the control, the application immediately responds to it, thus increasing performance. However, as the programmer, you must be aware that the properties that are updated with data from the server may not be available immediately after calling a method. Instead, you must place code that checks property values in the appropriate event module.

The following code sample illustrates the asynchrounous architecture, with code that connects a client application to an HTTP server. With most of the Internet ToolPak controls, you must set the HostName (or HostAddress) property and the port property to the port number on the server that provides the desired service (in this case the HTTP Port).

The code in the Form_Load procedure looks like this:

Form_Load()
CIHTTP1.HostName = WWW.MyHost.com
CIHTTP1.HTTPPORT = 80
nResult% = CIHTTP.ConnectToHTTPServer

HTTPServerConnection()
Code to perform once the connection attempt succeeds.
WSAError()
Code to perform if the connection attempt fails.

The application is connected when the HTTPServerConnection event fires. When the connection attempt succeeds, nResult% is an integer that represents the socket number opened by the ConnectToHTTPServer method. When the connection attempt fails, nResult% is 0 and the WSAError event fires. Note that the WSAError event occurs as a result of a Winsock error, and not an error from the server.

All of the controls adhere to the asynchronous programming model except the CIMAIL controls which adhere to the polled programming model (CIPOP and CISMTP).


About Server Connections

Related Topics

To identify computers on the network, TCP/IP, the Internet protocol, requires that each computer has a unique address known as a host address. A host address looks like this:

198.137.64.1

The Crescent Internet ToolPak controls implement this value as the HostAddress property.

Because a host address can be difficult to remember there is an alternate addressing system called the Domain Name System (DNS). The DNS uses a host name to identify the computer on the Internet. A host name looks like this:

organizationname.com

A host name has two parts: an organization name followed by the domain in which the host resides. In this example, the organization name is organizationname, and the domain is .com. A domain generally identifies the type of organization to which a host belongs. The following table shows some examples of Internet domains.

This domain . . .	Identifies this type of organization . . .
.com	Identifies commercial organizations.
.org	Identifies non-profit organizations.
.gov	Identifies U.S. government organizations.
.edu	Identifies educational institutions.
The Crescent Internet ToolPak controls implement the host name address as the HostName property.

Another advantage in using the DNS name rather than the Internet address is that host names generally do not change, though the IP address can. For example, if Progress Software, Inc. moved from Massachusetts to Texas, its IP address probably would change, while the DNS name (progress.com) probably would not. As a result, applications that access a machine by its host name would be unaffected while applications that access a machine by address would be.


Error Handling

Related Topics

There are two types of errors that you might encounter with the Internet ToolPak controls They are:

Winsock Errors

Winsock errors can occur for many reasons which include, but are not limited to, an unreachable network, a network timeout error, or an invalid host.

Winsock errors cause the WSAError event to fire. They also return a non-zero value to the called method.

Server Errors

A server error can occur when the server is not able to execute your command. This might occur because the data that you are requesting does not exist, or you dont have authority to perform the action. The server return codes are returned to the PacketReceived event.

The CITPAK.BAS file contains server return codes and Winsock error codes.


Standards Compliance

Related Topics

The Internet ToolPak controls comply, where practical, with the current Internet standards for the protocol that they support. The Internet standards are defined in documents called Request For Comments (RFC) documents. The following table identifies the protocol, the associated Internet ToolPak control and the RFC that it complies with.

This Protocol	and this control	comply with this RFC
SMTP	CISMTP	821
POP	CIPOP	1725
FTP	CIFTP	959
HTTP	CIHTTP	None
MIME	CIMIME	1521 and 1522
NNTP	CINEWS	977
RAS	CIRAS	None
TCP/IP	CITCP	None
UUEncode	CIUU	None
The CITelnet form (CITelnet)

The CITelnet form complies with the Telnet standard defined in RFC 854.


File Distribution and Application Deployment

Copyright          Technical Support

You can distribute any application you create using Internet ToolPak routines, as long as you distribute the application only as an executable. You may also distribute the Internet ToolPak control libraries (.OCX).

You cannot distribute the Internet ToolPak license (.LIC) files and you cannot distribute any Internet ToolPak source code or routines in such a way that other people can reuse them.

See the "End-user License Agreement" at the beginning of the Crescent Internet ToolPak User's Guide for more information about the license to use the Crescent Internet ToolPak.

To deploy applications that contain the Internet ToolPak controls, you must supply the Microsoft Foundation Class Library (MFC40.DLL), the Microsoft Visual C++ 4.0 Run-Time Library (MSVCRT40.DLL), and for the 32-bit environment you must also supply the WININET.DLL. Note that these objects and the controls must be registered.


System Requirements

Copyright          Technical Support          Distribution

The Internet ToolPak has these hardware and software requirements:

Microsoft Windows NT 3.51 or higher, or Microsoft Windows 95.

Microsoft Windows 3.1, Windows for Workgroups 3.11.

Microsoft Visual Basic 4.0 for Windows and the hardware and software that it
requires to function.


Crescent Internet ToolPak Technical Support

Before You Call Technical Support...

The Crescent technical support staff is ready to help you with problems that you encounter when installing or using Internet ToolPak. It does not matter what component of Internet ToolPak is causing problems; the Crescent technical support staff will do its best to help you succeed with Internet ToolPak.

If you need technical support, contact us using any of the following methods:

By Telephone	Contact Crescents North American technical support staff at (617) 280-3000  Monday through Friday from 9:00 a.m. to 5:00 p.m. EST.
By FAX	Contact Crescent by FAX at  (617) 280-4025.
Via BBS	Contact Crescent through our 24-hour bulletin board service at (617) 280-4221.
Via CompuServe	Contact Crescent through CompuServe address 70662,2605 Crescent also maintains a section in the MS Windows Components A+ Forum on CompuServe. To reach the Crescent section, type the following at the CompuServe prompt: GO CRESCENT
By Internet	Contact Crescent using the Internet address crescent-support@progress.com
By Mail	Address your correspondence to: Technical Support Crescent Division, Progress Software Corporation 14 Oak Park Bedford, Massachusetts 01730
Via WWW site	Contact Crescent using the URL http://crescent.progress.com
Via FTP site	Contact Crescent by FTP using ftp.progress.com/pub/crescent
Please have your product name, version number, serial number, and system configuration information available so that the Crescent technical support staff can process your support requests as efficiently as possible.


Before You Call Technical Support...

Copyright          Technical Support          Distribution

To maximize the effectiveness of your contact with Crescent's technical support, please have pertinent information available regarding your problem when you call. Before you call for technical support:

1.	Please read through the documentation thoroughly.

2.	Check the Demo programs.

3.	Check the Frequently Asked Questions topic in the on-line help.

We have found that many problems can be solved by applying the information contained in the documentation. If, after reading through text, you still cannot resolve your problem, please perform the following:

GPF? If you are getting a GPF (General Protection Fault), write down the information that is displayed when the error occurs. Also, note what your code was doing (in general terms).

ISOLATE IT. Try to isolate the cause of the error. If possible, step through your code with F8 and F9. Try to find the one line of code that is causing the error.

SCALE IT DOWN. Try to reproduce the problem in a small test program that you can send in. Call the technical support line to discuss your question and possibly arrange the method by which you can send in your test code.

CALL CRESCENT.


Copyright
Copyright © 1996 Progress Software Corporation

The information in this help file is subject to change without notice and Progress Software Corporation assumes no responsibility for any errors that may appear in this file.

Crescent Internet ToolPak™ is a trademark of Progress Software Corporation

All company and product names are the trademarks or registered trademarks of their respective companies.


The Crescent Internet ToolPak Architecture
Hardware and software requirements
File distribution and application deployment
Technical Support


The Crescent Internet ToolPak product components
About Server Connections
Error Handling
Standards Compliance


The Crescent Internet ToolPak product components
The Crescent Internet ToolPak Architecture
Error Handling
Standards Compliance


The Crescent Internet ToolPak product components
The Crescent Internet ToolPak Architecture
About Server Connections
Standards Compliance


The Crescent Internet ToolPak product components
The Crescent Internet ToolPak Architecture
About Server Connections
Error Handling


Contents
Glossary

A

Access Channel

Anchor

Article

B

C

Client

D

Data Channel

Domain name

Domain Name System (DNS)

E

F

File Transfer Protocol (FTP)

Firewall

G

H

Host

HostAddress

HostName

Hypertext

HyperText Markup Language (HTML)

HyperText Transfer Protocol (HTTP)

I

Internet Protocol (IP)

IP Address

J

K

L

Link

M

Mail List

N

Network News Transfer Protocol (NNTP)

O

P

Packet

Post Office Protocol (POP)

Port

Port Number

Protocol

Q

R

Request For Comment (RFC)

S

Server

Service

Simple Mail Transfer Protocol (SMTP)

Socket

Stream mode

T

Tags

Transport Control Protocol/Internet Protocol (TCP/IP)

U

Uniform Resource Locator (URL)

V

W

WinSock

World Wide Web (WWW or W3)

X

Y

Z


Access Channel

The channel used to pass commands/requests between FTP client and server machines. The access channel is one channel of a two channel model used by FTP. The other channel is called the data channel.


Anchor

Anchors are HTML formatting codes that have special meaning. They include a URL to specify links to data on the WWW.


Article

An article is a network news message. Articles are grouped by topic, called a newsgroup. Articles are stored on NNTP servers.


Client

A computer system or process that requests a service of another computer system or process. A workstation requesting the contents of a file from a file server is a client of the file server. See also server.


Data Channel

The channel used to pass file data between FTP client and server machines. The data channel is one channel of a two channel model used by FTP. The other channel is called the access channel.


Domain name

The name of a computer site (or subnetwork) on the Internet. Each organization on the Internet has a domain name for example, progress.com. To refer to a specific computer at a remote site, you must use a full host name, which includes a domain name.


Domain Name System (DNS)

An addressing system for computers on the Internet that allows the use of  names for computers instead of IP addresses. DNS is a query service that looks up host names and provides the equivalent host IP address.


File Transfer Protocol (FTP)

The TCP/IP based protocol that enables you to copy files between computers on the Internet.


Firewall

A security system that limits outside access to an Internet site.


Host

A computer that allows users to communicate with other host computers on a network. A host is usually a computer acting as a server. You may be able to login, access files, exchange mail, etc. by accessing a host using an appropriate protocol.


HostAddress

A property common to all of the Crescent Internet ToolPak controls that contains the IP address for a computer.


HostName

A property common to all of the Crescent Internet ToolPak controls that contains a computers name that equates to an IP address. A full host name is the name of the computer followed by the domain name, for example gorgon.progress.com.


Hypertext

A digital document or collection of documents that may include formatted text, images, sound, video, executable programs and links.


HyperText Markup Language (HTML)

A document formatting language that enables you to link information within single and multiple documents that are stored at single or multiple locations on the Internet. Defined in RFC 1866.


HyperText Transfer Protocol (HTTP)

The TCP/IP based protocol that enables sharing of hypertext documents.


Internet Protocol (IP)

The protocol that enables data to be passed from one computer to another.


IP Address

The unique 32-bit number assigned to a computer attached to the Internet. This number is expressed as four integers (one for each byte), separated by periods. For example: 192.9.145.23. The Crescent Internet ToolPak controls implement this value as HostAddress.


Link

A reference in a hypertext document that specifies a location in a hypertext document. A user may select (click on) the visual representation of  a link to view the referenced location in the document.


Mail List

A special kind of email address also known as an alias. Its function is to remail incoming mail to a list of subscribers.


Network News Transfer Protocol (NNTP)

The TCP/IP based protocol for the distribution, inquiry, retrieval, and posting of news articles. Defined in RFC 977.


Packet

A chunk of information sent over the network. The packet size and contents vary depending on the protocol.


Post Office Protocol (POP)

The TCP/IP based protocol that allows remote clients to retrieve email from a server. Defined in RFC 1725.


Port

A port is the portion of the computer that connects to external devices (usually communications devices). For example, an Ethernet card provides a network port. Internet protocols allow for multiple virtual ports known as sockets on a single network card.


Port Number

A number (integer) assigned to each program that is active on the network. A port number identifies a socket.


Protocol

The set of rules or conventions that govern information exchange between computers. Protocols can describe low-level details of machine-to-machine interfaces (e.g., the order in which bits and bytes are sent across a wire) or high-level exchanges between application programs (e.g., the way in which two programs transfer a file across the Internet).


Request For Comment (RFC)

A document that specifies standards and conventions for Internet protocols. Official Internet standards documents are maintained at the following URL  http://www.internic.net/ds/dspg0intdoc.html


Server

A computer that provides a service to other computers on a network.


Service

A service is a network accessible capability provided by a server computer. A service expects to receive commands conforming to a specific protocol from a client computer on a particular socket. A service returns responses to the client based on the commands received.


Simple Mail Transfer Protocol (SMTP)

The TCP/IP based protocol that allows computers (usually servers) to exchange email. In addition, client computers usually send email to servers via SMTP.


Socket

A socket is a logical port, identified by a port number. TCP/IP sends data packets between sockets on hosts. Usually a specific standard socket is assigned to be used by each Internet protocol such as SMTP, FTP, and HTTP.


Stream mode

One of three transmission modes supported by the FTP protocol. When data is passed in stream mode, it is passed as a raw stream of bytes.


Tags

Tags are HTML codes that are used to specify the formatting of documents on the World Wide Web (WWW).


Transport Control Protocol/Internet Protocol (TCP/IP)

The protocol that is the primary underlying protocol of the Internet. TCP/IP governs the format, routing, and reliable flow of packets between computers. Defined in http://www.internic.net/std/std7.txt.


Uniform Resource Locator (URL)

The URL is a standard for specifying links on the WWW. It identifies a resource (usually a file), its location and access method. URLs can be absolute or relative. An absolute URL is a complete address for the WWW object including the host name; while a relative URL is a partial address for the WWW object.


WinSock

WinSock is short for Windows Sockets. Windows Sockets is a standard API (set of functions) that allows Windows programs to work with TCP/IP.


World Wide Web (WWW or W3)

A hypertext-based distributed information system created by researchers at CERN Switzerland. This system uses the HTML and HTTP protocols to make hypertext documents available to clients.