You will now see the source
code of a new WSO in the Studio. Take a look at the Workspace Explorer
window. If Workspace Explorer is not open, click on the Workspace
Explorer icon on the Studio's toolbar.
Now, let's create the Greeting Web Service function.
This section assumes that you are familiar with Web Services and Web
Service Definition Language (WSDL). We will only explain coding and methodology
that is specific to DataFlex.
If you are unfamiliar with WSDL, visit http://www.w3.org/TR/wsdl
to read the World Wide Web Consortium's (W3C) definition of it. There
are also many other places on the Web where you can learn more about Web
Services and WSDL.
Web Service Objects are the main building block of Web Service applications in DataFlex. These objects are components you can build in the Studio. They contain functions coded in the DataFlex language. These functions can be "published" so that their interface can be called as a web service using the SOAP protocol.
We are going to illustrate some basic DataFlex Web Service development techniques using a variation of the well-known "Hello, World" program, which is used as the first program to teach many programming languages.
The Greeting Web Service you will create will be very simple, with 1 public function, named Greeting. The Greeting function will accept a Name as an argument and returns a string containing "Hello, {Name}, how are you today?".
Click on the Create New button on the Studio’s toolbar. Click on the Web Object tab of the Create New... dialog. Double click the Web Service Object icon.
The "Create a New Web Object" dialog will open. Enter oGreeting as the object name. Notice that the filename automatically changes to Greeting.wo as you type the object name. Accept the default directory path (the AppSrc folder in the GreetingWebService workspace). Click on the Ok button.
It is very useful to give your objects meaningful names. The name oGreeting is reasonably meaningful to describe what this WSO does. In a more complex project, with dozens, or potentially hundreds of objects, having the ability to uniquely identify an object easily will save you time and effort.
We recommend using the prefix o for objects. You can read more about DataFlex Naming Conventions in the Language Guide.
You will now see the source
code of a new WSO in the Studio. Take a look at the Workspace Explorer
window. If Workspace Explorer is not open, click on the Workspace
Explorer icon on the Studio's toolbar.
The Workspace Explorer is a docking window that lists the current project and components included in the current project by type. Read more about this in the Workspace Explorer topic in the Studio book. By default, it is located on the right side of the Studio.
The Current Project is a key concept in the DataFlex Studio that affects almost everything you do in the Studio. The current project is the project that is compiled, run and debugged in the Studio, even if you are working on components that are not part of that project. When creating new components, they are added to the current project by default. When working in a web application, WebApp.src will always be the current project. Read more about this in the Workspace Explorer topic in the Studio book.
In Workspace Explorer,
you should see WebApp.src as the Current Project. Click on the + in the tree view to expand WebApp.src, then click on the + to expand Web
Service Objects. You can see that Greeting.wo has been added
to project WebApp.src.
If you click on the + to expand Web Modal Dialogs, Web Browser Objects
and Other Files, you will see all other files that are currently part
of the project.
If the Code Explorer window
is not open, click on the Code Explorer
toolbar button.
In the Code Explorer window,
you will see an outline of the current source file in a tree. There
are nodes that represent other source files that are used
in this file, objects, and methods.
Double-click on the oGreeting control in Code Explorer to display the code for this object. This will place the edit cursor at beginning of the object declaration line for oGreeting.
There are multiple ways of navigating between open views in the Studio. As you already saw, double-clicking on an object in Code Explorer opens the code editor to the code for that object.
Tip
You can scroll through all open views by using the Ctrl + Tab or Ctrl + Shift + Tab keyboard shortcuts.
Once you are working in a larger project and have multiple files open, it may become useful to leave the File Navigator window open as a docked window. If the File Navigator is not already open, you can open it by clicking on the File Navigator toolbar button.
Tip
If you double-click on any file in Workspace Explorer:
If the file is not already open, it will open.
If the file is already open, but it is not the currently active window, it will be come the active window.
If the file is already open and it is the currently active window, the view will toggle between the code editor and designer (if the file can be modeled in a designer)
Tip
If you have enough windows open in the main Studio pane to exceed the space for tabs on a single row, the tabs will begin scrolling and you can use the arrow keys to scroll right and left to see more tabs.
As an alternative, you can configure the Studio from Tools > Configure Studio... to display multiple rows of tabs.
For more information about navigating around the Studio, see the Studio help book.
You
are going to write the Greeting function which accepts a name as parameter
and returns as result a string of "Hello, " and the name.
Type the following lines of code inside the already declared Object oGreeting, just above the
"End_Object" line.
If you are new to the Studio, I suggest typing these lines of code,
rather than copying and pasting them in. This will show you the power
of the Studio's CodeSense
features, which aid you in writing code by popping up suggestions
as tooltip, complete words (such as existing function names) for you,
add ending statements to code blocks, etc. If you just copy in the
code, you will miss many of these features.
The first line of code is:
Function Greeting String sName Returns String
This line of code declares a function named Greeting. It specifies that the function accepts one string variable named sName and that the function will return a string variable when the function completes.
This line also creates a local variable named sName, since it is declared as a function parameter.
The next line of code is:
String sReply sHello sHowAreYou
This line of code declares 3 local string variables with name sReply sHello and sHowAreYou.
The scope of a local variable is limited to the method (procedure or function) in which it is declared. You can "use" these variables, meaning that you can assign values to them and access their existing values only while in the current method, in this case Function Greeting. Attempting to reference variables outside of the scope in which they are declared will result in a compiler error.
Just as with object names, it is useful to give your variables meaningful names. The names x and y are not nearly as meaningful as sReply, sHello and sHowAreYou. In a more complex method, with dozens of variables, having the ability to easily identify the meaning of a variable name will make you a more efficient programmer.
We recommend using the prefix s for string variables. Prefixes like this also help in identifying the meaning of variable names. If you stick with this naming convention, you will never confuse a variable that holds a string with one that holds a number. You can read more about DataFlex Naming Conventions in the Language Guide.
As you start typing code, you will sometimes notice a list pop up that presents you with possible options. In most cases, this semi-automatic list feature of CodeSense will know the right time to appear and present you with appropriate contextual choices. If you want to manually invoke this list, press Ctrl+Space on just about any line or word you are typing.
CodeSense is a set of Studio features that intelligently assist you in writing code, providing lists of context sensitive options and information. Using CodeSense dramatically increases productivity, it gives you context sensitive information directly when you need it as you're typing code in the editor, so you don't have to leave the editor to look up references in the documentation. And it can even be used to complete your typing for you, minimizing typos etc.
You can learn more about using CodeSense here.
The next line of code is:
Move "Hello, " to sHello
This line of code initializes the string variable sHello to "Hello, ".
The syntax for setting the value of a variable is:
Move {Value} to {VariableName}
Local variables that are not initialized are automatically initialized to "" for strings or 0 (zero) for numeric variables (integer, real, etc.). However, it is a good habit to always initialize all variables you intend to use, even if you initialize them to "" or 0.
The next line of code is:
Move ", how are you today?" to sHowAreYou
This line of code initializes the string variable sHowAreYou to ", how are you today?".
The next line of code is:
Move (sHello + sName + sHowAreYou) to sReply
This line of code concatenates the contents of the string variables sHello, sName and sHowAreYou, and moves that value to the string variable sReply. So, if for example, sName contains "John", this would move "Hello, John, how are you today?" to sReply.
The next line of code is:
Function_Return sReply
This line of code returns the contents of the variable sReply to the calling routine.
The next line of code is:
End_Function
This line of code declares the end of the Greeting function.
The
completed code should look like this:
You may want to consider adding some blank lines to your code, to separate
the code into meaningful blocks, as demonstrated above. This can make
code easier to read, particularly when code you write becomes more
complex than this small sample.
Next,
the function needs to be published so that it can be invoked from
a Web page.
In Code Explorer, click on the +
in the tree view to expand the oGreeting
object. This will expand the oGreeting WBO object to show its child
objects and methods.
Right-click
on the Greeting function in
Code Explorer and select Published from the context menu.
The Greeting function is now published. Notice that its icon has changed.
Notice also that the Studio has inserted the following meta-data tags
above the function declaration line in your source code:
{ Published = True }
{ Description = "" }
Publishing web application functions is a security measure of DataFlex web applications. Only published functions can be invoked externally, so you are in complete control over how the calling web interface can interact with your application.
Edit the Description meta-data tag to describe what the purpose of the function is. Type
This function accepts a name and returns it in the form 'Hello, Name, how are you today?'
inside the quotes of the Description meta-data
tag, as seen below.
If the Properties window
is not open, click on the Properties
toolbar button to open it.
The Properties window is used to view and edit property values for the selected object, class or table in the Studio's designers, such as Code Explorer.
Select the oGreeting object in Code Explorer. In the Properties window, change the psServiceName from tempService to GreetingService.
The Service Name uniquely identifies the service within your application and is used by clients to access the service. In this case, the name of the service is GreetingService and the virtual directory in which the service will run is http://localhost/greetingwebservice. The service will be accessed with the URL http://localhost/greetingwebservice/greetingservice.wso. The name of this .wso file is important. Each WSO within a single web application should have a unique psServiceName.
Change
the value of the psServiceTitle
property from DataFlex Web Service
to Greeting Web Service.
The resulting properties should look like this:
Notice that all the property values that
have been modified from their default values (as initialized in the object's
class) are shown in bold. These are also the only properties
that are written out to the code of the current source file.
To reset a property value to its default value, right click on the property
name column in the Properties
window and select Reset Value.
You can see the documentation for any property by clicking on the property in the Properties window and pressing F1. This will take you directly to the DataFlex help entry for the selected property.
The Studio will display different controls
for each property based on the property type. For example, click in the
value column (the right column) for the pbDocumentStyle
property. Notice the combo form that allows you to select a value from
a predefined enumeration list (in this case, True or False for this Boolean
property).
A web service must define a TargetNamespace URI. This is supposed to be a unique identifier that keeps all parts of your web-service unique. The psServiceURI does not have to point to an actual web-address, it is just supposed to be a unique name. The default setting for this is http://tempuri.org/. This name will work fine for testing but it is strongly suggested that you change this before you actually publish a web-service.
Create a description for the entire web service to be published as part of the service’s description. Double-click on the oGreeting object in Code Explorer to display the code for this object. Find the following source code:
//------------------------------------------------------------------------------------
// psDocumentation provides high level documentation of your web service. Clients using
// this service will see and use this documentation.
//------------------------------------------------------------------------------------
Set psDocumentation to ;
("DataFlex Web Service .... " + ;
" ... " + ;
"documentation")
Replace the psDocumentation string with meaningful information. Notice that this source is broken up into multiple lines to demonstrate how to create long, yet readable description within the edit area.
Set psDocumentation to ;
("Greeting Web Service is used by the DataFlex Tutorials " + ;
"to demonstrate a simple Web Service.")
When you select the oGreeting object in Code Explorer again, you will see that the value of the psDocumentation property in the Properties window has been updated to reflect the source code change you just made.
Tip:
While in the code editor, you can press Ctrl+F7 to locate the object you are currently editing in Code Explorer. This will automatically select the object and bring up its properties in the Properties window (if this window is open).
Compiling and Testing Your First Web Service