PLB Web Server Tutorial
June 2015 

(c) Copyright Sunbelt Computer Systems, 2014-2015

Welcome to the Sunbelt PLB Web Server tutorial.  We suggest you print the document rather than switch between windows.  Once printed, you will be able to read each step and perform the task indicated with a clear uncrowded screen.

Please note that the 9.7 release or later of the PL/B Web Server software is required.
  
Our goal in this tutorial is to walk you through the process of setting up a PL/B web server, introduce you to the directory structure required, and explain the process of operating the server. 

The tutorial is intentionally simple. Upon completion, however, you will have a fully functional PL/B Web Server capable of accessing PL/B programs using a web browser. We do assume that the PL/B WebServer software has been installed properly.  Please review the installation sheet which accompanied the software if you are uncertain. 

---- Introduction to the PL/B WebServer ----

Once the PL/B Web Server has been installed, you should have a directory structure beneath the Sunbelt directory that contains all the required Sunbelt software.  In this directory you should find the "plbwebsrv.xx" directory where "xx" indicates the version of the software (i.e., "97").  The plbwebsrv.xx directory contains three directories, two of which are well known to most Sunbelt customers - "demo" and "code" and the other is "http_root".

The "code" directory contains the actual PL/B Web Server executable (plbwebsrv.exe), a threaded version of the server (plbwebsrvt.exe), the character debugger (plbdbug.plc), a default configuration file (plbwebsrv.ini), and two alternate configuration files (plbwebsrv.ini.local and plbwebsrv.ini.network) for reference.  A software release sheet, a terminal definitions file, and any supporting dynamic link libraries also exists in the directory. 

Beneath the "code" directory you will find the "logs" directory.  This directory is the default location of operational log files created by server. Options within the server configuration file control the logging and define the directory.  The default log file naming convention indicates both the date and time the server was started. The log files are in text format and can aid in diagnosing issues you may encounter.

The "demo" directory is the home of two subdirectories named "programs" and "SampleShortCuts".  Each directory has a specific purpose. 
 
The "programs" directory contains PL/B object code files (.plc) as generated by the PL/B compiler. As released, the configuration files' "PLB_PATH" (the path used by the web server to locate programs) points to this directory. In a later section of this tutorial we will modify the path to include a directory of your own choosing. As released, the "programs" directory contains some basic demonstration programs.  The "source" directory beneath "programs" contains the PL/B source files (.pls) of the demonstration programs.

The "SampleShortCuts" directory created by the installation process includes a number of text files that may be copied and pasted to your desktop.  These files illustrate useful desktop shortcuts for you PL/B Web Server applications.

The "http_root" directory serves as the "document root" of the web server.  That is, only files within this directory and below are exposed to clients of the server.  The files in this directory and below are HTML, JavaScript, and Cascading Style Sheet files as commonly found on web servers. While these files may be modified, it is best to start by using the files as they are distributed.

---- Starting the PL/B WebServer ----

With all the directories and files in place, let's start the web server.  During the installation process, your Windows start menu and a shortcut folder on the desktop were populated with entries that start and stop the server.  After clicking on "start" and selecting "All Programs", navigate to the "Sunbelt" entry and then "PLB Web Server x.x" where "x.x" is the software release number such as "9.7".  Within this menu item, you will find a set of entries to "start", "stop", and "force stop" the server.  These all reference a default .ini file.  The default .ini file applies to a web server running locally (i.e., on your PC and accessible only by your PC).  Plbwebsrv.ini.local is a backup copy of plbwebsrv.ini.  Plbwebsrv.ini.network is for a network server that will allow connection from other PCs.

The three functions perform actions as you would expect.  The "start" function brings up the web server allowing it to begin communicating with browsers.  The "stop" function requests that the server terminate execution when the last user exits.  The "force stop" function instructs the server terminate immediately regardless of the state of any connected users.
For this demonstration, we will use a local web server.  That is, the web server will be running on your PC.  In the TCP/IP world, the IP address of "127.0.0.1" is reserved and means the local computer.  Although your computer has another "real" IP address using the "127.0.0.1" is a generic way of indicating the local computer. When running as a local server, only browsers running on the local computer can connect to the server. 

