WebSmart logoWebSmartNew Installation Instructions

These instructions are for new installations of WebSmart ILE, WebSmart PHP (on the IBM i) and Clover [upgrader's click here]. Some installation steps are only necessary for certain versions or features - check the comments at the top of each step as you go. If you plan to evaluate WebSmart PHP, we recommend you start by installing Zend Server CE. Finally, if you don't have an IBM i, use these instructions to install WebSmart PHP on your PC.

Step 1. Install Zend Server CE (Community Edition).

This step is required for WebSmart PHP only. If you have no plans to use WebSmart PHP you can skip to the next step. However, if you think you might at some time try out WebSmart PHP, install Zend Server first so the WebSmart install can automatically detect it and adjust the WEBSMART HTTP server instance accordingly. If you install Zend Server afterward you must make these adjustments manually.

Verify Whether Zend Core or Zend Server CE are Installed

Zend Core has been superceded by Zend Server CE (see Zend's site for details), so if you don't already have Zend Core or Zend Server CE installed, you should install the free Zend Server CE (Community Edition).

Follow these steps to determine if you have Zend Core or Server installed:

  • At an IBM i session, run the command 'go licpgm'
  • At the menu presented, select option 10.
  • In the list of licensed programs, check that either the licensed program 1ZCORE5 (Zend Core) or 2ZSVRPI (Zend Server) are listed with a status of *INSTALLED.

If you don't already have Zend Core or Zend Server CE on your system, you can download and install Zend Server CE from Zend's website. At this page, download either of these (The Zend Server CE for IBM i installation package is the same as that for Zend Server) :

  • Zend Server for IBM i (PHP 5.3)
  • Zend Server for IBM i (PHP 5.3) Windows Installer

To install, please reference the Zend Server for IBM i Installation Guide, where the first section includes the system requirements. You can find additional information in the Zend Server CE online documentation.

After installing Zend Server CE you can continue with the next step.

 
Troubleshooting & Info   

See KB#8786 for the difference between Zend Server and Zend Server CE.

Visit Zend's website for more information about Zend Server CE.

If you have installed any release of WebSmart before installing Zend Core or Server you can change your Apache HTTP server instance configuration afterward. The configuration files for both Core and Server are installed to the /www/websmart/conf/ directory; they are called httpd.conf.zcore and httpd.conf.zsvr, respectively. Contact Technical Support for details.

Step 2. Download WebSmart and Transfer the IBM i Install Files.

This step is required for all installs on the IBM i. Follow the instructions below to transfer the server components to your IBM i.

Download WebSmart 9.0.

1. Go to the Download Free Software Opens new window page and fill out the form to download WebSmart.

2. Download and save both the IBM i and PC installation files to a new folder on your PC.

3. When the download finishes, double-click the IBM i install executable file WebSmart9.0.exe (the exact version number may vary) to unpack the files and transfer them to your IBM i.

4. After the file is decompressed, BCD's FTP upload utility is presented. Enter your IBM i IP address (or domain name) and the QSECOFR password (as shown below). Then click the Upload button:


When the Activity Log reports that the file upload is complete, you can close this window.

 
Troubleshooting   

If the transfer is interrupted, you can restart it by executing webinst.exe (in the folder to which you downloaded the software).

If the upload seems to be taking a long time you can check for activity on the IBM i. The transfer job will typically be a job named QTFTPxxxxx in subsystem QSYSWRK, displaying a CMD-CRTSAVF function. If you get an FTP transfer error please visit our Knowledge base and search for the error you encountered. You may need to adjust the FTP settings on your IBM i.

If the transfer fails, check the Activity Log window for errors. BCD's Knowledge Base Opens new window includes a number of useful troubleshooting options.

You can also run the command WRKSPLF QTCP and check the last joblog there.

You can also search our Knowledge Base Opens new window on this topic.

Step 3. Install the WebSmart IBM i Components.

This step is required for all installs on the IBM i.

1. Log on to an IBM i session as QSECOFR and execute the command BCDINSTALL/BCDINSTALL.

2. At the initial panel review the instructions and press Enter to continue.

3. The install will prompt you to specify a library to install to. The default library for the WebSmart development environment is XL_WEBLIB. Use this library for your first installation.

4. The IBM i libraries installed are XL_WEBLIB, XL_WEBSPT, XL_WEBDEMO, XL_EX51 and BCDSUPPT.

5. When prompted, enter your WebSmart License Key. If you don't have a valid WebSmart license key, contact BCD at (630) 986-0800 to request one. You can also press F3 to Exit (and complete) the installation process, and add the license key afterwards using the command XL_WEBLIB/UNLOCK.

6. When the IBM i install concludes, prompt the command XL_EX51/ZCFGTCP [F4] and ensure that the IP address shown at this screen is the correct local IP address for your IBM i. After you verify the settings press Enter to run the command.

7. If you made a change to any of the values displayed when you initially prompted the ZCFGTCP command, you need to restart the EXODUS51 subsystem (if it is running). Run the command ENDSBS SBS(EXODUS51) OPTION(*IMMED). Ignore any messages. Then run the command STRSBS XL_EX51/EXODUS to start the EXODUS51 subsystem. After a few moments run WRKACTJOB to verify that the EXODUS51 subsystem is active and contains a job called EXSERV51.

If the subsystem is started, continue with the next step.

Important Note about the WEBSMART HTTP Server Instance
As part of your WebSmart IBM i install we create, configure and start an Apache HTTP server instance named WEBSMART, running on port 8150. This allows you to start running your programs as soon as you install the software.

You can use the WEBSMART HTTP server instance however you want, but we recommend that once you start creating production applications you create your own server instances and use those. In our own internal development projects we have caused the HTTP server instances to go down due to malformed SQL and other programmatic issues, so we recommend that you create at least two separate server instances, for your development and production environments.

If you need assistance with creating your own server instances, please call Technical Support and we can help you out.

 
Troubleshooting   

After you select the library to install to BCDINSTALL attempts to restore the product library. It's very rare to have a problem with this step, but any that do come are usually due to changes to the RSTLIB command defaults.

If you mis-enter your license key, you can enter it later using the command XL_WEBLIB/UNLOCK.

If you IPL your IBM i nightly or on the weekends, you need to also restart TCP/IP services and the EXODUS subsystem. While you probably already have processes in place to restart TCP/IP, you can add the command STRSBS XL_EXODUS/EXODUS as part of that process (or just run it manually while you are still evaluating the software).

You can also search our Knowledge Base Opens new window on this topic.

Step 4. Testing the Server Side Installation.

This step is recommended for all installs.

As part of your WebSmart IBM i install we create, configure and start an Apache HTTP server instance named WEBSMART, running on port 8150. This allows you to start running your programs as soon as you install the software.

The installation also includes test programs you can run. Try these by entering your IBM i IP address below and clicking the ILE and/or PHP test buttons:

. . .

These tests build a URL that combines the IP address you entered, the WEBSMART HTTP Server's port number (8150) and the WebSmart library or IFS directory where the programs reside. If the test program(s) run it means that you have successfully installed the IBM i side of WebSmart ILE and/or PHP, and have started a functioning HTTP server instance.

Now you're ready to install the WebSmart IDE on your PC.

Background Information: The HTTP Server Admin Interface
As you start creating web applications you'll want to familiarize yourself with the IBM Web Administration for i interface.

To work with it go to the browser window where you ran the testcfg.pgm program and change the url to http://xxx.xxx.xxx.xxx:2001/HTTPAdmin, (where the x's represent the IP address of your IBM i).

When prompted, log in using your IBM i user profile. At the page presented you can go the Manage HTTP Servers section and select the WEBSMART server instance from the drop down list:

From here you can see the status of this server instance, and start, stop or restart it. If it's currently stopped you can click the green button to start it.

Note that from here you can also change the port number that the WEBSMART HTTP server instance is running on and other configuration changes.

  
Troubleshooting   

To confirm that this server instance was successfully started run the WRKACTJOB command and look for the subsystem QHTTPSVR. This subsystem should contain several jobs named WEBSMART. If this server instance is not visible you can start it using the command STRTCPSVR SERVER(*HTTP) HTTPSVR(WEBSMART).

If the programs don't run, verify the URLs generated in your browser window when you ran the test. The URL should look something like: http://xxx.xxx.xxx.xxx:8150/webapps/testcfg.pgm.

If you can't spot the problem, complete the PC install and then contact Technical Support.

You can also search our Knowledge Base Opens new window on this topic.

Step 5. Install the WebSmart IDE on your PC.

This step is required for all installs.

You can install the WebSmart IDE (the PC design tool) on any number of PCs that connect to the same server. Follow the steps below to install the WebSmart IDE:

  1. If you haven’t yet done so, go to the Download Free Software Opens new window page and fill out the form to download WebSmart.
  2. When the download finishes double-click the downloaded file to unpack the install files and initiate the install. The PC install file is named websmart90-pc.exe [this may vary slightly].
  3. Follow the instructions to install the WebSmart executables to your PC.

You should be able to accept all the default install options. When it’s done, the install will prompt you to launch the software. You can also launch WebSmart from your Start menu.

Then continue with the next step.

  
Troubleshooting   
Installation

Default Directories
The default installation location for WebSmart is C:\Program Files\ESDI\, but on Windows Vista and Windows 7 the software is installed to C:\ESDI\. Keep this in mind if you are looking for one of the installed components (e.g. templates or tutorial solutions).

Search our Knowledge Base Opens new window for installation issues.

Step 6. Configure Communications to the IBM i.

This step is required for installations on the IBM i.

The WebSmart IDE needs to be configured to connect to the IBM i so it can retrieve file layouts and perform other functions related to your IBM i database. [If you aren't using an IBM i as your server, please see the instructions for installing WebSmart PHP without an IBM i.]

1. If you haven't done so already, launch WebSmart from Start/All Programs/WebSmart/WebSmart.

2. If this is a new install WebSmart will detect that you haven't configured your server connection and ask you to do that. This prompt is presented (shown here with example values):


3. Enter your system name and IP (or DNS). The default port number is 4015. You may need to confirm this in your EXODUS51 configuration (as noted at the end of the Step 3 tab).

From the window above you can also set default values for a few options that you need to specify every time you create a new WebSmart ILE program. These include your RPG source file and object libraries. The program object library XL_WEBAPPS will work in conjunction with the standard WEBSMART HTTP server instance configuration.

Note: If this is a new install and you choose to use a different library, you will also need to adjust the default configuration for the WEBSMART HTTP server instance or create your own HTTP server instance to use instead.

4. For the default web path to object, type http://your_ip_address:8150/webapps/ where ‘your_ip_address’ is the IP address of your IBM i (make sure you don’t forget the port number and final slash shown above). This assumes that you are using the default configuration and the WEBSMART HTTP server instance.

5. To confirm your configuration click the Test Connection button. When you do this WebSmart prompts you to sign on to your IBM i and then displays a confirmation message.

6. Click OK to add the configuration entry.

Now continue with the next step.

  
Troubleshooting   
Communications Configuration

Your IBM i IP address and connection port number need to match the values set on the IBM i. If you aren't sure what to type, sign on to an IBM i session and run the command XL_EX51/ZCFGTCP to check the settings.

The most common connection error (10061) is caused by the EXODUS51 subsystem not being active. To address this run the WRKACTJOB command and check whether the EXODUS51 subsystem is running and contains a job called EXSERV51. If not, run the command STRSBS XL_EX51/EXODUS. If the subsystem is running but EXSERV51 is not, end and restart the subsystem and confirm the job is added. Then try connecting again.

If the subsystem is up but you still can't connect, add XL_EX51 to the library list of your IBM i session and run the command ZDSPERRLOG to display a list of your connection attempts. Check for error messages (such as invalid User IDs, etc.).

You can also search our Knowledge Base Opens new window on this topic.

Step 7. Create an FTP Connection (PHP only).

This step is only required for PHP. If you do not plan to create PHP applications skip to the next step.

WebSmart PHP requires at least one FTP connection. Your FTP connections allow you retrieve and work with files related to your application as well as set defaults for the PHP programs you create.

1. In the WebSmart IDE open the Tools/Options window and click the FTP entry to present these options:


Click the Add button to create an FTP Site:


Configure your options as described here:

Site NameType an informational description of the site you are connecting to.
FTP AddressEnter the IP address or domain name of your server.
Initial DirectoryEnter the initial directory to be displayed. For WebSmart, use this value: ‘/www/websmart/htdocs/wsphp/’ (with no quotes).
Web PathSelect a default path to pre-pend to your program name when you click the Launch button from within the IDE. The default WebSmart Apache HTTP server instance runs on port 8150, so this should normally be set to ‘http://your_IBMi_IP:8150/wsphp/’ (no quotes).
User/PSWDThe IBM i profile to use to connect to the IBM i when saving the PHP files.
FTP PortEnter the user profile and password to use to connect to the IBM i when saving the PHP files.
Passive ModeCheck this option if you need to establish your FTP connection in passive mode.

After entering the required values, click the Test Connection button to verify that you have entered your configuration details correctly. If the confirmation window tells you that the connection is working, press OK to create the site and continue with the next section.

  
Troubleshooting   

If you don't get a successful connection, double-check your values. If you have established links to the server in another application, compare your settings to those.

You can also create and modify your FTP connections from the window pane at the lower left of the main IDE. Just right-click in the area below the FTP Sites tab to present the available options.

You can also search our Knowledge Base Opens new window on this topic.

Step 8. Create an ODBC Connection.

This step is only required for WebSmart ILE or PHP programs running over databases other than DB2. If you will not create programs over non-DB2 tables, skip to the next step.

If you intend to use WebSmart to create programs over other databases (such as MySQL in PHP, and MySQL, MsSQL or Oracle in ILE) you need to create an ODBC connection to your target database so the WebSmart IDE can load the file layouts.

1. To create a new ODBC connection, launch the WebSmart IDE and go to the Tools/Options menu. Select the Servers/Databases section and click Add to present these options:


Click the Add button to create an ODBC Connection:


Configure your options as described here:

Name/DescriptionType a name and description for this ODBC connection.
Database TypeSelect whether you are using a database type of MySQL, SQLServer or Oracle.
Server/PortType a server IP and port number.
DatabaseEnter the database name.
User/PSWDType the User ID and password to be used to connect to this server.
DriverSelect the driver.

After entering the required values, click the Test Connection button to verify that you have entered your configuration details correctly. If the confirmation window tells you that the connection is working, press OK to create the connection and continue with the next section.

  
Troubleshooting   
Step 9. Set a Default User Profile for WebSmart PHP Programs.

This step is only required for WebSmart PHP, where you will be running PHP programs on your IBM i and/or MySQL server. If you will not use WebSmart PHP, skip to the next step.

After installing WebSmart PHP you need to set a number of connection defaults so your programs can access your IBM i and database. While there are a few ways to handle this requirement, the WebSmart PHP program templates are set up to retrieve the connection values from a file on your IFS. When you execute WebSmart PHP programs, the first thing they attempt to do is load a preferences file, xl_functions001.php, by executing this statement at the top of the code:

require('/esdi/websmart/v9.0/include/xl_functions001.php');

This file includes a section where you can specify default user profiles and system names (among other things). However, because this file is overwritten when you upgrade, it in turn attempts to load some of the defaults from another file, xl_user_preferences.php, which you need to create. (see our online WebSmart PHP KB article 6998 for additional details).

Create xl_user_preferences.php
1. In your IBM i IFS open the file /esdi/websmart/v8.9/include/xl_functions001.php (the release level may vary).

2. Save the file as xl_user_preferences.php (or copy and rename xl_functions.php).

3. In the new, copied file delete everything from (and including) this line up to the end of the file:

@include('xl_user_preferences.php');

Note: Leave the ?> at the end of the file!

4. In the section that remains in xl_user_preferences.php enter default values for the connections you will be using, as described here:

$pf_i5UserID and $pf_i5PasswordIBM i user profile and password to use for all i5 connections. If this value is left blank, Zend Core will use the special profile ‘NOBODY’. Note that these values are only necessary if your applications will use the i5-specific PHP functions.
$pf_i5IPAddressUnless you are by default connecting from your IBM i to another one, use the loopback value 127.0.0.1 here.
$pf_db2SystemNameEnter your IBM i system name for all database file access.
$pf_db2UserID and $pf_db2PasswordIBM i user profile and password to use by default for all DB2 access.
$pf_mysqlUrlDefault MySQL server to connect to.
$pf_mysqlUserId and $pf_mysqlPasswordDefault MySQL server user profile and password.
$pf_mysqlDataBase Default MySQL database.

When you create your own application you may want to load your User IDs another way (for example, by prompting the user to enter one), but this approach will get you started.

  
Troubleshooting   
Step 10. Set up the PHP Debugger.

This step is only required if you intend to develop PHP programs and want to use WebSmart’s PHP debugger. Follow these steps to set it up. If you will only use WebSmart ILE you can skip this step.

1. Copy the xdebug.so file to your Zend IFS directory.
When you install WebSmart on the server the file xdebug.so is created in your IFS, in the folder /esdi/websmart/.

Open your IFS and copy the file xdebug.so to /usr/local/zendsvr/lib/debugger/.

Note that the locations here and below are the most likely. Depending on whether you have Zend Core or Zend Server installed, your locations for these files and the Zend directory structure may vary.

2. Update your php.ini file.
Still in your IFS, find and open the file usr/local/zendsvr/etc/php.ini (the location may vary slightly if you are using Zend Core). Add these lines:

[xdebug]
zend_extension="/usr/local/zendsvr/lib/debugger/xdebug.so"
;xdebug.remote_enable=On
xdebug.remote_enable=1
xdebug.remote_host= 
xdebug.remote_mode=req
xdebug.remote_port=9000
;xdebug.remote_handler="dbgp"
;xdebug.trace_output_dir=""
;xdebug.remote_autostart=On
;xdebug.remote_handler=dbgp
;xdebug.idekey="IDEKEY"

In the file above, make sure the zend_extension path matches the location where you copied xdebug.so. Then replace the value with the IP address of the PC on which you are running WebSmart. In this release of WebSmart PHP the debugger only supports a single active user at a time.

One way to find your IP address is by going to Start > Control Panel and selecting Network Connections. In the list of network connections, right-click the Local Area Connection icon and select the Status option. In the Support tab you can find your IP address. Note that these instructions may vary by PC operating system. You can also just ask your Network Admin!

Disable the Zend debugger.
Zend’s debugger only works with Zend Studio and can’t be used with other IDEs. To disable Zend’s debugger, find the line below (if present) and insert a semi-colon at the start of it (to comment it out):

;zend_extension_manager.dir.debugger=/usr/local/zendsvr/lib/debugger

Save and close php.ini.

4. Restart your PHP server.
This step depends on whether you have Zend Core or Zend Server installed:

  • Zend Core. Restart the Zend Core subsystem.
  • Zend Server. Restart your WebSmart HTTP server instance.

5. Confirm your settings.
To confirm your settings you can execute the phpinfo(); function.

If you aren't sure how to do this, an easy way to display this information is by creating a new WebSmart PHP program using the “A Simple Page” template and inserting the line “phpinfo();”. Then press F6 to save, generate and run your program.

At the phpinfo page search for "xdebug.remote_enable"; this option should be set to On. Then search for "xdebug.remote_host"‘; this should show your computer’s IP address.

If the settings are wrong verify that you followed all the steps above.

  
Troubleshooting   

Note that the PHP currently only supports single client debugging. The value in the php.ini file must match the IP address of the client using the debugger. The reason for this is that debugging requests are actually initiated by the server, and if the client does not respond it assumes no one wants to debug and ends the debugging session.

Search our Knowledge Base Opens new window on this topic.

Step 11. Additional Miscellaneous Configuration Settings.
Finally, below are some additional configuration settings that may be relevant to you, depending on the type of applications you intend to build.

Set up Time Zones for PHP on the IBM i
If you will use time functions in your PHP programs at some point you need to set up times zones (if you haven’t already). You can find information on this on Zend’s web site at:

http://kb.zend.com/index.php?View=entry&EntryID=320

Unless you set up your time zone PHP scripts return the wrong time of day.

Configure the UTC Offset for Sending Email from WebSmart ILE Programs
The UTC offset for your SMTP server is used to correctly timestamp emails that you build and send out using the WebSmart ILE sendmailex function.

For instructions on how to configure this setting, please review Knowledge Base article 8054.

  
Troubleshooting   

You can also refer to the section "ECFGSMTP - Configure sendmailex SMTP Server" in Chapter 15 of the Reference Guide for additional information on configuring emailing options.

Step 11. Moving On.

At this point you should be ready to try running the software and start learning how to use it.

Continue with Step 2 of the 5 Steps to Success for:

If at any point in this process you would like to have an informal chat with someone to get some suggestions on how to address your particular needs, then by all means get in touch with our Sales or Technical Support teams.

We look forward to hearing from you soon.