|
CASL HTTP Tutorial
Tutorial Description
In this tutorial we will demonstrate how CASL can be used
to create advanced networking applications to send and
receive data across a network. The protocol
demonstrated in this example is HTTP. In addition, a
complete sample application is provided that will allow you
to quickly and easily integrate this functionality directly
into your own CASL applications. Use of this tutorial
would be helpful for many uses including:
- Adding update notification to your applications.
The sample includes a functional demonstration of this.
- Using HTTP POST to send data to a web server.
Such servers can be used for data collection, MRP/ERP/MES
Integration, corporate applications, etc. The
receiving server can be running BEA Weblogic, IIS, etc.
Messages to these servers can be formatted XML messages
over HTTP or any other form of request.
- The sample also includes a simple HTTP GET / Browser
implementation that can be used to extract the contents
of a URL and return the HTML source to a string.
Prerequisites
- You will first need to have the latest version of
CASL (i.e. CASL 4.3) installed. If you are unsure
of how to do this, please see the
Download page.
- Some understanding of networks, IP Addresses will be useful.
- Download the
HTTP Test Sample application and unzip it to a
folder on your system. You may want to open the
HTTP Test sample in the CASLide while you follow along
with this tutorial.
- If you are new to CASL, you may want to start by
reviewing the Introduction
to CASL guide (also included in the CASL Download).
CASL and HTTP
CASL can be used to develop applications that run on the
PalmOS, PocketPC/Windows Mobile 5 and Windows. Each
platform supports the ability to send information across a
network using the standard TCP/IP Protocol. TCP/IP is
the basic protocol used by the Internet and Intranets.
Sitting on top of TCP/IP are specialized protocols, such as
HTTP or Hypertext Transfer Protocol. HTTP is commonly
used for sending/receiving data to/from web servers.
The web servers can exist publicly on the Internet or
privately on an Intranet. In this tutorial, we will
use the included HTTP Test sample application to show just
how easy it is to use CASL to communicate with the outside
world -the Internet.
Recommendation -You
may want to download the
HTTP Test Sample
application
and unzip it to a folder on your system and open
the sample in the CASLide while you follow along
with this tutorial. .
Throughout this tutorial, functions will be referenced that
exist in this sample.
This tutorial also demonstrates how to integrate
key libraries from the HTTP Test Sample directly
into a new or existing CASL project. If
you would like to view both the HTTP Test sample
and create a new project demonstrated below,
ensure the menu option Tools/IDE Settings
has Allow Multiple CASLide's to run
checked. |
Using HTTP GET
An HTTP GET request is most commonly used to request the
contents of a URL or web address. The GET request is
typically limited to ~2k in size, plenty large to request
data from a URL. In it's basic form, a typical HTTP GET
Request will look something like:
In this section, we will demonstrate how to use code from
the HTTP Test application within your own CASL application.
You may want to start by creating a new CASL project (menu
option File/New Project) and provide a name for your
project. If you have an existing project you want to
integrate HTTP code into, you can load that project and
continue below.
To allow sending an HTTP GET Request to a web server,
your CASL application will need to include the following
Libraries from the CASL
HTTP Test Sample:
Library |
Description |
CASLMath.cpk |
This very useful library
provides many math functions that were
previously only available in MathLib on the
PalmOS. By including this Library within
your CASL application, you will have access to
many useful math functions on all supported CASL
platforms. For this tutorial, we are only
using the function "cslPOW" for the URLEncoder
function in the "LibNetCOMM.cpk".
The functions in this
library were kindly donated by Mr. Jeff Summers
of
Small Systems Software. |
CASLVB_Funct.cpk |
There many functions
available in this library that you may want to
use in your applications. If you are
familiar with Visual Basic, or if even you
aren't, you'll find most of these functions
useful in CASL applications you create.
For this tutorial, we are only using the
function "Hex" for the URLEncoder function in
the "LibNetCOMM.cpk".
The functions in this library
were kindly donated by Mr. John Vaccaro of
Southeastern Data Technologies. |
LibNetCOMM.cpk |
This is the main library used
by this tutorial to demonstrate how to make HTTP
GET / POST Requests to a web server. The
primary function that you will make use of is
the "SendData" function which makes sending
these requests very easy. It handles the
ability to URLEncode the request (commented by
default), Connect to the remote server, format
the HTTP GET/POST Request, Send the Data, wait
for a response (or timeout) and disconnect from
the remote host. The
functions in this library are donated to the
entire CASL community by your CASL Team. |
You will want to copy the above .cpk files to
your application's main folder. Next, you will
need to declare the libraries within the main CASL
file (.csl). In CASL, this is done by using
the include keyword. The code below can
be copied and pasted directly into to top section of
your applications main .csl file (don't forget to
copy the actual .cpk files from the sample to your
application folder so CASL can find them):
##########################################
## Application Name: <your app name here>
##
## Purpose: <app. purpose here>
##########################################
include "CASLMath.cpk";
# Include Jeff Summers
CASLMath Functions
include "CASLVB_Funct.cpk";
# Include John Vaccaro's
CASL>VB Functions
include "LibNetCOMM.cpk";
# Network Communication
Library
#
Add any of your own packages here: |
Now that the needed functions have been added to your
project, take the menu option Project/Update Includes.
This will force the CASLide to load the .cpk's into the CASL
project object tree. If you double-click under
Includes in the object tree, you'll see all three .cpk's
listed there.
There are just a few minor changes we need to make to our
library to remove some customizations that were added for
the HTTP Test tutorial. The changes that need to occur
are:
- Uncomment the line at the top of the
LibNetCOMM.cpk that states "numeric moveWorld=false;
# Animate World". That is, remove the leading "#"
from the line.
- Search for the function called "socket" and comment
line 224 that reads "animateWorld;" (this is used to
rotate the world image in the HTTPTest app. which we
don't need to do in your application). Also,
comment line 228 that reads "lblByteCount.display="("+
string(nByteCount,"0")+" bytes)";" (this code was used
to show the number of bytes received during the HTTP
receive).
That's it. Your application is now ready to
send/receive data using HTTP, at least from a main
functionality standpoint. We haven't placed any
controls on the form to allow the user to interact with the
code. Let's continue by assuming all we want to do is
click a single button and display the web page contents in a
text object. The request will be an HTTP GET Request
and we'll hard-code the URL (or web address) we want to use.
Let's first double click the form under the Forms
item in the project object list, this will make the form
visible within the CASLide. Now click the button
object from the toolbar to draw a button on the form (if
it's not already visible, click the menu option View /
Form Layout Toolbar). Double-click the button and
select the Common Properties tab and enter "cmdHTTPRequest"
for the Name of the button. Under the Button
Properties tab, enter "HTTP Request" for the button
caption.
One more object we need to create is a text object to
display the response after we click the "HTTP Request"
button. From the toolbar on the CASLide, now click the
Test Field object and draw a text box on the form (if it's
not already visible, click the menu option View / Form
Layout Toolbar). Double-click the text object and select
the Common Properties tab and enter "txtResponse" for
the Name of the Text Field. Select the Text
Properties tab and click the drop down to the right of
Scrollbar and select "Top" (this will add a scrollbar
to our text object).
Next, let's add the code below into your main .csl file
(just under the include declarations). Notice the
function name is the same as the button you recently
created. When you click the button, the code within
this function will then be executed.
function
cmdHTTPRequest;
# HTTP GET (Used
by most web pages)
txtResponse.display=SendData("http://www.caslsoft.com",
false, "");
end; |
Before we go further, let's explain the SendData
function in a little more detail. This
function handles allot of work for you, including
parsing the URL, determining the host to connect to,
formatting the GET or POST Request, sending the
request, checking for timeouts and returning the
response. This code in this function is all
pure CASL code and will work on all CASL platforms (CASLWin,
CASLpro for the PalmOS and CASL PocketPC/Windows
Mobile). Please consider the following
definition for the SendData function:
SendData(String
URL, Numeric asPost,
String inMsg) as string
Parameter |
Description |
URL |
A string which
contains the URL you want to receive (GET) or
send (POST) to. This will commonly be a
request such as "http://www.yourwebsite.com".
The function will handle parsing the URL for
you. |
asPost |
true/false value
that indicates if the request should be sent as
an HTTP GET (false) or POST (true). |
inMsg |
This value
contains the message you want to send for the
HTTP POST Request. This may be a formatted
XML message or any other type of data the server
is setup to handle. When performing an
HTTP GET Request, this parameter is ignored. |
Now our program is ready to run! To perform the
HTTP GET request from the website "http://www.caslsoft.com",
you can start the program in CASLWin by pressing CTL+F5
(make sure "Windows Release" is set on the toolbar).
Or, you can compile this application for the Palm or
PocketPC (for additional information on how to do this,
please see the Introduction to
CASL Tutorial). After you tap the "HTTP Request"
button, you'll then see the following.
Using HTTP Post
In the previous section we sent an HTTP GET request to
receive (or get) data from an existing webpage, but what if
you want to send data instead? To send data to a
remote web server, you'll want to perform an HTTP POST
Request. The data you send to the remote server will
make use of the last two parameters of the SendData
function. The asPost (2nd parameter) should be set for
true to indicate the request should be sent as a POST.
The last parameter, inMsg is the message you want to POST
(or send) to the remote server. What appears within
the inMsg string really depends upon the receiving system.
In some cases, it may be a formatted XML Message or a simple
string of characters. You will want to determine how
the inMsg request should be formatted before using it.
It can easily be used to send an HTTP POST request to a
Weblogic Java Server Page (.jsp) or most any other web
server.
SendData(String
URL, Numeric asPost,
String inMsg) as string
Parameter |
Description |
URL |
A string which
contains the URL you want to receive (GET) or
send (POST) to. This will commonly be a
request such as "http://www.yourwebsite.com".
The function will handle parsing the URL for
you. |
asPost |
true/false value
that indicates if the request should be sent as
an HTTP GET (false) or POST (true). |
inMsg |
This value
contains the message you want to send for the
HTTP POST Request. This may be a formatted
XML message or any other type of data the server
is setup to handle. When performing an
HTTP GET Request, this parameter is ignored. |
In the HTTP Test application, there is a very
simple example of an HTTP POST request to a .cgi
file. To view this code, load the HTTP Test
sample in the CASLide, double-click the frmMain
form, double-click the "HTTP Post" button, and tap
the "..." button beside the Invokes box. This
will jump to the section in the project which is
highly commented and provides more details regarding
the SendData function with an HTTP POST Request.
More about the HTTP Test Sample
The HTTP Test sample demonstrates the HTTP GET / POST
functions as described in the previous sections. In
addition, the sample goes a step further by showing you how
to implement an "Update Check" within your application.
The update check uses an HTTP GET request to return a text
file located on a remote server. The contents of the
text file indicates the current version of the application,
a description, etc. There are also string functions
provided in the sample to allow you to easily parse an XML
Response message (See the GetMessageValue function).
Another feature of the HTTP Test sample is that it
provides a very simple HTML Browser. Simply enter the
URL you want to browse and tap the GO! button.
The SendData function will then be executed which will
create the HTTP GET request to retrieve the web page
contents for you. The results of the HTTP Get will
then appear within the text object on the form. Just
for fun, the HTTP Test sample also includes an animated
rotating earth to indicate data was received, along with the
number of bytes received and a Browse History database.
Conclusion
It's easy to implement HTTP GET/POST Requests with CASL
using the code found in this tutorial. The simple
SendData function can become your key to unlocking greater
potential in new integrated applications using CASL.
Your applications need not be restricted to saving data
locally on the PDA, go wireless with HTTP!
If you have any questions or would like to discuss the
CASL HTTP tutorial with others, please visit the
CASL
HTTP Tutorial Thread.
Home | News | Community | Products | Download | Support | Sales | About CASL
|
|