To start the PLB Web Server, select "Start Web Server" from the start menu. You should see a window open and some messages displayed. If you would like to ensure that the server started correctly, you can use the task manager to view the running processes.  You could also examine the file found in the "logs" directory.  If for some reason the server fails to start, the log file should provide information to help correct the problem. 
 
Once the server is started, it runs in the background.  When the server is active, an icon is placed in the Windows system tray.  Right clicking on the icon will display a menu that allows a display of server statistics or termination of the server.

---- Connecting to the PL/B WebServer ----

Once the server has been successfully started, I'm sure you are ready to see it in action. Start your favorite browser and navigate to "127.0.0.1:8081".  By now you know the "127.0.0.1" means the local computer and the ":8081" is the port number used by the PLB Web Server. If you have a firewall configured, you may need to allow access to this port.  Once connected to the server, the demonstration "Answer" program is displayed.  Note that this program (answer.plc) is found in the "demo/programs" of the web server.  It is a PL/B compiled program just as any other PL/B GUI program. The source code is located in the "source" folder. The program contains PL/B instructions and includes a single web form named "answer.pwf".  A ".pwf" file is created with the Sunbelt Designer just as you would create a normal Windows ".plf" form file.

With the Answer program executing, click one of sample programs available with the top three radio buttons.  The "Address Program" demo shows a simple name and address demonstration program. Once you make the selection, click the "Chain" button and the program will execute. Just like the Answer program, the Address Program object and source files are provided in the "demo" area.  Exiting the demo program will return you to the Answer program.

After you have written your own PL/B Web Server program, you can execute it from this Answer program by entering the name in the space provided and clicking "Chain".  Should you wish to pass parameters to the program, a text box is provided as well.

To terminate execution of the Answer program, click the "Shutdown" button.  As released, terminating the Answer program will simply cause the Answer program to be executed once again. Users are able to configure this behavior as required.  For instance, if you wish to access the Sunbelt home page when the Shutdown button is clicked, edit the configuration file and change the "PLBWEB_MENU" directive to "http://www.sunbelt-plb.com".  This configuration change will take effect immediately.

If you wish to execute a program directly without going through the Answer program, add the file name to the browser location.  For example, to execute the Address Program directly, enter the url "127.0.0.1:8081/addrweb.plc". The server will then search the directory in which the server was started and then each of the directories in the configured PLB_PATH for the program.

---- Stopping the PL/B Web Server ----

Stopping the PL/B Web Server is as simple as starting it.  Select "Terminate Web Server" from the menu and the server will stop when no answer programs are running. Select "Force Stop Web Server" to halt the server immediately. Note that forcing the server to stop closes any open files and the child processes are terminated in an orderly manner to minimize any PLB application impacts.

---- Using a Network PL/B Web Server ----

To use a network web server, you will need to edit the configuration file.  Navigate to the "code" folder of the server software and open the "plbwebsrv.ini" file using a text editor.  Locate the line that starts with "PLBWEB_ADDRESS".  You may then change the value after the equal sign to be the IP address of the server or a registered domain name (i.e., www.sunbelt-plb.com). Upon starting a network web server, other workstations may connect using the IP address of the web server and port 8081.  A typical URL to connect to the server might be "192.168.1.56:8081".  

---- Changing the PLB Code Directory ----

While access to the demonstration software directory works well for testing purposes, most users will want to store their programs in another directory.  The process to do this is easy.  First, create a folder and copy the object code (.plc) files into it.  Next, edit the server configuration (i.e., "plbwebsrv.ini").  Change the value associated with the PLB_PATH directive to reference your new folder. Remember that by default an Answer.plc is expected if a program is not specified in the URL. 
   
---- Creating a PL/B Web Server Program ----

The process of creating a PL/B Web Server program is quite similar to creating a PL/B Windows program.  A source file (.pls) is created that will perform the bulk of the work. Within the program, forms will be used to provide the user interface. The primary difference between a Windows application and a Web Server application is the forms.  Web Server applications have their own set of objects, properties, and events and as such have their own form type. 
 
Let's create a very simple web program. We will have the program display the current time on a form and provide a button to exit the program. If you have not used the Sunbelt Designer in the past to create a form, you may want to first review the file named "tutorial.txt" released with the Designer.  It will walk you through the process of creating a form step by step.  A web form as required by our test program is created in the same way.

Start by creating a source file named "webtest.pls".  You can use any text editor or Sunbelt's IDE to accomplish this.  Add the following lines to the file:

MAIN	PLFORM	WEBTEST.PWF
.
	FORMLOAD	MAIN
.			
	LOOP
	EVENTWAIT
	REPEAT

Anyone who has done Sunbelt Visual PL/B programming before should be quite familiar with this code.  Basically, a web form is loaded (note the .pwf extension) and the program waits for a user action.  Save the source file and exit the editor.

Next, we need a simple form to display. The form is created using the Sunbelt Designer.  Start the Designer and select "New" from the file menu, followed by "Web Form".  Again, if you have designed Windows forms in the past, the Designer should look quite familiar.  You will note that the controls in the toolbox are a subset of those available when creating a Windows form although most common controls are supported.  Add a LabelText to the upper center area of the form and a button in the lower center. Clear the "Text" property of the LabelText and set the "Title" property of the Button to "Quit".  Double-click the form to open the Designer's code window and in the "Load_WebForm1" event procedure, enter the following lines:

TIME	DIM	8
	CLOCK TIME,TIME
	SETPROP LabelText1,Text=Time
			
This code simply retrieves the current time and stores it in the LabelText of the form when the form is first loaded.  Now, on the form, double-click the Button and in the event procedure 

"Click_Button1", enter
	STOP
	
This will terminate the program when the button is clicked.  Terminating a program will return the user to the answer program normally. Once the code has been entered, save the form as "webtest.pwf" in the same directory as your source file.

At this point we need to compile the program.  The program can be compiled from within the Sunbelt IDE or from the command line using the following syntax:

plbcmp webtest

All that is left to do is place the output of the compiler in a folder accessible to the web server.  The folders available are defined by the PLB_PATH directive in the server configuration file.  If the configuration file has not been modified, the following will work:

copy webtest.plc \sunbelt\plbwebsrv.xx\demo\programs

"xx" is the release version of your software (i.e., "97").  You can then execute the program by entering "webtest" in the "Program Name" field of the Answer program and clicking "Chain" or by using the following URL:

127.0.0.1:8081/webtest.plc

---- Debugging a Web Server Program ----

Just as using the Sunbelt PL/B web server is simple and straightforward, so is debugging a Web Server program. Let's debug the sample "webtest" program from the section above.
We start by compiling the program with a symbol file.  The IDE does this by default anytime a program is compiled.  If you are executing from the command line, compile with the "-s" option using:

plbcmp webtest -s

Copy both the "webtest.plc" and "webtest.sdb" files to the "demo\programs" directory. 

We next need to start the PLB GUI Debugger.  The easiest way to accomplish this is to open "Development Console" for your version of PL/B for Windows.  Click the Windows "Start" button and then select "All Programs".  Find "Sunbelt" and then your version of PL/B for Windows. Within that item will be a selection named "PLB Console Dev".  Clicking that item will open a Windows console with the path and other environmental items set as required. Now we can start the PLB GUI debugger in listening mode:

plbwin dbgiface -listen

A window will appear indicating the debugger is running and waiting for a program logon.  This window may be minimized if your wish.

Now, move to your browser and enter the following URL:

127.0.0.1:8081/webtest.plc?runopt=-dr

The "runopt=-dr" parameter instructs the runtime to execute the program in debug.  Once entered, a window will open and display the program source in the GUI debugger.  Exiting the debugger will return you to the command line.

---- End of Tutorial ----

Congratulations! This concludes the PLB Web Server tutorial.  If there are items you would like to see explained or additional functions added to the example, please let us know.  E-mail your comments and suggestions to:  support.scsi@sunbelt-PLB.com
