Embed Size (px)
Citation preview
www.zend.com
Zend Server 5 for IBM i Reference Manual By Zend Technologies
Abstract This is the Reference Manual for Zend Server for IBM i Version 5.0 Beta.
The information in this document is subject to change without notice and does not represent a
commitment on the part of Zend Technologies Ltd. No part of this manual may be reproduced or
transmitted in any form or by any means, electronic or mechanical, including photocopying,
recording, or information storage and retrieval systems, for any purpose other than the
purchaser’s personal use, without the written permission of Zend Technologies Ltd.
All trademarks mentioned in this document, belong to their respective owners.
© 1999-2009 Zend Technologies Ltd. All rights reserved.
Zend Server for IBM i Reference Manual, issued October 2009.
DN: ZIBMi-RM-211009-5.0-001
iii
Table of Contents Zend Server for IBM i ...................................................................................................................... 1
Overview ...................................................................................................................................... 1 About ............................................................................................................................................ 2 Installation Directories .................................................................................................................. 2 Password Management ............................................................................................................... 3 Support ......................................................................................................................................... 4
Zend Support Center ................................................................................................................ 4 Zend Forums ............................................................................................................................ 4 Online Documentation .............................................................................................................. 4 Open a Support Ticket (Only Available in Zend Server) .......................................................... 4 Zend PHP Email Updates ........................................................................................................ 4 Zend Developer Zone Resource Center .................................................................................. 5 Feedback .................................................................................................................................. 5
Administration Interface ............................................................................................................... 6 General Layout ......................................................................................................................... 6
Monitor Tab .................................................................................................................................. 7 Dashboard ................................................................................................................................ 7 Events ....................................................................................................................................... 8 Event Details ............................................................................................................................ 9 Jobs ........................................................................................................................................ 12 Queue Statistics ..................................................................................................................... 14 Code Tracing .......................................................................................................................... 15 Server Info .............................................................................................................................. 21 PHP Info ................................................................................................................................. 22 Logs ........................................................................................................................................ 23 Applications ............................................................................................................................ 24 Applications window ............................................................................................................... 25 Demo Applications window .................................................................................................... 25
Rule Management Tab .............................................................................................................. 27 Monitoring ............................................................................................................................... 27 Edit Rule (Monitoring) ............................................................................................................. 28 Caching .................................................................................................................................. 30 Edit Rule (Caching) ................................................................................................................ 31 Recurring Jobs ....................................................................................................................... 33
Rule Information ......................................................................................................................... 34 Server Setup Tab ....................................................................................................................... 35
Components ........................................................................................................................... 35 Extensions .............................................................................................................................. 37 Directives ................................................................................................................................ 38 Debugger ................................................................................................................................ 39 Monitor Configuration ............................................................................................................. 40 Job Queue .............................................................................................................................. 42 Zend Server for IBM i 5250 Bridge Settings ........................................................................... 43
Administration Tab ..................................................................................................................... 44 Password and License ........................................................................................................... 44 Updates .................................................................................................................................. 45
Tasks .......................................................................................................................................... 47 Working with Zend Server for IBM i ....................................................................................... 47 Getting Started with Zend Server for IBM i ............................................................................ 50 Configuring Zend Server for IBM i .......................................................................................... 53 Working with Extensions ........................................................................................................ 54 Working with Logs .................................................................................................................. 56
Zend Server 5 for IBM i Reference Manual
iv
Working with Events ............................................................................................................... 60 Creating a Job ........................................................................................................................ 69 Working with Code Tracing .................................................................................................... 73 Working with the Debugger .................................................................................................... 76 Working with the Zend 5250 Bridge ....................................................................................... 78 Working with Components ..................................................................................................... 80 Working with Directives .......................................................................................................... 82 Working with Optimizer+ ........................................................................................................ 83 When Not to use Optimizer+ (Blacklist)? ............................................................................... 83 Working with Zend Guard Loader .......................................................................................... 86 Working with Data Cache ....................................................................................................... 87 Working with Java Bridge ....................................................................................................... 90 Working with Local Debugging ............................................................................................... 93 Working with Monitoring ......................................................................................................... 94 Disabling Event Rules ............................................................................................................ 95 Working with Caching ............................................................................................................. 96
Components ............................................................................................................................. 101 Debugger .............................................................................................................................. 102 Optimizer+ ............................................................................................................................ 103 Guard Loader ....................................................................................................................... 104 Data Cache ........................................................................................................................... 105 Java Bridge ........................................................................................................................... 106 Zend 5250 Bridge ................................................................................................................. 108 Zend Framework .................................................................................................................. 112 Monitor .................................................................................................................................. 114 Page Cache .......................................................................................................................... 116 Job Queue Component ........................................................................................................ 117 Zend Code Tracing ............................................................................................................... 119 Zend 5250 Bridge ................................................................................................................. 120 Applications .......................................................................................................................... 124 Working with the Demo Applications .................................................................................... 125 Working with the Zend 5250 Bridge ..................................................................................... 127 Zend Server for IBM i 5250 Bridge Settings ......................................................................... 129 Working with the Zend Server 5250 Emulator ..................................................................... 130 CSS Editing .......................................................................................................................... 136 Opening Files in Zend Studio ............................................................................................... 139 5250 Bridge API ................................................................................................................... 141 Working with the 5250 Bridge API........................................................................................ 143 Using the 5250 Bridge API ................................................................................................... 144 Troubleshooting the Zend 5250 Bridge ................................................................................ 150 FAQ ...................................................................................................................................... 151
Reference Information ............................................................................................................. 154 Java Bridge Use Cases ........................................................................................................ 155 PHP Extension List ............................................................................................................... 159 Zend Server Extension List - PHP 5.2 ................................................................................. 160 Zend Server Extension List - PHP 5.3 ................................................................................. 165 Adding Extensions ................................................................................................................ 170 UNIX: Compiling PHP Extensions forZend Server for IBM i ................................................ 172 Info Messages ...................................................................................................................... 178
API Reference ............................................................................................................................. 180 Introduction .............................................................................................................................. 180 Zend Debugger ........................................................................................................................ 181
PHP API ............................................................................................................................... 181 INI Directives: ....................................................................................................................... 181
Zend Optimizer+ ...................................................................................................................... 185 PHP API ............................................................................................................................... 185
Table of Contents
v
External Configuration File: Optimizer+ blacklist file ............................................................ 185 INI Directives: ....................................................................................................................... 185
Zend Guard Loader .................................................................................................................. 192 PHP API ............................................................................................................................... 192 INI Directives: ....................................................................................................................... 195
Zend Data Cache ..................................................................................................................... 197 PHP API ............................................................................................................................... 197 INI Directives: ....................................................................................................................... 200
Zend Java Bridge ..................................................................................................................... 203 PHP API ............................................................................................................................... 203 INI Directives: ....................................................................................................................... 207
Zend Extension Manager ......................................................................................................... 209 Zend Utils ................................................................................................................................. 211
INI Directives: ....................................................................................................................... 211 Zend Page Cache .................................................................................................................... 212
PHP API ............................................................................................................................... 212 INI Directives: ....................................................................................................................... 213
Zend Monitor ............................................................................................................................ 216 PHP API ............................................................................................................................... 216 INI Directives: ....................................................................................................................... 219
Zend 5250 Bridge API .............................................................................................................. 227 Zend 5250 Bridge Object Oriented API ................................................................................ 227 Zend 5250 Bridge Procedural API Functions ....................................................................... 233 Zend 5250 Bridge Use Case Examples ............................................................................... 237 Zend Monitor Node Daemon ................................................................................................ 240
Zend Job Queue ...................................................................................................................... 243 PHP API ............................................................................................................................... 243 INI Directives: ....................................................................................................................... 255
Zend Job Queue Daemon ........................................................................................................ 258 INI Directives: ....................................................................................................................... 258
Zend Tracer .............................................................................................................................. 265 PHP API ............................................................................................................................... 265
PHP Toolkit for IBM i ................................................................................................................... 272 Introduction to the PHP Toolkit for IBM i .................................................................................. 272 PHP Toolkit for IBM i ................................................................................................................ 273 PHP Toolkit Classes (sample) ................................................................................................. 273 INSTALLATION........................................................................................................................ 274 Zend Studio IDE templates ...................................................................................................... 274
PHP Toolkit Functions .......................................................................................................... 275 PHP Toolkit Data Description ............................................................................................... 318 Program Samples ................................................................................................................. 327 Data Queues ........................................................................................................................ 330 PCML Program Call - PCML Description Used in the PHP Program .................................. 335 PCML Program Call 2 - PCML File External to PHP Program ............................................. 337 List of an RPG Program, "TESTSTRUC", Called by the PCML Sample Programs ............. 338 Web Services ....................................................................................................................... 339 Web Services - Client Side ................................................................................................... 340
IBM i Toolkit Templates ........................................................................................................... 341 Zend Server for IBM i Installation Guide ..................................................................................... 344
Installing Zend Server for IBM i ................................................................................................ 345 Installation Directories .............................................................................................................. 345 Choosing Which Distribution to Install for IBM i ....................................................................... 346 Silent Installation ...................................................................................................................... 347 Interactive Installation .............................................................................................................. 348
To run an interactive installation: ......................................................................................... 348 Windows-Based Installation ..................................................................................................... 353
Zend Server 5 for IBM i Reference Manual
vi
To install Zend Server for IBM i through Windows: ............................................................. 353 MySQL Installation ................................................................................................................... 355 Uninstalling Zend Server for IBM i ........................................................................................... 359 Post Installation ........................................................................................................................ 360
Package Setup and Control Scripts IBM i ............................................................................ 361 Starting Zend Components on IBM i .................................................................................... 361 Ports and Services for IBM i ................................................................................................. 362 Changing the Apache Port ................................................................................................... 362
Installed Components for IBM i ................................................................................................ 363 Installation Directories .......................................................................................................... 363
Upgrading Zend Server for IBM i ............................................................................................. 367 Upgrading to a Newer Version of Zend Server for IBM i ...................................................... 367 Zend Server for IBM i ........................................................................................................... 367 Upgrading Zend Server for IBM i ......................................................................................... 367
Updating Zend Server for IBM i ............................................................................................... 369 Manual Rollback ................................................................................................................... 369 Welcome to Zend Server for IBM i ....................................................................................... 370 7 Ways to Get Started with PHP on IBM i ............................................................................ 370 Accessing PHP Open Source Applications .......................................................................... 371
Registration .............................................................................................................................. 372 Setting a Password .................................................................................................................. 372 Licenses ................................................................................................................................... 373
How do I just take a look at the product? ............................................................................. 373 How do I get a License? ....................................................................................................... 373 I already have a License - what do I do? ............................................................................. 373 License Expiration ................................................................................................................ 374
Zend Server for IBM i Setup Menu .......................................................................................... 375 Sign-On ................................................................................................................................ 376 Main Menu ............................................................................................................................ 377 Changing the Administration Console Password ................................................................. 379 Update using PTFs menu ..................................................................................................... 380 Runing the Support Tool ...................................................................................................... 381 Zend Server for IBM i Service Management ........................................................................ 382 Start Zend Server Subsystem .............................................................................................. 382 Stop Zend Server Subsystem .............................................................................................. 383 Start Apache server instances ............................................................................................. 383 Stop Apache server instances .............................................................................................. 383 ReStart Apache server instances ......................................................................................... 383 Start PHP Toolkit service (i5_COMD) .................................................................................. 383 Stop PHP Toolkit service (i5_COMD) .................................................................................. 384 Monitor Management Menu ................................................................................................. 384 Java Bridge Management Menu .......................................................................................... 385 PRNGD (ZC_STR_PRN) job Management Menu ............................................................... 386 Start PRNGD (ZS_STR_PRN) job ....................................................................................... 386 Stop PRNGD (ZS_STR_PRN) job ...................................................................................... 386 Add restart PRNGD (ZS_STR_PRN) job to scheduler ....................................................... 387 Work with PRNGD (ZS_STR_PRN) scheduled jobs............................................................ 387 Java Bridge Management Menu .......................................................................................... 388
MySQL Management menu ..................................................................................................... 389 Start MySQL subsystem ....................................................................................................... 389 Stop MySQL subsystem ....................................................................................................... 389 Start MySQL daemon ........................................................................................................... 389 Stop MySQL daemon ........................................................................................................... 390
5250 Bridge Management Menu.............................................................................................. 391 Restart 5250 Bridge Server ..................................................................................................... 391 Reset 5250 Bridge Environment .............................................................................................. 391
Table of Contents
vii
Zend Server Best Practices ......................................................................................................... 392 Introduction .............................................................................................................................. 392 Performance ............................................................................................................................. 393
What's in the Performance Section ...................................................................................... 393 Optimizing Zend Server Performance .................................................................................. 394 Fine Tuning Optimizer+ ........................................................................................................ 396 Disabling Code Change Auto-Detection .............................................................................. 396 Decreasing Code Validation Frequency ............................................................................... 396 Configuring PHP for Performance ........................................................................................ 397
IIS Configuration Optimization ................................................................................................. 401 Tuning FastCGI Configuration for IIS6 ................................................................................. 401 Tuning FastCGI Configuration for IIS7 ................................................................................. 402
Security .................................................................................................................................... 403 What's in the Security Section .............................................................................................. 403 Configuring Debugger Access Control ................................................................................. 404 Securing the Administration Interface .................................................................................. 405 Configuring PHP for Security ............................................................................................... 406
Development ............................................................................................................................ 408 What's in Development......................................................................................................... 408 Working with Zend Framework ............................................................................................. 409 Loading Zend Framework Classes ...................................................................................... 409
Configuring Zend Framework .................................................................................................. 411 Configuring Zend Server for IBM i to Run a Zend Framework Application .......................... 411 Where is My Apache Configuration File? ............................................................................. 412
Advanced Diagnostics with Zend Server ................................................................................. 413 Advanced Diagnostics with Zend Server ............................................................................. 413 Custom Event ....................................................................................................................... 414 Slow Function Execution ...................................................................................................... 416 Function Error ....................................................................................................................... 418 Slow Request Execution ...................................................................................................... 420 High Memory Usage ............................................................................................................. 422 Inconsistent Output Size ...................................................................................................... 423 PHP Error ............................................................................................................................. 424 Java Exception ..................................................................................................................... 426 Database Error ..................................................................................................................... 427
1
Zend Server for IBM i Overview Zend Server for IBM i is a Web application server geared towards various usage models and
environments. This product is intended for architects, IT managers and system administrators
who want to maintain high quality of service on their Websites by:
Boosting application performance and throughput
Maintaining application reliability and security
Improving application management
Zend Server 5 for IBM i Reference Manual
2
About Zend Server for IBM i provides optimized PHP distribution for developers. Zend Server for IBM i
includes a tested and certified version of PHP and a set of tools to set up and optimize your
environment.
These tools are presented in an improved Administration Interface designed to provide all the
tools and technology necessary to support PHP developers.
Special attention has been given to creating consistency across operating systems to ensure
interoperability and facilitate the needs of diverse environments that use Linux, and Windows .
The PHP version is PHP 5.2 which has been tested and optimized for development use.
Commonly used extensions and Zend Framework are included with the PHP to provide a one-
stop shop for all the resources that developers need to create PHP Web applications.
A complementary set of tools is provided with Zend Server for IBM i to optimize and extend your
PHP capabilities. The tools included in Zend Server for IBM i are described in detail in the
Components Section. Instructions on how to work with each component are provided in the Tasks
section, where each possible task is described in detail from start to end.
To get started with Zend Server for IBM i , click here.
Installation Directories Not all users decide to install their software in the same location. To reflect this requirement, all
paths in this document have been replaced with the following prefix: <install_path>. This
represents the location of the installed files. If you used the default settings, the location should
be as follows:
For Zend Server for IBM i for IBM i Installation Directories, see IBM i Installation Guide
Zend Server for IBM i
3
Password Management After completing the Installation process and opening Zend Server for IBM i, a password
definition page is displayed for first time users. This page only appears once and is used to define
the Administration Interface's login password.
For security reasons, Zend Server for IBM i cannot restore your password for you. However, you
can reset your password.
The following procedure describes how to reset a lost password from outside the Administration
Interface.
To reset your password:
In IBM i:
Use Setup menu option 1
Correct completion of this procedure in Windows: Zend Server for IBM i displays the password
definition page.
Correct completion of this procedure in other operating systems: You can log in with the new
password.
If you are unable to change your password, refer to the Support Center for further information.
The following procedure describes how to change your password from inside the Zend Server for
IBM i Administration Interface.
To change your password from inside the Administration Interface :
1. In the Administration Interface, go to Administration | Password .
2. Enter your current password and enter your new password in the next two fields.
3. Click "Change Password" to apply changes.
Correct completion of this procedure results in Zend Server for IBM i requiring you to log in with
the new password the next time you access the Administration interface.
Zend Server 5 for IBM i Reference Manual
4
Support Zend Technologies provides a wide range of resources for obtaining additional information and
support, such as the Zend Support Center, the Zend Newsletter, and the Zend Developer Zone.
Zend Support Center The Zend Support Center is a portal for information on all Zend Product related issues.
From the Zend Support Center you can access:
Zend Forums Hosted user forums for the Zend product user community. See what other users have to say and
get answers directly from the Zend Support team. Visit: http://forums.zend.com
Online Documentation The Zend Product Online Documentation Center can be easily browsed and searched as a
resource for accessing the most to date information on using all Zend Products. Visit:
http://www.zend.com/en/resources/zend-documentation/
Open a Support Ticket (Only Available in Zend Server) If you did not find the answer to your question in any of the Support resources, you can open a
ticket with the Zend Support team, who will answer each ticket on an individual basis. This can be
done through https://www.zend.com/en/helpdesk/newticket.php.
Zend PHP Email Updates Sign up for Zend PHP email updates for the hottest updates, special promotions and useful
developer information.
To sign up, log in to your Zend account at https://www.zend.com/en/user/myzend, enter your
email address and click Subscribe.
Zend Server for IBM i
5
Zend Developer Zone Resource Center The Zend Developer Zone is the leading resource center for PHP developers, where you can
learn about PHP and meet the experts.
The Zend Developer Zone features the following:
The PHP 5 Info Center
Articles and Tutorials
PHP and PEAR News Weeklies
Worldwide Job Classifieds
Visit: http://devzone.zend.com
Feedback Send feedback, questions and comments on the Online Help and Documentation to:
Zend Server 5 for IBM i Reference Manual
6
Administration Interface
General Layout Zend Server for IBM i's Administration Interface is the main area for configuring and managing
your development environment.
The Administration Interface is accessed through your browser by entering the link that is
provided at the end of the installation process. Login is done through the Password administration
page that appears when you access the Administration Interface for the first time.
Note: Using the standard browser buttons is not recommended: They may cause unexpected behavior.
The Administration Interface is comprised of the following tabs:
Monitor - The Monitor tab is the main area for system information and it includes
Dashboard | Events | Jobs | Queue Statistics | Code Tracing | Server Info | PHP Info |
Logs.
Rule Management - The Rule Management tab is the main area for configuring the
performance and monitoring features and it includes
Monitoring | Caching | Recurring Jobs .
Server Setup - The Server Setup tab is the main area for configuring your PHP and it
includes
Components | Extensions | Directives | Debugger | Monitor | Job Queue | 5250 Bridge .
Administration - The Administration tab is the main area for configuring your Zend
Server for IBM i system settings and it includes
Passwords .
In addition to the main Administration Interface, Zend Server for IBM i comes with a tray utility
called the Zend Controller that provides quick access to:
Frequently searched reference information
Quick links to the administration interface
Extension control
Benchmarking tool
Zend Server for IBM i
7
Monitor Tab
Dashboard The Dashboard page is accessed from Monitor | Dashboard and is the default page after
logging in to the Administration Interface.
The Dashboard page is a summary of information and quick links. The information in this page is
divided into Recent Events, Tasks and a System Overview.
Recent Events show the top five most critical events that occurred in your system.
Clicking on an Event ID will display the full audit trail. The full list can be found in Monitor | Events.
Tasks include quick links to configuration tasks and useful information. Clicking on a link
directs you to the appropriate page in the Administration Interface.
The System Overview lists information about your environment including PHP version
and a Zend Components status display.
Zend Server 5 for IBM i Reference Manual
8
Events The Events page is accessed from Monitor | Events
The Events page is the main display for events that are generated based on the conditions
defined by the Monitoring Rules. Events contain information about a specific occurrence that
indicates that your environment is displaying uncharacteristic behavior. You can use the Events
page to perform additional actions to diagnose the problem.
The actions that can be performed from this page are Filter, View Event Details and Change
Status.
Each individual event includes specific information about the occurrence, such as when it
happened, how many times it happened and other details that can assist a developer in
diagnosing the event. More advanced diagnostic information includes information about the
request that generated the event or backtrace information.
Each event type is slightly different and therefore the information collected and displayed for each
event may differ. For example, a Slow Request event does not include information on a source
file or line of code, because the event was generated by a request. The same is true for Java
backtrace information: Java backtrace information is only included for Java exception events.
Zend Server for IBM i
9
Event Details The Event Details page is accessed from Monitor | Events by selecting an event from the list
and clicking on the row.
The Event Details page is the main display area for information regarding the occurrence of a
specific type of event.
Information on how an event is triggered is presented in Event Rules.
The following actions can be performed from the Event Details page:
Back to Events - Returns to the Events page.
Refresh - Refreshes the report. Refreshing the report updates the event counter if the
event occurred additional times.
Detach - Opens the report in a new browser window.
Diagnose - Applies Zend Studio for Eclipse (ZSE) diagnostics to the selected event
details (Debug event, Profile Event, Open in ZSE).
Change Status - Changes the status of the event displayed. For a complete explanation
of event handling, see Working with Events.
On the Event Details page, users can view a general summary of an occurrence, its status and
diagnose the occurrence with Zend Studio for Eclipse.
Zend Server 5 for IBM i Reference Manual
10
Event Details - Information
The following list describes the information types displayed in the Event Details Page
Top Bar:
Number of Occurrences - The accumulated amount of times the event was triggered.
Refreshing the report updates this number if the event occurred additional times.
First Occurrence - When the event was triggered for the first time.
Last Occurrence - When the event was last triggered.
Status - The status if the event: Open, Closed, Reopened and Ignored. For a specific
event, the status can be changed in the Event Details page: For multiple events, the
status can be changed in the Events page.
Severity - The severity of the event (Warning or Critical). The severity is defined in the
event's master settings in the Monitoring tab.
Event Details Table:
Events are aggregated into groups based on the time they occurred. The aggregation is set to
five minutes: Thus, all the events that occur within that time frame are grouped together. Each
time a set of events is aggregated (i.e., a new group is created), the occurrence details are
collected again. To view the event occurrence details for a group, click on the group in the Event
Details table: The display on the right is changed.
The Event Details Table options are:
Last Time - when the last event in this group occurred
Count - the number of events triggered in the same time frame (set to five minutes)
Clicking on one of these options updates the display with the relevant information.
Zend Server for IBM i
11
Event Details The Event Details are a collection of information relevant to the event that occurred. Because the
information for each event may be different, the events may not display the same details.
The following list presents the possible details that can be displayed for an event:
Export - generates an XML file containing the selected event's information.
General Data - Displays information about the event: The data changes according to the
event type.
Function Data - Displays information on the function that triggered the error, including
the function name and arguments.
Request - Displays information about the request. The superglobals (POST, GET and
COOKIE) are always displayed. The other parameters (RAWPOST and FILE) are
displayed only when there is relevant information to display.
Server - Displays the superglobals SERVER and ENV when there is relevant
information.
Session - Displays the superglobal SESSION when there is relevant information.
Backtrace - Displays all the function calls that were made before the event was
triggered, including the relevant files for each function.
Error Data - Displays the PHP error and the Java backtrace if there was a Java
exception.
Custom Variables - Displays information for a custom event (i.e., class and user-defined
information that was passed to the event when it was triggered).
Studio Integration - Displays the actions can be applied to event details if Zend Studio
for Eclipse (ZSE) is installed and Zend Server for IBM i is configured to communicate with
it:
• Debug Event - Initiates a debug session fort he event URL in ZSE.
• Profile Event - Profiles the event URL, using the ZSE Profiler with the same
parameters (GET, POST, COOKIE, HTTP headers, etc.).
• Show File in Zend Studio - Opens the file where the event occurred in Zend
Studio. This option makes it possible to use Zend Studio to edit files and
implement changes for multiple servers.
Settings: through this option you can choose to apply the Studio Integration actions to
the Originating Server (the server on which the event was triggered) or to an Alternate
Server (a different server running the same environment).
Zend Server 5 for IBM i Reference Manual
12
Jobs The Jobs page is accessed from Monitor | Jobs.
The Jobs page is the main display for jobs that are scheduled in your environment. The jobs
listed in this page refer to jobs created as follows:
Based on the conditions defined in the Recurring Jobs tab.
Non Recurring Jobs
Jobs generated by the Job Queue API
Jobs contain information about a specific Job that you have set to run in your environment. You
can use the Jobs page to perform additional actions to follow up on Job activity.
The actions that can be performed from this page are Filter, View Job Details and Delete Job.
New jobs are created in Rule Management | Recurring Jobs.
Each individual Job includes specific information about the occurrence, such as the URL,
Application, Status, Priority and Run Time all details that help assess job activity. More advanced
diagnostic information includes information about the variables, priority and dependencies.
Zend Server for IBM i
13
Job Details
The Job Details page is accessed from Monitor | Jobs by selecting a Job from the list and
clicking on the row.
The Job Details page is the main display area for information regarding a specific job.
Information on how a job is created is presented in Recurring Jobs.
The following actions can be performed from the Job Details page:
Back to Jobs - Returns to the Jobs page.
Refresh - Refreshes the Job information.
Detach - Opens the Job details in a new browser window.
Re-queue - Reschedules a non re-occurring Job to run.
Zend Server 5 for IBM i Reference Manual
14
Queue Statistics The Queue Statistics page is accessed from Monitor | Queue Statistics.
The Queue Statistics page is the main display for information regarding active Jobs that you have
defined in your system.
With this information you can track, monitor and evaluate the scope of active Jobs in your system.
Statistical Parameter Definitions
The daemon started at
Number of jobs added since last startup
Number of jobs served since last startup
Number of waiting jobs
Number of jobs waiting for predecessor
Number of running jobs
Number of completed jobs
Number of failed jobs
Number of scheduled jobs
Average job wait time x seconds
Average job run time
Zend Server for IBM i
15
Code Tracing The Code Tracing page is accessed from Monitor | Code Tracing.
The Code Tracing page is a central display and management area for all traced information .In
addition Trace information can be viewed per event by drilling-down to a specific event in Monitor | Events.
Zend Server Code Tracing captures full execution data of PHP applications in real time. The
execution data includes function call trees, arguments and return values, function execution
duration, memory usage and indication for executed files name and line of code. This enables
you to capture problems when they occur, which eliminates the need to set up environments and
reproduce the steps led up to the failure.
The trace displayed in the Zend Server web console enables you to view the execution history of
your application and follow in the footsteps of an individual, problematic request to quickly
pinpoint root cause.
Zend Server 5 for IBM i Reference Manual
16
Zend Server Code Tracing is an in-depth diagnostic tool that will allow you to drill-down to the
function level to view actual performance related information and statistics.
Trace information can be collected in one of two ways:
1. Collected as an additional level of event information by Monitor Rules mechanism to
generate a trace when an event occurs.
Traced information can contain information on more than one event that occurred
according to the reoccurrences of the event.
2. Manually Triggered
From this page you can:
Trigger a URL trace - Manually run code tracing on a specific URL
View trace information
Delete trace information
Zend Server for IBM i
17
Code Tracing Tree
The Code Tracing Tree is accessed from Monitor | Tracing and selecting a trace ID from the list.
The Tree tab displays the call tree for a selected event or dump.
The Tree tab is a table based display that includes the following columns:
Name: The name of the caught object in the dump. This could be an argument, return
value, function error, header etc.
Time: Duration in milliseconds including children
Percent: percentage of the total script runtime
Memory Usage:
• Own – memory used by this item
• Sum – Total memory usage after this item has ended
Filename: The file where the event happened. Hover over to see a tooltip with the exact
path to the file.
Line: The line of code where the event happened (in the file stated in filename).
Navigation
In Tables:
All tables are sortable by clicking once the table is sorted by that column, click again to
change the sort direction.
Zend Server 5 for IBM i Reference Manual
18
At any time you can hover over a component to see a tooltip that describes the
component and in certain cases additional information.
In the Tree tab:
Bold items indicate calls that took the most time to execute and this continues inside the
call itself – indicating the slowest calls.
This indicates the application’s critical path.
Double clicking on any item will jump to the relevant function in the Statistics tab.
Zend Server for IBM i
19
Code Tracing Statistics
Code Tracing Tree are accessed from Monitor | Tracing and selecting a trace ID from the list.
The Statistics tab is a table based display that provides a statistical perspective of the data
captured in the request. The same data is displayed in two different ways. The “All functions” area
at the top that lists all the functions included in the dump for a certain occurrence and the “Calls
for Functions” area at the bottom that displays the function calls for a function selected from the
list (by clicking on the function).
Use this tab to investigate performance information such as the slowest function (sorting the table
by 'own time' will help pinpoint this.
The “All Functions” area includes the following columns:
Function: The name of the function as it appears in the code.
Total Time: Total time taken by this function’s invocations including nested function calls.
Hovering over shows a tooltip with the average time.
Total %: Percentage of the total request time taken by this function’s invocation
including nested function calls.
Own Time: Total time taken by this function’s invocations not including nested function
calls (i.e. the time it tool to call other functions).
Own %: Percentage of the total request time taken by this function’s invocation not
including nested function calls (i.e. the time it tool to call other functions).
Zend Server 5 for IBM i Reference Manual
20
Calls: Function invocation count – how many times the function was called.
Memory: memory consumed by all invocations of the function.
Source: The file where the function was defined. Internal functions are not defined in a
file and therefore this column will be empty.
The “Calls for Functions” area includes the following columns:
File: The file where the call happened
Line: the line where the call happened
Total Time: time consumed by the call, including nested functions.
Own Time: time consumed by the call, excluding nested functions.
When selecting an item from the “Calls for Functions” list details about the actual call are
displayed if it is an object.
Navigation
In Tables:
All tables are sortable by clicking once the table is sorted by that column, click again to
change the sort direction.
At any time you can hover over a component to see a tooltip that describes the
component and in certain cases additional information.
In the Statistics tab:
Clicking on an item will display the function’s calls in the “Calls for Functions” area.
Double clicking on an item the “Calls for Functions” area will open it up to show where it
happened in the Tree tab.
Clicking on an item in the “Calls for Functions” area will display the calls argument and
return values if it is an Object.
Zend Server for IBM i
21
Server Info The Server Info page is accessed from Monitor | Server Info.
The Server Info page displays the details of your environment. The information displayed in this
page is as follows:
Zend Server - Product version.
PHP - PHP version and the path to your PHP configuration file (php.ini). This information
can also be accessed from the Administration Interface, on the PHP Info page.
Web Server - Your Web server's IP, type and the operating system used to run the Web
server.
Zend Framework - Release version and directory location in your computer.
Zend Data Cache - Release version and status.
Zend Debugger - Release version and status.
Zend Guard Loader - Release version and status.
Zend Java Bridge - Release version and status.
Zend Monitor - Release version and status.
Zend Optimizer+ - The status of the Optimizer+ component used for opcode caching
and optimizations.
Zend Page Cache - Release version and status.
Zend Job Queue - Release version and status.
Zend Code Tracing - Release version and status.
Zend Session Clustering - Release version and status
Zend Server 5 for IBM i Reference Manual
22
PHP Info The PHP Info page is accessed from Monitor | PHP Info.
The PHP Info screen is a read-only page that outputs a large amount of information about the
current state of PHP. It is an easily accessible representation of information contained in the
php.ini file, including information about PHP compilation options and extensions, the PHP
version, server information and environment, PHP environment, OS version information, paths,
master and local values of configuration options, HTTP headers and the PHP License.
Note: The values displayed in the PHP Info page may differ from the system-wide settings displayed
further down the page in the "Local View" column of the Configuration section. To see the
system-wide settings, view information listed in the "Master Value" column.
Changing PHP Info
The Administration Interface allows easy changing of PHP info through the Setup tab. Any
changes made in the Extensions, Components and Directives pages will be automatically
updated in your php.ini file and will be reflected in the PHP Info page.
Note: Configuration changes will only take effect once you PHP has been restarted by clicking
.
More information about the PHP Info display can be found in the PHP Manual, accessed by going
to "PHP Options and Information".
Zend Server for IBM i
23
Logs The Logs page is accessed from Monitor | Logs.
The Logs page is a means for developers to view log information directly from the Administration
Interface. This information can be used to investigate unwanted activity in your environment in
terms of errors and application behavior.
The logs displayed in this page consist of the system logs, as determined by the type of Web
server you use:
Apache servers include three logs - PHP Error log, Apache Error log and Apache Access
log - all of which reference the installation locations (except for the PHP Error log, which
comes from the error_log directive).
IIS servers include the PHP Error log.
IBM i Apache Servers include the PHP Error Log
Power users can edit the XML file to include additional logs. For more information on adding logs
to the Logs page, see Working with Logs.
Zend Server 5 for IBM i Reference Manual
24
Applications The Applications page is accessed from Monitor | Applications.
The Demo applications included in Zend Server for IBM i are a convenient tool for gaining insight
into how you can use the Zend 5250 Bridge API to extend your applications into a Web based
environment.
There are several ways to view the Demo page:
From the Administration Interface by clicking Monitor | Applications
By opening the following file in your browser:
http://<ServerIP>:10088/Zend5250Demos/index.html by replacing <ServerIP> with your
machines IP or Hostname.
A detailed list of the 5250 Bridge API functions that were used in order to create the Demo
Applications can be found in the Working with the 5250 Bridge API section.
The source code for the Demo Applications can be found in /usr/local/zendsvr/5250/demos. A
convenient way for developers to view the source files is by opening them in your Zend Studio
IDE.
See Opening Files in Zend Studio for more information on how to view the code in Zend Studio
for Eclipse.
Alternatively, you can view the content of the files from your preferred green screen emulation
using the following commands:
1. Change the directory to the location of the Demo files CD
"/usr/local/zendsvr/5250/demos".
2. Enter WRKLNK to list the contents of the demos directory.
3. Select one of the Demo directories:
Subfile Demo - subfile
Extended Subfile Demo - subfileExtended
To view the code that generates the demo open index.php in the Green screen emulation using
option 5 for each directory.
Zend Server for IBM i
25
Applications window
Zend 5250 Emulator
The Zend 5250 Emulator provides browser access to i/OS resources and applications equivalent
to an IBM© 5250 terminal without having to deploy telnet or terminal client applications.
Demo Applications window
5250 Bridge Demo Applications
The two Demo Applications demonstrate how the Zend 5250 Bridge API can be used to create
interactive web-applications for 5250 programs. Clicking one of the demo application links open a
new browser Window.
These demo applications were written in PHP using the Zend 5250 Bridge Procedural API
Functions using functions to organize the code and HTML for the display.
Note: The sample application code is located in: /usr/local/zendsvr/250/demos.
For more information about the Demo Applications and how you can recreate this functionality in
your environment see: Working with the Demo Applications.
Subfile Demo - The Subfile Demo demonstrates how you can use the 5250 Bridge API
to recreate IBM i resources in a Web based environment without using the 5250
emulation client look and feel. This provides a way to extend your IBM i resources to the
Web and provide a more user friendly application especially for users who are not familiar
with working in an IBM i environment. Another advantage of this method is that you can
control the layout of the screen and choose to add or remove information, input fields and
buttons. The demo itself is based on a sample application with limited functionality.
Subfile Extended Demo - The Extended Subfile Demo shows how you can use the
5250 Bridge API recreate IBM i resources in a web based environment without using the
5250 emulation client look and feel. This like the Subfile Demo, provides a way to extend
your IBM i resources to the web and provide a more user friendly application and in
addition demonstrates how you can improve the layout using HTML and AJAX. The
demo itself is based on a sample application with limited functionality.
Zend Server 5 for IBM i Reference Manual
26
Zend Navigator Demo Application
This Zend Navigator Demo Application shows the usage of PHP toolkit for IBM i functions. The
source code for this application can be found in /usr/local/zendsvr/apaches2/htdocs/
Zend_Navigator_Demo. The main file is called login.php. The demo application has the following
options:
Logon - This option allows you to logon to IBM i with a valid System i user profile.
Active Jobs - This option allows you to view all active jobs. You can use the "Load
Subsystem" filter to view jobs in selected subsystems. Clicking on a job line will display
some job details and job log.
Spooled Files - This option allows you to view current user spooled files. You can use the
'Load User' user filter to display other users' spooled files. Clicking in a spooled file line
will display the spooled file content. Some spooled file details and spooled file options
such as DELETE, HOLD/RELEASE or display spooled file content, will be displayed in
PDF format.
System Value - This option displays a full list of all IBM i system values.
User Profiles - This option allows you to view all user profiles on your server. Clicking on
a user profile line will display some user details and user status options, and will allow
you to enable or disable selected user profile statuses.
Database files - This option allows you to view all database files on your server. Selecting
a library from the drop-down list and clicking a file will display all data in the file. Click the
'File Description' button in the file display to see more information on the file.
Zend Server for IBM i
27
Rule Management Tab
Monitoring Monitoring Rules are defined and activated in Rule Management | Monitoring and they
generate events that are displayed in the Events page.
The Monitor component is set to run out-of-the box, based on default settings. To change the
Monitor component settings, see Working with Components. To configure a specific event, see
Edit Rule and to view generated events, see Events.
Monitoring is based on a set of predefined rules that can be configured to suit your environment's
requirements (such as performance thresholds) or enabled and disabled as necessary. Once
Zend Server for IBM i is installed, the monitor component begins to create events. To find out
more about event configuration methodologies, see Working with Monitoring.
The actions that can be performed from this page are Edit Rule and Disable Rule. To disable a
rule, click next to an event type and Restart Server. When a rule is disabled, the
information for that specific rule is no longer collected. For more information about when to
disable a rule, see Working with Monitoring.
In addition to creating issues to display events that occurred, you can define a rule to generate
trace information using Zend Code Tracing see Edit Rule to find out how to trigger code trace
collection from a Rule.
Zend Server 5 for IBM i Reference Manual
28
Edit Rule (Monitoring) The rule editing page is accessed from Rule Management | Monitoring. To edit a specific rule,
click the Edit link next to the rule name.
This page is used to edit the conditions which generate an event (as displayed in Monitor | Events).
The following image is an example of a rule. (rule layout and parameters differ from rule to rule).
Zend Server for IBM i
29
The rule editing page lists all the relevant information for the selected event. The initial event
settings are based on the system defaults.
Name - A descriptive name for the event and the event's status (Moderate or Critical).
Description - A generic description of what triggers the event.
Event Type - The type of event this rule generates. For a list of event types, see Event
Types.
Event Condition - The exact function or parameter value that triggers the event.
Event Action - As soon as an event of this type is generated, trigger one of the following
actions:
• Send email to: send an email to the specified recipient.
• Save Trace Data: collect Code Tracing information.
• Activate Trace Data Collection for...: Wake the Code Tracing component from
sleep mode (performance optimization mode) for x seconds to collect trace
information and then resume trace mode. Additional Code Tracing Settings can
be found in Server Setup | Monitor.
Zend Server 5 for IBM i Reference Manual
30
Caching The Caching page is accessed from Rule Management | Caching. The Caching page is the central configuration area to configure rules to cache content by URL.
Caching by URL makes it easy to eliminate situations where the same file is used in multiple
instances, such as when the same file is used to redirect to several pages.
Note: Zend Server for IBM i also provides the ability to cache content using the Zend Data Cache (API).
To read more about the Data Cache, see Working with the Data Cache.
From this page you can:
Filter - Search for a specific rule by name.
Add Rule - Add a new rule to the Caching page. Each new rule is applied after restarting
PHP.
Delete Rules - A multi-selection for deleting redundant or unused Rules.
For each Rule you can:
Clear - Clear the selected rule's cached information.
Edit - Open the Rule for editing to modify settings.
Copy - Create a new rule based on an existing rule.
Zend Server for IBM i
31
Edit Rule (Caching)
The Edit Rule page is accessed from Rule Management | Caching, by clicking
or by clicking Edit next to a specific rule.
For more information and rule examples see: Working with Page Caching.
Note: URL caching conditions can be defined using Perl-Compatible Regular Expressions (PCRE). The
pattern syntax is the same as the syntax used by PHP's preg_match() and other preg_* functions.
For more information on the PCRE syntax, see
http://devzone.zend.com/manual/reference.pcre.pattern.syntax.html.
Caching Information
Rule Name - The unique name you give the rule. This name appears in the list in Rule Management | Caching.
Step 1: Caching Conditions
Define a Web page to cache by building the URL in the entry fields. Use the URL of the page you
want to cache and define how long to cache the page and the caching format and enter the
conditions for the rule:
Zend Server 5 for IBM i Reference Manual
32
Get - This refers to the parameters after the' ?' in the URL. Use this condition to cache
specific URLs, for example, caching a page with the URL:
http://localhost:81/index.php?page=gallery. When the rule is applied, only the specified
page is cached out of all the pages on http://localhost:81/index.php.
Server - This global variable can be used to determine server (Apache) parameters. The
most common usage of SERVER variables is to use the headers that are sent in the
request (i.e., variables that begin with HTTP - for example, HTTP_USER_AGENT), that
can be used to define rules based on browser type.
Session - This global variable originates from an active session and can be used to
cache (or specifically not cache) scripts if a specific variable exists (or has a value) in the
active session.
Cookie - This global variable stores information that is sent to the server from the
browser. A cookie can be used to cache banners such as "Related Search" banners
(which usually take time to compile), by displaying pre-cached banners according to the
information in the cookies.
Note: You can only cache URLs that display static content with a long rendering time or dynamic
content that you want to display statically according to time/parameters.
Match Any/All - If you use the option "Match any of the above", the pages will be
cached when the parameter given does not exist or if it exists that it equals the given
parameter. If you use the option "Match all of the above", the pages will be cached
either when the given parameter does not exist or when it is equals the given parameter.
Step 2: Cache Output
Define the cache's lifetime, compression settings and if you want to manage a different cache
version according to an additional parameter.
Lifetime - The duration of the cache content, after the set amount of seconds the cached
content will be replaced by new content.
Compression Settings - This option allows you to disable the creation of a gzip-
compressed version of each cached page as long as it is larger than 1KB. You should
normally leave this option checked.
Zend Server for IBM i
33
Recurring Jobs The Recurring Jobs page is accessed from Rule Management | Recurring Jobs. The Recurring Jobs page is the central configuration area to configure jobs to run by URL.
Running jobs by URL makes it easy to eliminate situations where the same file is run in multiple
instances, such as...
Note: Zend Server for IBM i also provides the ability to Schedule Jobs using the Job Queue API . To
read more about the Job Queue, see Working with Jobs.
From this page you can:
Filter - Search for a specific job by name.
Add New Recurring Job - Add a new job to the Recurring Jobs page. Each new job is
applied after restarting PHP.
Suspend - Temporarily stop the job from running while still saving the job definitions.
Settings are applied after restarting PHP.
Resume - Un-suspend a job. Settings are applied after restarting PHP.
Delete - A multi-selection for deleting redundant or unused Rules.
For each Rule you can:
Edit - Open the Rule for editing to modify settings.
History - View the details of each time the job ran.
Zend Server 5 for IBM i Reference Manual
34
Edit Rule (Job Queue)
The Rule page is accessed from Rule Management | Recurring Jobs, by clicking
or by clicking Edit next to a specific rule.
For more information and rule examples see: Working with Jobs.
Rule Information Create New Scheduling Rule Details: URL -
Name -
Application -
Schedule Job Details:
Use the options to define when the job should re-occur based on an hourly, daily, weekly or
monthly basis. selecting an option will change the different parameters to allow you to define
when the job will run. For example, choosing weekly scheduling will display options to set the job
to run on a specific day of the week.
After completion of a job (it doesn’t matter if it was succeeded or failed) the Job Queue re-
schedules its next execution with the same values.
Zend Server for IBM i
35
Server Setup Tab
Components The Components page is accessed from Server Setup | Components.
The Components page provides a convenient way to view and configure the components
installed in your environment.
The following components can be turned On/Off and configured as follows:
Component Status Comments
Zend Data Cache
On - Activates the Data Cache: Scripts
that include the Data Cache API can run. Off - Disables the Data Cache: Scripts
that include the Data Cache API cannot run.
This component stores
information and therefore
has an additional action for
clearing information.
Zend Optimizer+
On - PHP is optimized.
Off - PHP is not optimized.
This component stores
information and therefore
has an additional action for
clearing information.
Zend Java Bridge
On - The Java Bridge runs: Scripts
containing the Java Bridge API can run.
Off - The Java Bridge stops running:
Scripts containing the Java Bridge API
cannot run.
This component can be
restarted.
Zend Debugger
On - Activates the Debugger for local and
remote debugging with Zend Studio.
Off - Disables the Debugger and does not
permit debugging from Zend Studio.
The Debugger requires that
you enter a list of IP
addresses to allow, deny or
permit remote debugging
through a firewall.
Zend Guard Loader
On - Scripts encoded with Zend Guard
run.
Off - Scripts encoded with Zend Guard
cannot run.
Zend Monitor On - Event information, as defined in Rule Management | Monitor, is collected and
displayed in Monitor | Events.
Zend Server 5 for IBM i Reference Manual
36
Component Status Comments
Off - Disables the Monitor component:
Event information is not collected.
Zend Page Cache
On - Activates the page cache: URLs associated with caching rules are cached. Off - Disables the page cache: URLs marked to be cached are not cached.
This component stores
information and therefore
has an additional action for
clearing information.
Zend Code Tracing
Zend Job Queue
Zend 5250 Bridge
On - The 5250 Bridge runs: Scripts
containing the 5250 Bridge API functions.
Off - The 5250 Bridge stops running:
Scripts containing the 5250 Bridge API
cannot function.
If it is On, and there is a
license, then it allows
running multiple 5250
sessions. When there is no
license, it allows running
only one 5250 session.
Note: For more information on adding additional components, see the Installation Guide.
The On/Off Status is used to configure your php.ini according to the components you want to
load. If you intend to use functions related to a component in your code, verify that the extension
is enabled and that the status is set to On.
Hovering the curser over the Information icon displays a brief component description.
Zend Server for IBM i
37
Extensions The PHP Extensions page is accessed from Server Setup | Extensions.
The PHP Extensions page provides a convenient way to view and configure extensions.
Use this page to control and configure extensions that are loaded in your environment.
To find out how to add more extensions to this list, see Adding Extensions.
PHP extensions are sets of instructions that add functionality to your PHP. Extensions can also
be employed to recycle frequently used code. You can place a set of functions into one extension
and instruct your projects to utilize the extension. Another use for PHP extensions is to improve
efficiency and/or speed. Some processor intensive functions can be better coded as an
extension, rather than as straight PHP code.
The Extensions page is list of the extensions included with the Zend Server for IBM i installation
and extensions added to the php.ini by the user. Use the Extensions page to view the status of all
your extensions and to quickly and easily load and unload extensions.
You can also configure directives associated with certain extensions. Extensions with directives
that can be configured have a Configure link next to them.
Clicking the link opens the PHP Directives page, filtered to the exact directives associated with
the particular extension. Click the All option in the PHP directives page to see a complete list of
directives.
Extension Status
Extensions can have one of three different statuses:
Off - The extension is not running on the machine and code that includes the Extension's
functions works.
On- The extension is running on the machine.
Built in- This applies to extensions that have dependencies on, or were complied with
PHP. Built-in extensions cannot be removed and thus do not have an On/Off option.
Zend Server 5 for IBM i Reference Manual
38
Directives The PHP Directives Info page is accessed from Server Setup | Directives.
The PHP Directives page allows you to easily edit your PHP configurations from the
Administration Interface. From here, you can view and configure commonly used directives.
The available directives are grouped by category in expandable lists. Clicking the arrow next to
the category name expands the list to expose the different options. Where relevant, input fields
are added, to change a directive's value. The initial display shows the most commonly used
Directives. Click "All" for the full list of directives or use the "Search" component to locate a
specific directive or use ext:<extension_name> to find directives by extension. You can also use
the Popular option to view commonly used directives such as directives that define directories
and languages.
Zend Server for IBM i
39
Debugger The Debugger page is accessed from Server Setup | Debugger. The Debugger page is used to enable remote PHP debugging and profiling of Web applications
using the Zend Debugger component.
This component enables developers using the Zend IDE to connect to a remote server to analyze
(debug and profile) and fix code.
The Zend Debugger page allows you to configure the hosts for the following debug options:
Hosts allowed to initiate debugging and profiling sessions.
Hosts denied the permission to initiate debugging and profiling sessions.
Zend Server 5 for IBM i Reference Manual
40
Monitor Configuration
The Monitor page is accessed from Server Setup | Monitor. From this page, you can define the different settings for configuring the Zend Monitor component.
This component is used to capture PHP events when they happen and to alert developers and
system administrators. This can be done by using the events predefined in the Administration
Interface or by using the API.
The Monitor page is a settings definition page for the Monitor component that provides event-
based PHP monitoring.
Zend Studio Client Settings
Settings for using the integration with Zend Studio, to debug, profile and view event source code.
Zend Studio IP address - Manually configure the IP address according to the settings in
Zend Studio or use Auto Detect.
Use Browser IP Address check-box - Automatically selects the Browser IP Address.
Zend Studio debug port - Manually configure the port according to the settings in Zend
Studio or use Auto Detect.
Encrypt communication using SSL.
Note: Manual configuration settings should be based on the IP and port configured in Zend Studio's
Installed Debuggers preferences page. The preferences page is accessed from Window | Preferences | PHP | Debug | Installed Debuggers. (Click 'Configure' to view and change the
preferences).
The default port number is 20080.
Zend Server for IBM i
41
Mail Server Settings
Define the action settings for rules that use the action 'Send Mail'. The Send Mail action sends an
email that includes the event details and a link back to the Zend Server for IBM i Administration
Interface to the address(es) listed in the event rule. Note: If you do not plan to send email
notifications for events, you do not need to configure these settings.
SMTP server address - The server used to send mail.
SMTP server port - The port used to send mail.
Sender's email address - The email address that is displayed in the 'From' details of
each message.
Administration Interface URL - Use the valid Zend Server for IBM i address, includes
protocol (http or https), Server, and Port settings. The URL is included as a link in the
event email.
Code Tracing Settings
Activation options for running a code trace.
Active - Zend Code Tracing will collect trace information in Events that are defined for
collecting trace information
Inactive - Zend Code Tracing is running but no new trace data will be collected even
when a new event is triggered. The Manual Trace URL option (Monitor | Code Tracing)
will remain active.
Standby - The Zend Code Tracing will run in sleep mode and when an event defined to
collect trace info is triggered, Code tracing will be active for a set period of time (as
defined in the Monitor Rule).
Zend Server 5 for IBM i Reference Manual
42
Job Queue The Job Queue page is accessed from Server Setup | Job Queue.
From this page, you can define the different settings for configuring the Job Queue Component.
This component is used to schedule jobs to run a php script. This can be done by creating a Job
in Recurring Jobs or by using the API.
The Job Queue page is a settings definition page for the Job Queue Component that provides
Job scheduling capabilities.
The following settings options are available:
Quantity of simultaneous jobs: The amount of Jobs you permit to run at the same time
Verbosity level: The logs verbosity level
Zend Server for IBM i
43
Zend Server for IBM i 5250 Bridge Settings The 5250 Bridge Settings page is accessed from Server Setup | 5250 Bridge Settings.
The 5250 Bridge Settings page enables you to configure your settings for smooth integration with
other current user settings; for instance, language settings and characters, connection type and
performance, server time-out, and print screen as XML. The 5250 Bridge Settings tab includes
the following windows:
Zend 5250 Bridge
Zend 5250 Bridge Configuration
Zend 5250 Bridge
Click the Start service link to begin the service
Note: The same function can be invoked from the 5250 Bridge Management Menu (option 7 in the Zend
Server for IBM i Service Menu).
Zend 5250 Bridge Configuration
The Zend 5250 Bridge Configuration window enables you to integrate with your current user
settings:
I/OS EBCDIC Character Code Page (CCSID) - The values are: English, Italian, French,
German and Spanish. This setting allows to view 5250 screen special characters in a
browser
Persistent Connection - Define the connection type between the 5250 Bridge and your
System i server. Click, Yes for a persistent connection and No for the connection to be
terminated once the script has run. Persistent connections allow to increase 5250 Bridge
server connection-time performance. For more detailed information on persistent
connections,.refer to i5-pconnect in the PHP Toolkit section.
Server Time-Out (in microseconds) - The time to wait for a connection to the IBM i server
before timing-out. Decreasing the server timer-out allows to increase PHP script overall
performance using the 5250 Bridge API. This setting can be set to 0 for V5R4.
Print Screen Image as XML - This can be used by developers to debug their applications
by providing an XML version of the 5250 screen image. Clicking Yes, will add an
additional field for you to s pecify a path for saving the file containing screen image information in XML format.After
changing the settings, click Save to apply changes.
Zend Server 5 for IBM i Reference Manual
44
Administration Tab
Password and License
Updating your License
You are not required to enter a license to use Zend Server for IBM i . However, you must have a
valid license to use the complete edition of Zend Server for IBM i .
How do I get a license?
If you do not currently have a valid license, go to the licensing page to find out how to get a
license: http://www.zend.com/en/products/server/license
I already have a license, what do I do?
If you have already purchased a license, you should have received a confirmation e-mail that
includes your Order number and License key.
To enter a License:
1. Go to Administration | Password and License
2. In the "Update License" area, enter the Order number and License key that were
included in your confirmation email.
3. Click to apply the changes.
4. Click .
Zend Server for IBM i will start to run in a fully functional mode.
License Expiration
Before your license expires, a notification is displayed at the bottom of the Administration
Interface, telling you how long you have left until your license expires and where to go to renew
your license.
Once a license expires, Zend Server for IBM i reverts to the Community Edition mode until a new
license is entered. During this time, all the licensed features are unavailable. However, their
settings are kept and will be restored, along with the functionality, when a new license is entered.
Zend Server for IBM i
45
Updates The Updates page is accessed from Administration | Updates.
The Updates page is the central display area for the Zend Server for IBM i 's update mechanism.
Here you will find a list of all the available update packages from Zend's Web site.
This page provides information on the type, version and severity of the update for each
component. The actual updates are downloaded directly from zend.com's updates page -
http://www.zend.com/en/products/server/updates?zsp=updates.
Zend Server for IBM i checks for updates each time you log in to Zend Server for IBM i , or every
72 hours, provided that you are connected to the Internet.
When updates are available, you will see a message at the bottom of the screen with a yellow
'warning' triangle next to it.
Update Statuses
Depending on the importance of the update, each package is given a different status as follows:
Critical - Security fixes that are needed to help protect your Server. Ignoring these
updates could potentially open your environment to security threats.
Important - Performance and stability related updates that can improve PHP and
Web application performance.
Recommended - Fixes to the Administration Interface and non critical updates that
have no security or performance implications.
Zend Server 5 for IBM i Reference Manual
46
Rollback
Windows operating system users can use the operating system's Add/Remove programs
functionality to remove the last installed small update package. You cannot revert to a previous
version after you have performed an upgrade.
To remove an update:
1. Open the Control Panel from the Start menu.
2. Choose "Add or Remove Programs".
3. When the dialog opens, click "Show updates" to display the available updates for
Zend Server for IBM i .
4. Select the option "Zend Server for IBM i - Update 4.X.X - X" and click "Remove"
to delete the update - see the image below.
Zend Server for IBM i removes the update. When you re-enter the Administration Interface, the
message stating that updates are waiting for you reappears at the bottom of the Administration
Interface and in the Updates page.
Important: Do not select "Zend Server for IBM i", doing so will begin the uninstall process.
Zend Server for IBM i
47
Tasks
Working with Zend Server for IBM i The following text describes how to work with Zend Server for IBM i . Each of the tasks in this
section describes a different procedure that can be used to facilitate your PHP development
process.
The following table lists the different tasks, their descriptions and the expected outcome of each
task:
Task Description Outcome
Before Working with Zend
Server for IBM i
Review all the post
installation tasks before
working with Zend Server for
IBM i .
Access the Administration
Interface.
Configuring Zend Server A step-by-step overview of
all the possible configuration
tasks you need to perform to
customize Zend Server for
IBM i and your PHP.
A customized configuration
of Zend Server for IBM i that
suits your requirements.
See also Best Practices.
Working with Extensions How to enable and disable
extensions.
The environment is
customized to suit your
requirements.
Working with Logs How to view and add logs. View and define which logs
are displayed.
Working with Events How to find and manage
events.
Find events, view event
details and change event
statuses.
Working with Event Details What to do with the Event
Details report.
Understand the information
provided and diagnose
events using Zend Studio for
Eclipse.
Working with Components How to enable and disable
components (Debugger,
Data Cache Guard Loader,
Java Bridge , Download
The environment is
customized to suit your
requirements.
Zend Server 5 for IBM i Reference Manual
48
Task Description Outcome
Server and Page Cache ).
Working with Directives How to enable and disable
directives.
The environment is
customized to suit your
requirements.
Working with Optimizer+ How to use the Optimizer+. Improve performance by
running the Optimizer+.
Working with Guard Loader How to use the Guard
Loader component.
Run code encoded with
Zend Guard.
Working with Data Cache How to use the Data Cache
API.
Implement the Data Cache
API functions into your PHP
code.
Working with Java Bridge How to use the Java Bridge. Extend your PHP code to
reach out to Java
functionality in runtime.
Working with the Debugger How to configure the
Debugger to debug and
profile code running with
Zend Server for IBM i.
Use the local and remote
debugging features in Zend
Studio for Eclipse.
Working with Monitoring How to configure monitoring
rules.
Setup your Monitor
component for development
or production environments.
Managing Jobs How to use Jobs to help
manage your environment
Know how to implement
Jobs for off loading
processes.
Working with Code Tracing Locate trace information for
events and analyze.
Define which events should
collect trace information and
how to trigger a trace.
Working with Caching How to configure page
caching rules.
Define page caching rules
for URLs.
Working with Updates How to update Zend Server
for IBM i using the Updates
tab.
Download and install an
update package, depending
on your operating system.
Working with the Zend 5250
Bridge
How to use the components
and applications of Zend
Server for IBM i.
Use the 5250 Bridge on
Zend Server for IBM i.
Zend Server for IBM i
49
Task Description Outcome
Working with phpMyAdmin
to Manage MySQL
How to configure
PHPmyAdmin to work with a
MySQL database.
Manage your MySQL from
PHPMyAdmin through a link
in the Administration
Interface.
Zend Server 5 for IBM i Reference Manual
50
Getting Started with Zend Server for IBM i Zend Server for IBM i is a tool that requires a minimal amount of actual interaction with the
Administration Interface. Once your environment is setup, apart from occasionally logging in to
view your system settings or your php.ini, there are not many day-to-day activities that require the
Administration Interface.
The first point of reference for working with Zend Server for IBM i is what to do after installation.
What to do After Installing Zend Server for IBM i
The following section describes the tasks that should be performed after installing Zend Server
for IBM i for the first time.
These tasks cover all the different installation types (DEB, RPM, Tarball and Windows). Each
task is accompanied by a description of its purpose and the expected results.
Run the Administration Interface
Purpose: To verify the installation and that the Administration Interface is accessible.
Result: the Administration Interface opens in a browser.
The Administration Interface is a Web interface that runs through a browser.
This procedure describes how to view the Administration Interface.
To view the Administration Interface: 1. To run Zend Server for IBM i locally, open a browser and enter the following
URL:
For IBM i: http://IBM_i_hostname:10088/ZendServer
If you are using a remote connection, replace localhost with your Host Name or
IP.
2. The Zend Server for IBM i login screen opens and prompts you to set a
password.
This screen only appears once and is not displayed again after your password is
set.
The next time you log in to Zend Server for IBM i, you are prompted for the password you set the
first time you opened Zend Server for IBM i.
Zend Server for IBM i
51
Configure Your Password
Purpose: To ensure that you can access the Administration Interface.
Result: Your password is created.
When you first run Zend Server for IBM i, the registration screen is displayed. Define your Zend
Server for IBM i login password in this screen.
To view the different password management options, click Password Management.
Check Apache
Purpose: To verify that Apache is running.
Result: System confirmation.
This procedure describes how to check if the Apache Web server is running.
To check if the Apache server is running: IBM i: from the command line, run WRKACTJOB JOB(ZENDSVR)_
A notification with the Apache server status is displayed.
Run a Test on Your Web Server
Purpose: To verify that the installed Web server is running properly.
Result: The "Hello World" message is displayed in your browser.
This procedure describes how to run a test PHP script.
To run a simple test script: 1. Create a file called hello.php
2. Enter the following code into the file: <?php echo "Hello World"; ?> The "Hello World" message is displayed when the code runs in a browser.
1. Save the file in your Apache document root directory /www/zendsvr/htdocs. Only
files in this directory are serviced by the Web server. For information about the
document root directory, see Deploying Code with Zend Server.
2. Open a browser and enter the following URL: http://localhost:<port
number>/hello.php.
Replace <port number> with the port you are using. The default values are port
80 for Windows DEB and RPM and port 10088 for the other operating systems
unless you manually changed the port assignment.
Your browser displays the "Hello World" message.
Zend Server 5 for IBM i Reference Manual
52
Configure Debugger Access Control
Purpose: To enable PHP debugging using Zend Studio and Zend Server for IBM i.
Result: You are able to debug your PHP code and view the results in Zend Studio.
Before working with the Debugger, configure the allowed hosts in Server Setup | Debugger.
Note: By default, Zend Server for IBM i comes with a permissive setting that allows all standard private
IP addresses (for example 10.*.*.*) to access the Debugger. For security reasons, if you do not
have an immediate need for permissive access, remove these ranges from the Allowed Hosts:
10.*.*.* / 192.168.*.* / 172.16.*.*.
Additional setup information can be found in the Installation Guide, in Package Setup and Control
Scripts.
Zend Server for IBM i
53
Configuring Zend Server for IBM i This section refers to the actual configuration workflow for using Zend Server for IBM i . Here, we
describe the general workflow. Each component also has a separate section describing how to
work with the component in detail .
The Zend Server for IBM i 's Administration Interface is the main control center for configuring
your PHP and Zend Server for IBM i components. After installing Zend Server for IBM i , use the
Administration Interface to configure your PHP by performing the following actions:
1. In Server Setup | Extensions, define the extensions that should be "turned on" or
"turned off". If you are planning to use functions related to an extension in your code,
verify that the extension is turned on. If your extension has additional directives that are
used to configure the extension's behavior, a configure link is included in the Directives
column. Clicking this link leads you to the directives, pre-sorted to display the relevant
directives.
2. The Directives page is accessed by clicking Server Setup | Directives. Here, you find all
the directives relating to the extensions and components loaded in your PHP. If you
cannot find a directive in the directives page, look in Server Setup | Extensions or
Server Setup | Components to check that the extension or component is "turned on".
See Adding Extensions for instructions on how to manually add an extension.
3. In Server Setup | Components, define the Zend Server for IBM i components that should
be "turned on" or "turned off". If you are planning to use functions related to Zend Server
for IBM i components in your code (such as the Optimizer+, Data Cache, Debugger,
Guard Loader or Java Bridge), verify that the extensions are "turned on". If your Zend
Server for IBM i component has additional directives used for configuring the
component's behavior, a configure link is included in the Directives column. Clicking this
link leads you to the relevant directive in the Directives page .
4. In Server Setup | Debugger, define which hosts are allowed to connect to the server to
use the Zend Debugger for debugging and which hosts are not allowed.
5. In Rule Management | Monitoring , define the rules to generate events in Monitor |
Events . Additional Monitor settings to define behavior (such as integration with Zend
Studio for Eclipse and Mail settings for forwarding event information outside Zend Server
for IBM i ) can be found in Server Setup | Monitor . 6. In Rule Management | Caching , define the rules to cache output based on a URL.
Zend Server 5 for IBM i Reference Manual
54
Working with Extensions The Extensions page provides a convenient way to view and configure PHP extensions.
Use this page to control and configure the extensions that are loaded in your environment.
Changing Extension Status
To change an extension's status: 1. Go to Server Setup | Extensions.
2. Select an extension. In the actions column, click Turn off or Turn on:
Built-in extensions do not have the Turn on or Turn off option.
After changing an extension's status, a message appears to prompt you to click
the Restart Server button at the bottom of the screen .
You can turn more than one extension on (or off) before you click Restart Server
. All the changes that are made prior to restarting the server are applied after the
restart.
If you navigate to other tabs, the changes you make are saved and applied when
the server is restarted.
Changes are updated in the Server Info page and in your php.ini file. Changes are also applied
when the server is manually restarted.
Configuring Directives Associated with Extensions
To configure a directive associated with an extension: 1. Go to Server Setup | Extensions.
2. If the Extension has directives that can be configured, a link appears in the
directives column.
Clicking the link opens the Directives page, with the relevant directives already
filtered.
3. Configure the directive as required.
You can configure multiple directives before you save and apply your changes.
4. Click the Save Changes button at the top right corner of the
screen to save your changes. To discard changes, navigate away from the screen
without clicking the Save Changes button.
Changes are updated in the Extension Configuration screen and in the php.ini file the next time
the server is restarted.
Zend Server for IBM i
55
Note: Directives of extensions that are turned off can also be configured through the Extensions page.
Added extensions that are not part of the original Zend Server for IBM i list of extensions cannot
be configured on the Extensions page.
Zend Server 5 for IBM i Reference Manual
56
Working with Logs
The Logs page is a log viewer for developers to view log information directly from the
Administration Interface.
From this page you can:
View a Log
Filter log information
Navigate inside a log
Activate_'Auto_Refresh'
Advanced
Log_File_Permissions
Advanced users can also add logs to the list of logs to display in the "Log View" list.
View a Log
This procedure describes how to view a log file.
To view a log file:
1. Go to Monitor | Logs.
2. Select a log from the View Log list.
3. The log information is displayed in the main display area.
Use the Show option (located below the main display) to determine how many
lines to display. To use this option, enter a number between 5 and 200 and click Go to apply the
setting.
Zend Server for IBM i
57
Filter Log Information
This procedure describes how to filter a log file to fine tune the information to display specific
results.
To filter a log file:
1. Select a log to display.
2. Go to the Filter area and enter the text to use for the filter: You can use any text.
3. Click Refresh or Find.
The results are displayed in the main display area.
To run another query, change the text in the Filter area and click Refresh. There is no need to
display the complete log again.
Navigate Inside a Log
This procedure describes the different navigation options available for navigating inside a
selected log file.
Start - displays the first X lines of the log file.
Prev - shows the previous X lines of the log file.
Next - Shows the Next X lines of the log file.
End - displays the last X lines of the log file
'X' represents the number of lines that you specified in the Show option . The
default value is 20.
Activate 'Auto refresh'
The following procedure describes how to activate and deactivate the Auto refresh option. The
Auto refresh option sets the log information to display the most recent log entries in the last lines
of the log that is currently being viewed. Therefore, as the log changes over time, the content in
the view is always current. This feature provides an easy way to view errors in "almost real-time".
(Because the refresh rate is in seconds, there is at least a 3-5 second display lag, which is why
the Auto refresh feature is not considered true real-time logging.)
To activate Auto refresh:
1. Select a log to display.
2. Click the Auto refresh check box to automatically refresh the log information.
As long as the log is displayed, the information is refreshed. Each time you choose another log or
exit the page, the settings are reset.
Zend Server 5 for IBM i Reference Manual
58
Advanced - Add logs to the list of logs in the "Log View" list.
It is possible to add and display other logs that are specific to your environment in the Log Tail
page.
To add these other logs requires that you view and access backend application files which, in
normal circumstances, should not be changed. For this reason, we request that you perform this
task only if you clearly understand the instructions. If for some reason the system does not load
or malfunctions, please re-install Zend Server for IBM i .
Power users may edit the XML file in <install_path>/gui/application/data/logfiles.xml to add as
many logs as they may have.
To add log files to the list: 1. Open the file <install_path>/gui/application/data/logfiles.xml.
2. Add the name and location (full path) of the log files in the same format as the
existing files and save.
3. Restart your PHP.
Log File Permissions
When the message "Log file /usr/local/zend/var/log/error.log does not exist or missing read
permissions" appears:
Zend Server for IBM i does not have permissions to read the log file, or, the file does not exist. If
the file does exist, you will need to provide the 'zend' user permissions to access the directory
containing the file, and read the file itself.
One example of enabling Zend Server for IBM i to read the Apache error log on Debian Linux is
provided below:
To enable Zend Server for IBM i to read the Apache error log on Debian Linux: 1. Open a terminal and switch to root using "su" or "sudo -s".
2. Run the following command:
chmod 644 /usr/local/zend/var/log/error.log
Note On most Red Hat, Fedora and CentOS systems you will need to allow access to the Apache logs
directory too. This can be done by running the following command as root or using 'sudo': chmod
755 /var/log/httpd
Zend Server for IBM i
59
Zend Server 5 for IBM i Reference Manual
60
Working with Events To access this tab go to Monitor | Events.
An event is a collection of runtime-related information collected by Zend Server for IBM i . This
information is collected when an event is triggered, according to the Monitor component's rule
settings. An event indicates that something happened in your environment that exceeded your
definitions and the standards of how you want your PHP code to run.
From this page you can:
Find Events
View Event Details
Change an Event's Status
See Working with Monitoring to learn how to define which events you want Zend Server for
IBM i to generate and under which conditions.
Finding Events
By default, all events are displayed in the Events page (Monitor | Events). The filter option
allows you to reduce the number of events displayed in the Events table to easily locate specific
events. There are seven filtering categories for events:
Occurred Before... - Only show events that first happened before the specified date.
Occurred After... - Only show events that first happened after the specified date.
Rule Name - Only show rules of a specific type.
Occurred at.... - Filter to display the results for each server.
Severity - Filter to display Severe or Warning events.
Event Type - Filter by 'Event Type'.
Status - Show events by status: Open, Closed, Reopened or Ignored.
Zend Server for IBM i
61
Events can be filtered by one or more of the categories and in some cases several options can be
selected using the CTRL button to select multiple options, such as the Event Type filter.
The following procedure describes how to create a filter for events.
To filter events: 1. In the Events page, click "Show Filter Details".
A filter controller is added beneath the filter. To hide the filter controller, click
"Hide Filter Details".
2. Click the arrow to expand the list and select a filter from the list.
Each time a different filter is selected, an additional selection area will appear
above the "Add" list. You can add as many filters you like. Each time a filter is
selected, a new selection area is added.
3. To delete a specific filter option, click the delete button (X).
4. Set your preferences according to the filter type. For example, set a date range
for the Date filter.
5. When you have finished configuring the filter, click "Save" to name the filter and
save it for future use.
6. Click "Apply" to filter the content.
If you do not want to save the filter directly, click "Apply" without saving.
Only events matching the filter are displayed.
Use "Remove All" to reset the filter. Filter information is saved until the next login: You can safely
navigate to other pages and tabs without losing your filter settings.
Zend Server 5 for IBM i Reference Manual
62
Viewing Event Details
The following procedure describes how to open an event to view the event's details. Event Details
are the actual context of the event. Use these event details to locate information for root cause
analysis of the issue.
To open an event: 1. Go to Monitor | Events to display the Events page.
2. In the Events page, go to the Event table.
3. Locate an event that interests you (the filter option can be used to decrease the
number of events listed in the table).
4. Click on the event's ID number in the ID column.
The Event Details page opens.
Changing an Event's Status
This procedure describes how to change an event's status. The event status is used to handle
the information gathered by an event in a way that is similar to an issue tracking system. For
example, if you know that a certain problem has been solved, you can close the event or, if
several events of the same type are triggered, you can choose to ignore them.
The possible statuses are:
Open - The basic status of an event.
Closed - Closes the event (i.e., changes the event status to closed). If this event occurs
again, it is reopened .
Ignored - Ignores future instances of this event (i.e., changes the event status to ignore).
Therefore, a new event is not created if the same event occurs again.
Reopened - A closed event that was opened again because it reoccurred after the event
was closed.
Important: You can select events with different statuses and apply the same new status to them.
Zend Server for IBM i
63
To change an event's status:
1. In the Events page, select the relevant event/s from the events list.
2. Scroll down to the end of the page and select the relevant status from the Status
list .
3. Click Change Status to apply the changes.
The status of the selected event/s is changed. You can also change an event's status from inside
an event details page by using the "Change status..." controller at the bottom of the report.
Zend Server 5 for IBM i Reference Manual
64
Working with Event Details
To access this page, go to Monitor | Events and select an issue ID from the list.
This page shows aggregated details regarding the events that triggered a specific rule. The
details include audit trail information and options for investigating and resolving issues.
For a more detailed description of events and issues, see Monitor.
The actions in the issue details page can be divided into two categories:
Basic Tasks: Simple actions that can be applied to the page.
Advanced Tasks: Advanced actions for diagnosing and managing the content of the
issue.
Zend Server for IBM i
65
Basic Tasks
The following actions can be applied in an issue.
Return to the Events page.
To return to the Events page, click Return
Refresh an issue's details.
To refresh an issue, click Refresh
Detach an issue
Detaching an Issue
This procedure describes how to detach an issue. Detaching an issue is the process of opening
an issue in a new popup window. This feature can be used to display several events at the same
time.
To detach an event:
1. Go to Monitor | Events.
2. Select an issue from the table and open the issue (click on the event ID).
The event is displayed.
3. In the opened issue, click Detach .
The issue is opened in a new popup and the main page returns to the Events list.
Once an issue is detached, it cannot be re-attached. This process can be repeated to open
several issues at the same time.
Zend Server 5 for IBM i Reference Manual
66
Advanced Tasks
Issues contain different types of information and actions that allow you to detect the source and
drill down to investigate what caused a problem. In some cases (and depending on the type of
event that happened), the information also indicates the solution. For example, issue information
includes the exact line of code that has a problem and the nature of the problem.
Basic Details
The first layer of issue details are the basic details. These details are used to identify an issue
with high-level characteristics. Every issue includes the following basic details:
ID and Rule Name - The ID number is a unique identifier for a specific issue. The Rule
Name states the rule (defined in Rule Management | Monitoring) that triggered the
event. The ID number can be used to locate a specific issue using
in Monitor | Events . The Rule Name indicates the rule
that triggered the event: Several issues can be triggered by the same rule. Knowing the
rule name makes it easy to find the rule if you want to modify the rule settings (Rule Management | Monitoring | Edit).
Occurrence Info - An issue is a collection of aggregated events: This detail specifies
how many times this event occurred since the first time.
Status - The Status indicates the state of the issue. In some cases, the Status changes
automatically. The Status can be used to locate events in the Events page: Use a filter to
display the specific status.
Severity - Currently there are two severity levels, Critical and Warning. These levels
reflect your preferences, in terms of the importance of the event.
General Details
Each issue is an aggregation of one or more events with common, predefined characteristics.
These common characteristics are displayed in the General Details section. Therefore, you can
assume that each event that occurred for this issue has at least these details in common. This is
the first step in identifying the source of the event and understanding the circumstances
surrounding the event.
Zend Server for IBM i
67
Group Details
Grouping is yet another additional aggregation layer applied to an issue. Inside a single issue,
events are divided into groups according to the time they occurred. A new group is created only if
there was no activity for at least five minutes. If a new event occurs after five minutes have
passed, a new group is added to the issue.
Group Details show how many groups were created for an event, when a group was
created and how many events are in a group. When the event is also a relative or
quantitative event, an additional "Runtime" column is added to show the time it took to
perform the action. This helps you determine if there are differences in the event's
runtime, identify which events took longer and what else may have happened when the
event occurred (for example, did the event occur during a peak load, or during a DB
query, etc.).
Group Drilldown - Clicking on a group changes the contents of tabbed
display to show the details collected for that specific group of events.
Diagnostic Actions - These actions can be applied to each group to investigate what
caused the event. The diagnostic actions are Debug, Profile and Open File. All these
actions run on the server defined in . By default, the settings are set to
run diagnostic actions on the originating server (the server on which the event was
created). You can change the settings to run on a different server.
Note: When you use these actions, make sure that you have Zend Studio on the remote machine,
access to the remote server and that the remote server is an allowed host. For more details, see
Error: Failed to Communicate with Zend Studio.
Export
The Export option takes the Basic and General Details of a specific Group and generates an
XML file. Due to the extendable nature of XML, you can take this file and write a script that will
convert, import or display the information in any way you want.
Zend Server 5 for IBM i Reference Manual
68
Change Status
The Change Status option provides an easy way to manage issues. Issues that are assigned an
appropriate status can be efficiently filtered to control which issues to display in Monitor | Events.
The following summary describes what happens to issues when they are created and what
happens when new events are added to issues that have a changed status.
New events are created with the status New.
If the event status is Closed and a new issue occurs, the event status is changed to
Reopened.
If the event status is Ignored and a new issue occurs, the event status does not change.
However, the system continues to collect information about the event.
To change an issue's status:
1. Go to Events and select an issue from the list.
2. In the issue details page, scroll down to the bottom and use the drop-down list to
select a status.
Closed - Changing an issue's status to closed will close the issue until a new
event of that type occurs and then the issue will automatically be changed to
Open.
Open - Changing an issue's status to Open can be applied to issues that are in
status, closed or ignored.
Ignore - Changing an issue's status to Ignored will keep the same status even
when new events occur.
3. Click to apply changes.
The status in the basic details area and in Monitor | Events will be changed accordingly.
Zend Server for IBM i
69
Creating a Job
The Zend Server for IBM i Job Queue component provides the ability to off-load script execution
using Jobs. A Job is in essence a command to execute a PHP script according to the specific
parameters you give it. The Job Queue component manages the timing and execution of jobs in
the system.
Jobs can be created to facilitate a wide range of situations that require you to asynchronously run
PHP code. Here are a few examples:
Action Based Jobs for backend activities which are not a part of the HTTP request-
response interaction with end users and need to be executed asynchronously.
Scheduled Jobs that are set to execute according to a predefined schedule.
One-time jobs that need to be run for any reason.
Improving website performance by offloading processes to a different server.
Optimizing long script execution by deferring running scripts to low peak times.
Unifying script usage by referring to a job script outside the application code instead of
repeating the same code for the same functionality. This also provides the added
advantage of being able to implement changes throughout the application be editing a
single script (instead of editing each individual instance of the script throughout the
application's code).
Using the Job Queue from the Zend Server for IBM i Administration Interface
The Zend Server for IBM i administration interface provides tools for creating recurring jobs.
These jobs have a set schedule and will be run at specific times.
This procedure describes how to create a recurring job.
To create a recurring job:
1. In the administration Interface go to Rule Management | Recurring Jobs
2. Click to open the New Scheduling Rule page.
3. Enter the following rule related information:
a. URL - the path indicating to where the code is for the job to execute.
b. Name - Optional, a name describing the job
c. Application - Optional, the name of the application the job is related to.
This information can be used for grouping jobs.
4. Define when the job should run by using the time options (Hourly, Daily, Weekly
Zend Server 5 for IBM i Reference Manual
70
or Monthly). Selecting an option will change the parameters displayed. For
example selecting daily will display hour and minute options whereas, weekly will
display the days of the week.
When all the settings are properly defined, the "Create Rule" button will change
from Grey to Blue.
5. Click to save the changes.
As soon as the new Recurring Job is saved, it will be put in the Job Queue at the time specified in
the Rule.
To find out how the job ran go to Monitor | Jobs. To see what jobs are currently running go to Monitor | Queue Statistics. For additional information on handling jobs see Managing Jobs.
Note: The Jobs and Queues Statistics pages display information about all the Jobs in your system,
including Jobs triggered by the Job Queue API.
Working with The Job Queue API
The Job Queue API is a set of functions that allow you to create, define and manage the
execution of PHP code using a job.
There are three types of Jobs you can create with the Job Queue API
Queued Jobs - triggered as a direct result of an end-user activity
Recurring Jobs - usually defined by the system's programmer. They are usually related
to the system's maintenance and are not triggered by an action made by an end-user.
The most common existing system to handle such jobs is cron which is usually a part of
the operating system on most UNIX-like systems.
One-Time Deferred Tasks (jobs) - usually a result of an end-user interaction, and may
be deferred in order to optimize the system's load (e.g. cleanup or report generation
tasks may be pushed to off-hours) but may also be a part of the application's business
logic.
Zend Server for IBM i
71
Queued Jobs
This procedure describes how to create a Job that will be triggered as a result of end-user activity
using the Job Queue API.
To create a Job that will be triggered as a result of end-user activity:
1. Open your existing code.
2. Isolate the part of the code that should be executed as a job.
This code should be a viable script that performs some sort of action that can
be run at a later time without disturbing the general functionality (such as
sending an e-mail, confirming a credit card etc.).
3. Put the code into a file and name the file. The location and the name of the file
will become the value of the URL parameter therefor always provide descriptive
names and place job files in the same location.
4. In the original code, replace the code you removed with a call to the Job Queue
function createHttpJob.
5. In the function, pass additional GET parameters in the job's URL query string, to
handle different data.
6. Publish the fixed code to your webserver.
The next time the code is used the job will be triggered inside the code. To find out how the job
ran go to Monitor | Jobs. To see what jobs are currently running go to Monitor | Queue Statistics. For additional information on handling jobs see Managing Jobs.
Example: The following example shows how the original code looks like. How it will look like using
the Job Queue API, and what the new Job file looks like.
Before converting to a job: <?php function validate_credit_card_number($string) { if(preg_match('/^([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{2,4})$/', $string)) { return TRUE; } else { return FALSE; } } // here we call the function to validate the credit card validate_credit_card_number($_POST['credit_code']);
Zend Server 5 for IBM i Reference Manual
72
Instead of calling the function from inside the script we will create a job that will be
executed when we specify it to run. The script will be replaced wit a call to the Job Queue
API as follows:
The application script after modification: <?php $cc = $_POST['credit_card']; $q = new ZendJobQueue(); $ts = date('Y-m-d H:i:s', time()+10); $id=$q->createHttpJob('/jobs/validate_credit_card.php',array('credit_card'=>$cc),array('name'=>'Credit card validation using a single job execution scheduled to run after 10 seconds','schedule_time'=>$ts)); if(!$id){ exit(1);
The new job script: The job script: <?php function validate_credit_card_number($string) { if(preg_match('/^([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{4})[\-|\s]*([0-9]{2,4})$/', $string)) { return ZendJobQueue::setCurrentJobStatus(ZendJobQueue::OK); } else { return ZendJobQueue::setCurrentJobStatus(ZendJobQueue::FAILED); } } $params = ZendJobQueue::getCurrentJobParams(); validate_credit_card_number($params['credit_card']); ?>
Zend Server for IBM i
73
Working with Code Tracing
Code Tracing records execution activity in real-time. This provides an in-depth diagnostic tool that
will allow you to drill-down to the function level to view actual performance related information and
statistics.
In order to work with Code Tracing you first have to have the Code Tracing component installed
and activated (see the Installation Guide for information on adding components and to see
Working with Components for information on the components in your system).
Setting a Monitor Rule to Run a Code Trace
This procedure describes how to define monitor rule settings to in addition to the event related
information also collect trace information when the event is generated.
To set a monitor rule to save trace data:
1. Go to Rule Management | Monitoring.
2. Select a rule from the list.
3. Click Edit to open the rule for editing.
4. Scroll down the page to "Step 2: Event Action"
5. Select the one of the options and click .
The Tracing options are:
Save Trace Data - Generate a trace file each time the event is triggered.
Activate Trace Data Collection for... -Generate a trace file fora given time
frame each time an event is triggered.
6. Scroll to the bottom (or the top) of the page and click Save to save changes.
The next time the event is triggered trace information for that specific occurrence will be collected.
The trace information can be viewed in Monitor | Code Tracing or directly from the event (see
important note below).
Important Note: A single issue can contain aggregated information about more than one instance of an
occurrence. This information is also grouped according to when the event occurred. When Code
Trace information is collected it is collected for a specific time and therefore will be associated to
a specific group inside the event for more information see "Viewing Trace information Inside an
Event".
Zend Server 5 for IBM i Reference Manual
74
Manually Triggering a URL Trace
This procedure describes how to manually run a code tracing on a specific URL. Running a code
trace on a specific URL will capture the current activity at the time the trace was triggered.
To manually trigger code tracing on a specific URL:
1. Go to Monitor | Code Tracing.
2. Enter the URL in into the "Trace URL field and click
The URL has to be running on the Server running Zend Server for IBM i .
The trace information will be collected and added to the list in the Code Tracing page.
Running Code Tracing on Another Machine
You can run Code Tracing on another machine as long as the Zend Code Trace component is
installed and running on it. However, when running a trace on a remote machine the trace
information is collected on that machine therefore, Instead of running the trace from a remote
machine always run a trace on the specific machine you need. If you do want to run a trace on a
remote server after all, make sure that the server's IP is an allowed host in Server Setup | Debugger.
Viewing Trace Information
There are two ways to view trace information according to how the trace was generated.
Manually generated traces can be viewed in the Code Tracing page Monitor | Code Trace.
Traces that were generated alongside an event can be viewed in the Code Tracing page Monitor | Code Trace and also from the issue's details.
Viewing Trace Information Inside an Event
This procedure describes how to view trace information that was collected at the time a monitor
event was triggered.
Trace information for a monitor event is only collected if the specific event was defined to trigger a
code trace.
To view trace information inside an event: 1. Go to Monitor | Events:
2. Select an event from the list by clicking on the event's ID.
The Issue Details page will be displayed.
Zend Server for IBM i
75
3. In the occurrences section, navigate to the time that the trace was supposed to
run. clicking on that group will add an additional "View Trace" button tot he
display. Clicking on it will open the Code Tracing view where you will be able to
see the trace information.
See Code Tracing Tree and Code Tracing Statistics for more information about the Zend Code
Tracing view.
Viewing all Trace Information
This procedure describes how to view trace information for traces that were triggered manually or
by an event.
The Code tracing view is populated after trace information has been collected either from an
event or manually.
To view trace information:
1. Go to Monitor | Code Tracing.
2. Select a trace from the list by clicking on the trace's ID.
The Code Tracing view will open in a new window.
Use the Code Tracing Tree and Code Tracing Statistics tabs to navigate through the information.
Deleting Trace Information
This procedure describes how to delete trace information.
1. Go to Monitor | Code Tracing.
2. Select a trace or multiple traces from the list by clicking the trace's check box.
3. scroll to the bottom of the page and click delete.
The trace information will be permanently deleted. New trace information for the same URL will
continue to be recreated as long as the setting in the rule is not changed. To change the rule's
settings see "Setting a Monitor Rule to Run a Code Trace".
Zend Server 5 for IBM i Reference Manual
76
Working with the Debugger The Debugger API that is included in Zend Server for IBM i is a remote debugging tool for
developers who work with Zend Studio. If the Debugger Component is not set to "On" in the
Components page, you are not able to run remote debug sessions using Zend Studio. For more
information on turning the Debugger Component to "On", see Working with Components.
From the Zend Server for IBM i perspective, other than defining allowed hosts and denied hosts,
no additional interaction is required.
The following procedure describes how to define allowed hosts for debugging. Users define
allowed hosts to create a list of IP addresses (of computers that run Zend Studio) that have
permission to debug the PHP code that runs on the server.
To define allowed hosts for debugging:
1. In the Administration Interface go to Server Setup | Debugger. 2. In the "Allowed Zend Studio Clients for Debugging" section, enter a valid IP
address or use Wildcards (*) to specify a range of IPs.
3. From the drop-down list, select an option according to the type of IP address you
entered. Click 'Exact IP address only' for a single IP, or one of the other options
to represent a range of hosts.
4. Click to add the Host.
5. The changes are applied after you restart the Server
The IP or range of IPs is allowed to connect to the server to debug PHP code with Zend Studio .
To remove a specific IP from the list, click "Remove".
Important Note:
If your machine has several IP addresses (for example if you are using a wireless network
connection on a laptop) verify that you have defined all the possible IP addresses as "Allowed
Hosts for Debugging" or that the IP you want to use is first in the list of IPs in Zend Studio for
Eclipse. (In Window | Preferences | PHP | Debug | Installed Debuggers, verify that Zend
Debugger is selected and click Configure in the Client Host/IP field.)
Zend Server for IBM i
77
The following procedure describes how to define denied hosts for debugging. Users define
denied hosts to create a list of IP addresses (of computers that run Zend Studio) that do not have
permission to debug the PHP code that runs on this server.
To define denied hosts for debugging:
1. In the Administration Interface go to Server Setup | Debugger. 2. In the "Denied Zend Studio Clients for Debugging" section, enter a valid IP
address or use Wildcards (*) to specify a range of IPs.
3. From the drop-down list, select an option according to the type of IP address you
entered. Click 'Exact IP address only' for a single IP, or one of the other options
to represent a range of hosts.
4. Click to add the host.
5. The changes are applied after you restart the Server .
The IP or range of IPs is denied permission to connect to the server to debug PHP code with
Zend Studio.
To remove a specific IP from the list, click "Remove".
Note: Do not add the same IP address to both the Allowed and Denied host lists. Pay attention when
you specify a range of IP addresses: If you deny a range of addresses that includes an IP that
was specified in the Allowed hosts, the host is not allowed to create a debug session.
Wildcards (Net Mask)
Wildcards use the asterisk (*) to define a string of IP addresses and to specify a range of IPs that
are either allowed or denied hosts. This option makes it possible to specify a range of IPs from 0-
255, according to the selected number of wildcards. For example, if you use the Net Mask option
to deny the IPs 10.1.3. *, all the IP addresses beginning with 10.1.3. are denied access to the
Studio Server (i.e., integration with Studio is not permitted for these IP addresses).
Zend Server 5 for IBM i Reference Manual
78
Working with the Zend 5250 Bridge The Zend 5250 Bridge provides two different methods for Web-enabling your PHP applications:
1. Zend 5250 Emulator - Takes the back-end logic of your 5250 application and displays it in a
browser format. This is achieved without any work from the developer.
2. Zend 5250 Bridge API - A set of API functions which allow you to use the input and output
data in your 5250 application to construct a PHP application which allows complete flexibility
and customization options.
Which Method Should you Choose?
The method you choose will depend on the amount of time you want to invest in the process, the
programming knowledge and skills that you or your programmers possess, and the amount of
extra customization and functionality that you would like to add to your application:
Zend 5250 Emulator
Use the Zend 5250 Emulator if you:
Need to give users browser access to your 5250 applications and want to invest a
minimum amount of development time.
Want to reduce emulator application deployment costs (licences/time).
Want to make small cosmetic changes (colors etc.) to your screens.
Do not know PHP or JavaScript (though a basic knowledge of HTML/CSS is useful if you
want to customize the 'look' of your screens.)
Want to test the capabilities of the Bridge.
Plan to frequently change your 5250 Display Files.
Zend Server for IBM i
79
5250 Bridge API
Use the Zend 5250 Bridge API if you:
Want to make presentation-level changes as well as applying additional display logic
Want to apply complete display-side customization to all or individual screens.
Want to combine several screens into a new view.
Want to remove or filter out content/data for a subset of end-users (e.g. redundant fields).
Have a good knowledge of PHP/HTML/CSS/JavaScript (recommended).
Expect to continue significant development of your RPG 5250 applications and want to
minimize Parallel Maintenance considerations.
Want to pipeline the data coming from the bridge for usage in other, non browser
applications (Java, Web Services, others.)
For more information on working with the Zend 5250 Bridge see Zend 5250 Bridge Introduction.
Zend Server 5 for IBM i Reference Manual
80
Working with Components The Components page provides a convenient way to view and configure the Zend Components
installed in your environment.
Use this page to control and configure components loaded in your environment.
Changing Component Status
To change a component's status: 1. Go to Server Setup | Components.
2. Select a component and click the On switch in the component's status column.
After changing the component's status, a message appears, prompting you to
click the Restart Server button at the bottom of the screen .
More than one component can be loaded or unloaded before you click Restart
Server . All the changes made prior to restarting the PHP are applied when the
server restarts.
Even if you navigate to other tabs, the changes are kept and are applied when
the server restarts.
Changes are updated in the Components page and in your php.ini file. Changes are also applied
when you manually restart your Web Server.
Configuring Directives Associated with Components
To configure a directive associated with a component: 1. Go to Server Setup | Components.
2. If the component has directives that can be configured, a link appears in the
directives column.
Clicking the link opens the Directives page with the relevant directives already
filtered.
3. Configure the directive as required.
You can configure multiple directives before you save your changes.
4. Click the Save Changes button to save your changes. To
discard changes, leave the screen without clicking Save Changes.
Zend Server for IBM i
81
Changes will be updated in the Components page and in your php.ini file the next time the server
restarts.
Note: Directives of both loaded and unloaded components can be configured through the Components
page.
Actions
Actions are additional activities that can be applied to a certain component when necessary.
The actions are as follows:
Clear - Clears all cached information (Data Caching and Optimizer+ bytecode caching).
Manage - Directs the user to an additional page inside the Administration Interface to
manage and fine-tune a component. The basic definitions that are defined by directives
are set by clicking Configure.
Restart - Server-based components can be restarted using this action (for example the
Java Bridge).
Adding New Components
The installation process determines which components are installed in your environment.
Depending on your operating system, you can choose to customize your installation (Windows) or
to work with a basic set of components that you can add to later on (DEB, RPM).
In this case no additional installation is required but only configuration change.
For installation specific instructions on how to add additional components, see Choosing Which
Distribution to Install and click on your installation type for instructions.
Zend Server 5 for IBM i Reference Manual
82
Working with Directives This tab is accessed from Server Setup| Directives
The initial display shows the most commonly used directives. Click "All" for the full list of
directives or use the "Search" component to locate a specific directive.
Users are also directed to this page from the Extensions and Components pages when they click
"Configure" for an extension or a component that has directives which can be configured.
To configure directives: 1. Expand one of the lists, use the Search/All or the popular options to locate the
relevant directive.
2. Configure the directive as required.
You can configure multiple directives before saving.
3. Click the Save Changes button at the top right corner of the
screen to save all the changes made or leave the page without saving to discard the
changes
4. As soon as changes are made to this page, a prompt to Restart Server is displayed.
5. Click .
The changes are updated in the Directives page and in your php.ini file.
Zend Server for IBM i
83
Working with Optimizer+ The Optimizer+ runs out-of-the-box (by default, after installation). Optimizer+ allows you to gain a
performance boost by reducing code compilation time. When PHP code is compiled for the first
time, it is saved in the server’s memory. Each time the code is called, the pre-compiled version is
used instead of waiting for the code to compile, which causes a delay each time the code is used.
Note: Using the Optimizer+ should not be confused with caching. The Optimizer+ saves a compiled
script to the server 's memory, while Caching saves the script’s output to the server’s memory.
The general recommendation is to always keep the Optimizer+ set to 'On' to boost Web
application performance.
When Not to use Optimizer+ (Blacklist)? There are some instances where it is preferable not to store PHP byte-code for certain PHP files.
To do so, you can make a list (a blacklist) of file names that you want the Optimizer+ to ignore or
increase the Optimizer+ resource allocation.
Files and directives should be blacklisted under the following conditions:
Directories that contain files that are larger than the allocated memory defined in:
zend_optimizerplus.memory_consumption or or that contain more files than the allocated
quantity of files, as defined in zend_optimizerplus.max_accelerated_files.
Large files that have high memory consumption - If you have exhausted all your allocated
memory, select the largest and slowest scripts blacklist them.
Files that have long execution times (makes the compilation save irrelevant).
Code that is modified on the fly (e.g., auto-generated template files).
Zend Server 5 for IBM i Reference Manual
84
Increasing Optimizer+ Resource Allocation
The following procedure describes how to change Optimizer+ resource allocation. This procedure
is used as an alternative to blacklisting files and should be tried first, before adding a file to a
blacklist (unless the file meets one of the criteria above). Optimizer+ settings can be changed to
increase allocated memory and the maximum quantity of files. This alternative depends on the
amount of memory available to allocate to the Accelerator.
Memory allocation can only be increased when the Optimizer+ is set to 'On'.
To increase the Optimizer+ memory allocation: 1. Go to Server Setup | Components and verify that the "Zend Optimizer+"
component is set to 'On'.
2. Click the "Configure" link in the directives column to display the list of Optimizer+
directives.
3. Locate the directive: zend_optimizerplus.memory_consumption and increase the
value according to your system's memory allocation abilities.
To increase the quantity of files: 1. Go to Server Setup | Components and verify that the "Zend Optimizer+"
component is set to 'On'.
2. Click the "Configure" link in the directives column to display the list of Optimizer+
directives.
3. Locate the directive: zend_optimizerplus.max_accelerated_files and increase the
value according to your system's memory allocation abilities.
If the memory fills up quickly (especially if there are only a few files), increase the memory
allocation or blacklist the file. Files which exceed the allocated memory or file quantity are not
accelerated.
Zend Server for IBM i
85
Blacklisting Files
If none of the alternatives (described above) are suitable, or if the file meets one of the criteria for
blacklisting a file, use the following procedure to create a blacklist file that contains the file names
of the files you do not want to be byte-code cached by Optimizer+.
To create a blacklist file:
1. Create a .txt file using a text editor.
2. Write a list of the file names to blacklist (i.e., ignored by the Optimizer+).
List each file name in a new line.
3. In Server Setup | Components, verify that the "Zend Optimizer+" component is
set to 'On'.
4. Click the "Configure" link in the directives column to display the list of Optimizer+
directives.
5. Locate the directive: zend_optimizerplus.blacklist_filename and specify the full
path to the file location.
The files in the blacklist are now ignored by Optimizer+.
Optimizer+ Duplicate Functions Fix
In situations where certain functions were (or were not) defined, some PHP code produces
different opcodes, depending on the circumstances. This causes a discrepancy for the
Optimizer+ in the situation where the Optimizer+ caches one version, and a sequence of events
arises that requires a different function. If the discrepancy is not addressed, the script stops
working and raises a "duplicate functions" error.
To maintain proper performance in these and similar situations, activate the
zend_optimizerplus.dups_fix parameter. This parameter shuts down the Optimizer+ duplicate
function check to prevent these errors from occurring.
This parameter can be defined in Server Setup | Directives by searching for
zend_optimizerplus.dups_fix.
Zend Server 5 for IBM i Reference Manual
86
Working with Zend Guard Loader The Zend Guard Loader is a PHP extension that is used to run code that was encoded or
obfuscated using Zend Guard. If you chose to install this component, it is set to run by default,
out-of-the-box.
To locate your installation package and verify if the component was installed by default or needs
to be installed, see the Installation Guide, Choosing Which Distribution to Install.
PHP code that was either encoded or obfuscated using the Zend Guard, or which is license
restricted will only work if the
Zend Guard Loader component is set to 'On'.
The Zend Guard Loader component can be set to 'On' or 'Off" from Server Setup | Components.
Note: If you do not require the Zend Guard component for optimal performance, either do not install it,
or set this component to 'Off'.
Zend Server for IBM i
87
Working with Data Cache
The Data Cache API is used the same way as any other API: By inserting the API functions into
your PHP code. The Data Cache component uses an API to cache partial PHP outputs using
memory or disk.
The Data Cache API includes the following functionality:
Storing variables to the Cache
Fetching variables from the Cache
Deleting variables from the Cache
Clearing the Cache
Disk/memory (SHM) storage
Caching using namespaces
Cache folder depth configuration
Disk/Shared-Memory Caching
This feature provides options to determine where to store cached variables. Memory caching
improves server responsiveness and increases performance - primarily in environments that run
high-traffic applications that can benefit from off loading activity directed toward their hard disk.
Disk caching is more suitable for smaller applications and ensures the cached content is available
after the machine is restarted.
SHM/disk storage is implemented by using the appropriate API functions and configuring the
Data Cache directives.
Note: Memory option error messages have been created to notify you if the store operation fails or you
run out of allocated memory.
Zend Server 5 for IBM i Reference Manual
88
The following example shows the different storage options:
Example: A simple key with no namespace stored on disk if (zend_disk_cache_store("hello1", 1) === false){ echo "error2\n"; exit(); } Shared memory: if (zend_shm_cache_store("hello1", 1) === false){ echo "error2\n"; exit(); } Store with namespace on disk if (zend_disk_cache_store("ns1::hello1", 1) === false){ echo "error2\n"; exit(); } Shared memory: if (zend_shm_cache_store("ns1::hello1", 1) === false){ echo "error2\n"; exit(); } Store with namespace on disk with limited lifetime (3) if (zend_disk_cache_store("ns3::test_ttl", 2, 3) === false){ echo "error12\n"; exit(); } Shared memory: if (zend_shm_cache_store("ns3::test_ttl", 2, 3) === false){ echo "error12\n"; exit(); }
'namespace' Support
Using namespaces for caching provides the ability to define a key that can serve as an identifier
to delete select items from the cache, rather than unnecessarily removing shared instances.
'namespace' support is intended for environments that run large applications that are separated
into modules. Applying a 'namespace' to each module provides the identification necessary to
pinpoint all the cached items that belong to a given module and remove only those specific items.
This does not mean that you must use the 'namespaces' to clear the cache: The entire cache can
be cleared by using the 'output_cache_remove' function.
Setting the cached 'namespace':
The cache 'namespace' is set by adding it as a prefix to the cache with '::' as the separator.
Example: This example shows how to manipulate variable caching using a 'namespace'
zend_disk_cache_store("my_namespace::my_key",$data) is fetched with
zend_disk_cache_fetch("my_namespace::my_key");
zend_shm_cache_clear("my_namespace") clears all the keys that start with
"my_namespace::"
Zend Server for IBM i
89
Cache Folder Depth Configuration
Defining the Cache folder depth is intended for environments that use a large number of keys. By
definition, cached content is separated into different directories by key, to prevent performance
degradation caused by accessing files that contain large amounts of content. This option is only
available with disk caching. Increase the cache folder depth according to the quantity of content
that requires caching (small amount = 0, large quantities = 2).
Note:
A single directory may include several keys, depending on the quantity of cached content.
The cache folder depth is defined by the directive zend_cache.disk.dir_levels. The value of the
directive configures how the cached files are stored. The accepted values for this directive are 0,
1 or 2, where:
0 = one directory containing all the cache files
1 = a separate directory under the cache directory
2 = an additional sub directory for cached content under the cache directory
Zend Server 5 for IBM i Reference Manual
90
Working with Java Bridge
The Java Bridge is only active when the Java Bridge component is installed and activated (see
the Installation Guide). The component's status and settings can be viewed and configured in the
Administration Interface, from Server Setup | Components.
Note: The Java Bridge requires that you have Sun Microsystems JRE 1.4 (or later) or IBM Java 1.4.2
(or later) installed on your computer. During or after installing (depending on the installation type),
you are prompted to direct the installer to the JRE location. Therefore, you should already have
JRE installed. 64-bit JRE is not supported.
More information about JREs and the latest updates can be obtained from the SUN Microsystems
Website.
Configuration
This procedure describes how to configure the target Java runtime environment.
Configuring the runtime environment: Use the following command to run JavaMW: java com.zend.javamw.JavaServer For correct execution, the classpath should include the javamw.jar file in the directory
where JavaMW is installed.
Example: UNIX, Linux, IBM i Windows <install_dir>\bin\javamw.jar
Zend Server for IBM i
91
Testing the Bridge Connection
The following code sample shows how you can, as an initial step, test the connection between
your PHP and Java environments to ensure that the Java Bridge is defined properly and
communicates with the correct Java. This code demonstrates the interaction between a PHP
application and Java objects that occurs in the Java Bridge implementation.
To test the Java Bridge connection:
Create a new PHP script to create a Java object, as in the example below: <?php // create Java object $formatter = new Java("java.text.SimpleDateFormat", "EEEE, MMMM dd, yyyy 'at' h:mm:ss a zzzz"); // Print date through the object print $formatter->format(new Java("java.util.Date"))."\n"; // You can also access Java system classes $system = new Java("java.lang.System"); print $system."\n"; // will use toString in PHP5 print "Java version=".$system->getProperty("java.version")." <br>\n"; print "Java vendor=".$system->getProperty("java.vendor")." <p>\n\n"; print "OS=".$system->getProperty("os.name")." ". $system->getProperty("os.version")." on ". $system->getProperty("os.arch")." <br>\n"; ?> If the Java Bridge is correctly installed and running, you should receive the following
response: Friday, June 13, 2008 at 8:45:57 PM U.S Daylight Time class java.lang.System Java version=1.6.0_06 Java vendor=Sun Microsystems Inc. OS=Linux 2.6.25.3-18.fc9.i686 on i386 This output shows the date, Java version, vendor and operating system and indicates
that the connection is complete.
If you receive an error message instead of the expected output information, one of the
following problems may have occurred:
1. The Java Bridge is not installed
2. The Java Bridge extension is not running (Server Setup | Components)
3. The Java Bridge Server needs to be restarted (Server Setup | Components)
4. The requested .jar file does not appear in the environment's classpath.
Once the connection is established, you can start using the API to call Java objects from your
PHP.
Zend Server 5 for IBM i Reference Manual
92
Before using the Java Bridge API
Before you start incorporating the Java Bridge API in your code, you must be aware that when
you call Java from PHP, you must use Java coding standards to call the correct objects, because
the Java Bridge does not perform dynamic data conversion. You must perform the type
conversion in your PHP code.
For example,
Example: If you call a Java method that looks like this: public void doSomething(int i); Using what you would expect to work in PHP: $var = "1" $javaObject->doSomething($var); The Java Bridge throws an exception. To avoid this, use the following line of code to
convert the parameter from a string to a numeric value before the Java Bridge passes it: $javaObject->doSomething($var + 0);
For more information, see the API, or Java Bridge Use Cases.
Zend Server for IBM i
93
Working with Local Debugging Local debugging occurs when your entire environment (Zend Studio for Eclipse, Debugger and
Zend Server for IBM i ) is located on a single machine.
When working with an IDE such as Zend Studio for Eclipse, your project files are, in most cases,
placed in a location that you have defined. To run the files on the Web Server, you must first
move the files to the Web Server's document management directory called "htdocs".
Zend Server 5 for IBM i Reference Manual
94
Working with Monitoring To access the Monitoring page, go to Rule Management | Monitoring.
This page is the central management area for defining the conditions by which events are
generated (as displayed in Monitor | Events).
Creating Events
Event generation is an out-of-the-box feature. On installation, the Monitor component begins to
collect and report information about events, according to the Monitor's default settings. The
resulting events are displayed in Monitor | Events. To further enhance monitoring
effectiveness, event thresholds can be customized. In a similar manner, thresholds can be
gradually modified to not only reflect improvements in performance, but also to verify that
problematic issues have been resolved.
Configuring Events
Events can be configured according to each environment’s specific requirements. The main
configuration changes that should be performed relate to tuning rule values and defining a list of
functions and PHP errors to monitor.
The following procedure describes how to configure event rules
To configure event rules: 1. Go to Rule Management | Monitoring.
2. Select a rule from the list. Hovering over the information icon displays a
description of the selected event and the event’s parameters.
3. Click Edit to change the default settings according to your requirements.
Each event type has different configuration options suited to the nature of the
event.
4. Scroll to the bottom of the page and click Save to save changes.
The new settings are applied after you click Restart PHP.
To return to the main Monitoring page, click Cancel, Save or use your browser's Back button.
See Edit Rule (Monitoring) for more information about rule settings.
Zend Server for IBM i
95
Disabling Event Rules In some cases, there may be events that are either not applicable to your system or unnecessary.
Events are disabled from the Monitor page. When an event is disabled, the event is not monitored
and information is not stored for the event.
To disable event rules: 1. Go to Rule Management | Monitoring.
2. Select a rule from the list. Hovering over the information icon displays a
description of the selected event and the event’s parameters.
3. Click Disable to stop the Monitor from collecting and reporting information
relevant to this event type.
This event type is no longer monitored.
Zend Server 5 for IBM i Reference Manual
96
Working with Caching To access the Caching page, go to Rule Management | Caching.
The Page Cache is used to speed-up recurring executions of PHP scripts in your application. This
is achieved by caching the PHP output (HTML) for specific URLs on first execution, to reuse the
cached data for subsequent calls.
Cache behavior is defined using a flexible rule system that allows you to maintain the dynamic
capabilities of your applications.
As opposed to other caching alternatives (Zend Server for IBM i Data Cache and Zend
Framework Zend Cache), the Zend Server for IBM i Cache does not require any code changes
and can be easily applied to existing applications. Moreover, while other caching solutions still run
some code on recurring executions, the cache does not run any code to display the cached
content, which results in improved performance.
Creating URL cache rules with Zend Server for IBM i is a two-step process. In step one, you
define the basic URL and conditions to apply. In step two, you define the cache duration and
output options.
The following procedure describes how to create a cache rule.
To create a Cache rule:
1. Go to Rule Management | Caching
2. Click to open the New Rule page.
3. Name the rule.
Make sure the name is descriptive and easy to remember: This name is what will
appear in the main Caching page.
4. Enter the information according to the following steps and click Save to apply the
changes:
Zend Server for IBM i
97
Step 1: Caching Conditions
1. Use the fields to define the URL that you want to cache.
A URL can be an exact URL or a representation of a pattern of URLs using
Regular Expressions, which can be either case sensitive or case insensitive.
Example: Exact URL
This representation sets the Page Cache to cache the URL
http://www.zend.com/index only.
URL pattern using Regular Expressions
Note: Using regular expressions consumes more time and CPU than using exact
URLs.
This example sets the Page Cache to cache the following:
Matches regex - Any URL that matches this pattern is cached.
Scheme - Only URLs that begin with 'http' are cached (the
alternatives are 'https or 'either').
Host - The host name and port part (optional) of the URL. By using a
regular expression, you can specify whether to cache URLs that begin
(or do not begin) with "www". For example: (www\.)? - Indicates that the URL may or may not
begin with 'www.\'.
Path - the path and query part of the URL. For example: /.* - Indicates that any string after the host name
'zend.com/articles/' is acceptable. To be precise, it represents 0 or
more of any character.
2. Click to create additional caching rules based on
HTTP requests and session parameters.
There is no limit to the amount of conditions that can be added.
Zend Server 5 for IBM i Reference Manual
98
Example: How can we configure the system to use only cached content when a user is not logged in? Usage Scenario: Websites (portals, news sites, forums...) that provide different content to premium users and non-registered users.
Assuming that the _SESSION 'username' parameter is used to store the
name of a currently logged in user, create a rule based on this parameter,
as follows:
This sets the Page Cache to cache content only when the _SESSION
parameter 'username' is not set. Subsequently, users that do have the
_SESSION 'username' set are presented with a live version of the page.
If necessary, we can extend this limit to include all users whose 'username'
_SESSION parameter equals 'guest' as follows:
Note: Square brackets are not required for non-nested variables when referring to
superglobal variables in caching conditions . If you do not use square brackets, the
system adds them automatically after you click "Save".
3. Use the match options to define if you want to cache only if all of the
conditions are met ("Match all of the above") or if any one of the
conditions is met ("Match any of the above").
If you use the option "Match any of the above", the pages are cached
both when the parameter 'username' does not exist or if it equals 'guest'.
If you use the option "Match all of the above", the pages are cached either
when the parameter 'username' does not exist or when it equals 'guest'.
This completes Step 1 of creating a Page Cache Rule.
Zend Server for IBM i
99
Step 2: Cache Output
1. Set the cache duration in seconds. After that time, the cache is refreshed and a
newer version is created.
For example, 600 seconds is ten minutes.
2. Choose to create compressed cache copies.
This option allows you to disable the creation of a gzip-compressed version of
each cached page, as long as it is larger than 1KB. You should normally leave this
option checked.
By default, Zend Server for IBM i creates a compressed version of each cached
page and stores it alongside the original version. This compressed version is sent
to browsers that support gzip compression (all modern browsers support this)
instead of the uncompressed version. For typical HTML, XML or other text-based
outputs, using the compressed version can save about 90% of the bandwidth and
improve page load times. In addition, the compressed copy is saved in your cache
so the CPU-intensive process of real-time compression is not required. However,
if you are caching a PHP script that outputs binary data (for example JPEG or
PNG images, ZIP or EXE files, PDFs, etc.) which cannot be further compressed,
you should un-check this option to avoid redundant processing. For more
information, see: Page Cache.
3. Click to create different cached copies according to specific values.
This creates more than one version of the page in the cache, based on specific
conditions.
Example: The following example demonstrates how to create different copies of cached
information, based on the _GET parameter 'language'.
This sets Caching to create a different copy for each different value of _GET
'language' (for the content that was cached based on the rules defined in steps
1 and 2).
This example demonstrates how to use Caching for multilingual pages that
handle the same content in different languages.
This completes the last step of creating a Cache Rule.
Scroll to the bottom of the page (Rule Management | Caching) and click "Save" to save the rule
information and "Restart PHP" to activate the rule.
To edit a rule, go to Rule Management | Caching and click Edit next to the rule you want to edit.
Zend Server 5 for IBM i Reference Manual
100
To clear the information in the cache for a specific rule, go to Rule Management | Caching and
click Clear next to the rule you want to edit.
Zend Server for IBM i
101
Components Zend Server for IBM i is comprised of several components that each contribute important
functionality to facilitate the development process.
The components are:
Debugger - The Zend Debugger communicates with the Zend (PHP) Engine to retrieve
runtime information and present it in Zend Studio for root cause analysis.
Optimizer+ - The Zend Optimizer+ component speeds up PHP execution via opcode
caching and optimization.
Guard Loader - The Zend Guard Loader is used in order to run PHP scripts that are
encoded with Zend Guard.
Data Cache - The Zend Data Cache component provides a set of PHP functions to
improve performance, by storing data in the cache.
Java Bridge - The Zend Java Bridge component makes it possible to use Java classes
and code from within PHP.
Zend 5250 Bridge - The Zend 5250 Bridge component makes it possible to use the 5250
Bridge on Zend Server for IBM i.
Zend Framework - An open source framework for developing Web applications and Web
services with PHP.
Monitor - The Zend Monitor component is integrated into the runtime environment and
serves as an alerting and collection mechanism for early detection of PHP script
problems.
Page Cache - The Zend Page Cache component is used to cache the entire output of
PHP scripts, without changing the PHP code.
Job Queue Component - The Jobs Component is used to streamline offline processing of
PHP scripts.
Zend Code Tracing - Code Tracing enables real-time execution flow recording in
Production Environments.
Click on a link to view a full description of the components architecture. To see how to work with a
component, select a topic that begins with "Working with..." from the Tasks section. For a short
description of each component and where it is installed, see the Installed Components section in
the Installation Guide.
Zend Server 5 for IBM i Reference Manual
102
Debugger The Zend Debugger component enables remote debugging of PHP scripts with Zend Studio.
The Zend Debugger communicates with the Zend (PHP) Engine to retrieve runtime information
and present it in Zend Studio for root cause analysis purposes.
Note: If your machine has multiple IP addresses, make sure you define all the IPs as allowed hosts in
Zend Server for IBM i.
The Zend Debugger API communicates with the Zend (PHP) engine to reveal PHP runtime
information such as variables, call stack and environment information. This information is then
displayed and set up in Zend Studio to enable server side debugging, profiling and code
coverage.
Zend Server for IBM i
103
Optimizer+ The Zend Optimizer+ component speeds up PHP execution through opcode caching and
optimization.
The Zend Optimizer+ improves PHP performance by storing precompiled script bytecode in the
shared memory. This eliminates the stages of reading code from the disk and compiling it on
future access. For further performance improvement, the stored bytecode is optimized for faster
execution. This component works out-of-the-box and therefore does not require any configuration
or changes to your code.
The Zend Optimizer+ speeds up PHP execution and increases server performance, resulting in
better Web application performance.
This component is intended for PHP developers who run complex PHP applications and can
benefit from bytecode caching (which is especially helpful for working with Zend Framework).
Note: The Optimizer+ works exclusively with Apache or FastCGI environments (no CLI or CGI support).
Zend Server 5 for IBM i Reference Manual
104
Guard Loader The Zend Guard Loader runs PHP scripts that are encoded with Zend Guard.
The Zend Guard Loader runs outputs created by a separate product available from Zend, which
provides an easy way to encode, obfuscate and license PHP code via an Eclipse-based interface
or from the command line.
The Guard Loader must be installed on each Web server that runs files that were encoded with,
or use, Zend Guard licenses.
The Zend Guard Loader translates encoded files to a format that can be parsed by the Zend
Engine. This runtime process uses the Zend engine as a trigger to start the Zend Guard Loader
component.
Zend Guard
Zend Guard is a separate product available from Zend that provides an easy way to encode,
obfuscate and license PHP code via an Eclipse-based interface or from the command line.
To view the API, click Zend Guard Loader.
For additional information on using Zend Guard, see the Zend Guard User Guide, available online
from http://files.zend.com/help/Zend-Guard/zend-guard.htm
Zend Server for IBM i
105
Data Cache The Zend Data Cache component provides a set of PHP functions to improve performance by
storing data in the cache.
The Zend Data Cache is used to cache different types of data (e.g., strings, arrays and objects),
as well as script output or script output elements for various durations. Items can be stored in
shared memory (SHM) or to disk. Namespaces are supported, to group cached objects for easy
management.
Data Caching is primarily used when it is impractical or impossible to cache the entire page
output, such as when sections of the script are fully dynamic, or when the conditions for caching
the script are too numerous. An example of this kind of usage is when some of the output is a
form: The data may include credit card numbers, addresses and other kinds of information that
should not be cached, for security reasons. For more information, see Working with the Data
Cache.
The Data Cache API includes the following functionality :
Storing variables to the cache
Fetching variables to the cache
Deleting variables from the cache
Clearing the cache
Disk/memory (SHM) storage
Caching using namespaces
Cache folder depth configuration
Zend Server 5 for IBM i Reference Manual
106
Java Bridge The Zend Java Bridge provides PHP developers with a way to use existing Java code and build
PHP applications that use Java code.
The Java Bridge integrates Java code in PHP by connecting the PHP object system with the Java
Bridge object system.
Note: The Java Bridge requires that you have SUN Microsystems JRE 1.4 (or later) or IBM's Java 1.4.2
(or later) installed on your computer.
During (or after ) installing, (depending on the installation type, you are prompted to direct the
installer to the JRE location. You should, therefore, already have JRE installed. 64-bit JRE is not
supported.
More information about JRE and the latest updates can be obtained from SUN Microsystems’s
website.
The Java Bridge PHP extension adds functions that allow you to instantiate new Java classes
from inside your PHP script. Once a Java class is instantiated, the Java Bridge gets a message
from the Zend Engine to execute the Java code. The Java Bridge executes the script and returns
the results to the Zend Engine.
Zend Server for IBM i includes the Java Bridge PHP Extension and the ability to restart the Java
Bridge and configure the Java Bridge settings (from Server Setup | Components).
The Java Bridge is an optional component that is installed differently, depending on the operating
system (WIN, UNIX) and the installation method format (EXE, DEB, RPM). Once the extension is
installed and its status is On, PHP code can use the Java Bridge API to call Java objects.
The process of calling Java objects in PHP is described in the following diagram:
Zend Server for IBM i
107
Advantages
The Zend Java Bridge provides the following advantages:
J2EE application servers can be extended to include the advantages that PHP offers
(relative to other Web-enablement languages), such as reduced development time,
reduced time-to-market, lower TCO (Total Cost of Ownership), etc.
PHP-centric companies can take advantage of J2EE services that are not present in
scripting languages.
The PHP/Java Bridge provides the ability to interact with plain Java objects.
The Java Bridge operates without the overhead of a JVM for each Apache process.
The Java Bridge consumes a set amount of memory that is disproportionately small
relative to the amount of activity that it handles.
Zend Server 5 for IBM i Reference Manual
108
Zend 5250 Bridge
The 5250 Bridge is a PHP based solution for running interactive applications in the i/OS
environment. This provides an answer to the challenges faced with directly accessing the 5250
data stream. The 5250 Bridge provides a method for running interactive i/OS based applications
through a browser.
There are several distinct usages for this solution:
1. Providing a web-based interface to replace the traditional green-screen display –
allowing for a wider range of functionality and display options.
2. Creating a web-based version of legacy applications – opening up the functionality to
users who are not familiar with the i/OS environment and extending the usage to a wider
range of users.
3. Incorporating information from i/OS into integrated applications – providing System
Integrators with tools to ensure true integration with data/applications located on i/OS
servers.
5250 Predecessor
Zend Server for IBM i
109
How the Zend 5250 Bridge Works
The diagram below shows how the 5250 Bridge can be used to access information from a 5250
program and leverage it to either be displayed in a browser-based environment or to populate
screen values:
1. PHP sends a 'start session' request to the 5250 Program using the 5250 Bridge.
2. The 5250 Bridge returns a confirmation to PHP that the session has started.
3. The 5250 Bridge sends current screen information in XML format to PHP (e.g. format
name, input and output fields and current cursor position).
4. The XML data can be automatically entered into the program or sent on in an html format
for user input.
Flow depicting the interaction between the 5250 Bridge, the i/OS server, and PHP
Zend Server 5 for IBM i Reference Manual
110
Overview
The Zend 5250 Bridge is a PHP API which offers several modernization options for running
interactive (5250) applications in a Web environment.
The 5250 Bridge assists developers who are interested in PHP as a strategic Web development
platform for their organizations.
The 5250 Bridge is a set of functions that developers can use to import 5250 functionality into a
Web-based environment. The 5250 Bridge offers 2 models of operation:
1. 5250 Emulator - Displays your IBM i application in a browser by emulating your application.
2. 5250 Bridge API - Web-enables your application and allows for complete customization
options.
The Working with the 5250 Bridge section will help you to decide which mode of operation is
suitable for you.
Note: In all the cases, the business logic continues to run normally on the IBM i. The options given are
for presentation level changes and further in-browser functionality and PHP development.
Note: The 5250 Bridge uses the IBM WebFace server which allows the running of interactive (5250)
programs in batch mode. IBM WebFace server APIs do not support Workstation IDs. The display
device starting with QQF is created and used by the WebFace APIs.
Advantages
The following list describes a few key advantages to implementing the 5250 Bridge:
Does not require WebSphere Application Server (WAS), resulting in lower CPW
requirements providing the ability to run applications on less expensive machines.
No 5250 workload - use batch processes for green screen programs instead of
interactive processes.
No display file source required - works on objects.
Allows access to a variety of IBM i resources that do not currently have an interactive
option.
Transfer presentation data only - Only transfers the information displayed on screen,
reducing traffic.
Zend Server for IBM i
111
Ability to encapsulate a 5250 program into Web Services - present the application as a
Web service to grant access from any client without limitations.
Free single connection for evaluating the 5250 Bridge even after the trial license expires.
This provides the ability to create a fully functioning Web based application in PHP based
on content currently only accessible from the 5250 emulation.
Extendibility with features only applicable to Web based applications such as Rich-text,
sound and images, AJAX, Mashups.
Note: The Zend Server for IBM ir trial license allows creating unlimited interactive (5250) sessions.
Once the trial license expires the interactive (5250) sessions will be limited to one at a time. Fully
licensed versions permit creating unlimited interactive (5250) sessions.
Zend Server 5 for IBM i Reference Manual
112
Zend Framework Zend Framework is a high quality, open source framework for developing Web applications and
Web services with PHP.
Built in the true PHP spirit, the Zend Framework delivers ease-of-use and powerful functionality. It
provides solutions for building modern, robust and secure websites.
Zend Framework Resources
All the developer resources can be found at: http://framework.zend.com/
Why Zend Framework
(Taken from: http://framework.zend.com/whyzf/overview)
Extending the art and spirit of PHP, Zend Framework is based on simplicity: Object-oriented best
practices, corporate friendly licensing and a rigorously tested agile code base. Zend Framework
is focused on building more secure, reliable and modern Web 2.0 applications and Web services,
and consuming widely available APIs from leading vendors like Google, Amazon, Yahoo!, and
Flickr, as well as API providers and cataloguers like StrikeIron and ProgrammableWeb.
Expanding on these core themes, we have implemented Zend Framework to embody extreme
simplicity and productivity, the latest Web 2.0 features, simple corporate-friendly licensing and an
agile, well-tested code base that your enterprise can depend upon.
Extreme Simplicity & Productivity
We designed Zend Framework with simplicity in mind. To provide a lightweight, loosely-coupled
component library simplified to provide 4/5s of the functionality everyone needs and that lets you
customize the other 20% to meet your specific business needs. By focusing on the most
commonly needed functionality, we retain the simplified spirit of PHP programming, while
dramatically lowering the learning curve - and your training costs – so developers get up-to-speed
quickly. We do this with:
Extensible and well-tested code base
Flexible architecture
No configuration files necessary to get going
Zend Server for IBM i
113
Frameworks and best practices mean reduced training costs and quicker time-to-market –
important factors in adoption decisions. Built so you can pick and choose just the pieces you
need to turbocharge your web applications – all your developers know where to find their PHP /
Zend Framework code, which speeds new development and reduces maintenance costs.
Latest Web Development Features
AJAX support through JSON – meet the ease-of-use requirements your users have come to
expect
Search – a native PHP edition of the industry-standard Lucene search engine
Syndication – the data formats and easy access to them your Web 2.0 applications need
Web Services – Zend Framework aims to be the premier place to consume and publish web
services
High-quality, object-oriented PHP 5 class library – attention to best practices like design patterns,
unit testing and loose coupling
Friendly & Simple Licensing, Safe for the Enterprise
Based on the simple and safe new BSD license, with Zend Framework's License, you can rest
assured that your code is compliant, unimpeachable and protected as you see fit. We also require
all contributors to the open source Zend Framework to complete and sign a Contributor License
Agreement (CLA) — which is based on the standard open-source Apache license — to protect
your intellectual property (that is, your added-value) built on Zend Framework.
Fully Tested – Extend Safely and Easily
Tested. Thoroughly. Enterprise-ready and built with agile methods, Zend Framework has been
unit-tested from the start, with stringent code coverage requirements to ensure that all code
contributed has not only been thoroughly unit-tested, but also remains stable and easy for you to
extend, re-test with your extensions and further maintain.
Zend Server 5 for IBM i Reference Manual
114
Monitor The Zend Monitor component is integrated into the runtime environment and serves as an
alerting and collection mechanism for early detection of PHP script problems.
The Zend Monitor is a Zend Server for IBM i component that integrates into the PHP runtime
environment and watches for various events such as errors, failing functions, slow scripts,
database errors, etc. When an event occurs, the Zend Monitor collects and reports all the
relevant debugging information. This information can then be used to perform root cause
analysis.
What is an Event?
Events are governed by rules created in Rule Management | Monitor. Rules define the nature of
an event and the parameters for capturing event related information in an application. Events are
only created when the monitor component is running (Server Setup | Components).
By definition, an event is a collection of information that can be used to investigate what caused
the rule to trigger an event. The information collected varies according to the rule type.
Aggregation
If events are triggered by the same rule and have similar characteristics – i.e., filename, URL, line
etc – they are aggregated into a single issue. If they do not have similar characteristics, a
separate (new) issue is created.
Inside a single issue, events are divided into groups according to when they occurred. A new
group is created only if there is no activity for at least five minutes. If a new event occurs after five
minutes pass, a new group is added to the issue. The new group includes all the events that
occurred, as long as five minutes without activity has passed.
Changing Statuses
This section describes what happens to issues when they are created and what happens when a
new event must be added to an issue after the issue's status has changed.
New events are created with the New status.
If an event is closed and a new issue occurs, the event is changed to the Reopened
status.
If an event is ignored and a new issue occurs, the event does not change its status.
However, the system continues to collect information for the event.
Zend Server for IBM i
115
Zend Server 5 for IBM i Reference Manual
116
Page Cache The Zend Page Cache component is used to cache the entire output of PHP scripts, without
changing the PHP code.
The Zend Page Cache improves PHP application performance by caching the entire output of
PHP scripts (HTML, XML, etc.), while still maintaining dynamic capabilities through an elaborate
rules system. Rules are configured in the Administration Interface.
Page caching extends the concept of caching files and applies it to pages. Caching by page
facilitates the ability to eliminate situations where the same file is used in multiple instances, such
as when the same file is used to redirect to several pages.
When to Cache Pages Pages should be cached when their content is stable and does not require frequent changes. You
can cache any PHP generated output including, HTML, XML, and images (if the images are
generated by PHP, such as graphs and charts).
Compression should be used to cache content such as HTML, XML and plain text, but is not
recommended for caching binary output.
When Not to Cache Pages Caching is not recommended for files that have constantly changing output, such as clocks,
timers and database queries.
Compression should not be used for images, PDF files, .exe files, ZIP files or any other
compressed binary formats.
Note: Zend Page Cache only caches GET and HEAD HTTP requests. To comply with the HTTP RFC,
POST requests are never cached.
All cached content is stored in a hashed directory structure on disk. The location is defined by the
directive zend_pagecache.save_path.
Caching Alternatives
Web pages that contain sections that continuously change can also be cached. This partial page
caching solution can be accomplished by applying the Data Cache API to the portions of code
that do not change. Data caching is an intermediate solution to provide a partial performance
boost that can sustain the accuracy of changing content.
To find out more about this alternative, go to Data Cache
Zend Server for IBM i
117
Job Queue Component
The Jobs approach is used for streamlining offline processing of PHP scripts. It provides the
ability to delay execution of “heavy” parts of web applications that originate from direct user
interaction with a Web Server. As result it may significantly improve response time and reduce
Web Server load.
Basically, any authorized PHP script can create a job which will be executed later, separately
from a current HTTP request. The job itself is just an additional HTTP request to another PHP
script that can be done on the same or different Web Server. In addition, the Jobs component
supports SHELL based jobs which can execute any command.
As opposed to “fire and forget” systems,(like cron), the Job Queue is a job management system
that provides advanced capabilities such as:
Keeping track of batch jobs, including their status, execution time and output
Different schedule strategies based on time, load, job priorities and dependencies
Run-time statistics
Web-based management GUI
The functional diagram of the Job Queue is shown on the following picture.
The central part of the Job Queue system is the Job Queue daemon. As a standalone process, it
serves requests from front-end PHP scripts (through special extension which encapsulates all the
protocol details). Such requests may ask to create a new job with specific parameters or to
retrieve the state of previously added jobs. To store information about jobs, Job Queue uses a
central database. All the database updates (e.g. job creation, deletion, etc) are performed only by
Zend Server 5 for IBM i Reference Manual
118
the Job Queue Daemon. Front-end PHP scripts and management GUI may modify data in the
database only through Client Extension API calls which actually send requests to the daemon.
The Job Queue may be easily configured to use several dedicated back-end servers which
handle HTTP based batch jobs. In this case it performs a type of load balancing by spreading
jobs across servers.
Zend Server for IBM i
119
Zend Code Tracing
Zend Code Tracing enables real-time execution flow recording in Production Environments.
Code Tracing enables deep analysis of PHP execution and flow using drill-down requests related
to an Event (Monitoring Rule), or triggered manually.
The component focuses on collecting key data points such as:
Application functions and main PHP function calls including function arguments
High-resolution timing and memory usage of execution elements.
Key PHP engine services such as Web server interface calls
The information collection process focuses on only keeping relevant information based on user-
defined parameters that trigger events. Each time an event is triggered the information is dumped
(kept) for further use. Otherwise, the information will be discarded to preserve disk-space. Events
can also be triggered to generate a dump for a specific URL (see Creating a Dump page).
The Trace information is a capture of the Function Tree and enables deep tracing of the
functions of the server parameters, including:
Returns
Memory
Time (ms)
Advantages
One of the most appealing characteristics of this application is that the performance and memory
characteristics have been designed to be suitable for production environments and excellent in-
depth trace of execution.
Other advantages:
In-depth root-cause analysis when event happens. Trace of “exact” request which had
the failure (a view back in time)
No need for risky reproduction
Insight into additional PHP subsystems beyond the script itself such as Web Server
interface
Technology suitable for development, testing, staging and production
Zend Server 5 for IBM i Reference Manual
120
Zend 5250 Bridge
The 5250 Bridge is a PHP based solution for running interactive applications in the i/OS
environment. This provides an answer to the challenges faced with directly accessing the 5250
data stream. The 5250 Bridge provides a method for running interactive i/OS based applications
through a browser.
There are several distinct usages for this solution:
1. Providing a web-based interface to replace the traditional green-screen display –
allowing for a wider range of functionality and display options.
2. Creating a web-based version of legacy applications – opening up the functionality to
users who are not familiar with the i/OS environment and extending the usage to a wider
range of users.
3. Incorporating information from i/OS into integrated applications – providing System
Integrators with tools to ensure true integration with data/applications located on i/OS
servers.
5250 Predecessor
Zend Server for IBM i
121
How the Zend 5250 Bridge Works
The diagram below shows how the 5250 Bridge can be used to access information from a 5250
program and leverage it to either be displayed in a browser-based environment or to populate
screen values:
1. PHP sends a 'start session' request to the 5250 Program using the 5250 Bridge.
2. The 5250 Bridge returns a confirmation to PHP that the session has started.
3. The 5250 Bridge sends current screen information in XML format to PHP (e.g. format
name, input and output fields and current cursor position).
4. The XML data can be automatically entered into the program or sent on in an html format
for user input.
Flow depicting the interaction between the 5250 Bridge, the i/OS server, and PHP
Zend Server 5 for IBM i Reference Manual
122
Overview
The Zend 5250 Bridge is a PHP API which offers several modernization options for running
interactive (5250) applications in a Web environment.
The 5250 Bridge assists developers who are interested in PHP as a strategic Web development
platform for their organizations.
The 5250 Bridge is a set of functions that developers can use to import 5250 functionality into a
Web-based environment. The 5250 Bridge offers 2 models of operation:
1. 5250 Emulator - Displays your IBM i application in a browser by emulating your application.
2. 5250 Bridge API - Web-enables your application and allows for complete customization
options.
The Working with the 5250 Bridge section will help you to decide which mode of operation is
suitable for you.
Note: In all the cases, the business logic continues to run normally on the IBM i. The options given are
for presentation level changes and further in-browser functionality and PHP development.
Note: The 5250 Bridge uses the IBM WebFace server which allows the running of interactive (5250)
programs in batch mode. IBM WebFace server APIs do not support Workstation IDs. The display
device starting with QQF is created and used by the WebFace APIs.
Advantages
The following list describes a few key advantages to implementing the 5250 Bridge:
Does not require WebSphere Application Server (WAS), resulting in lower CPW
requirements providing the ability to run applications on less expensive machines.
No 5250 workload - use batch processes for green screen programs instead of
interactive processes.
No display file source required - works on objects.
Allows access to a variety of IBM i resources that do not currently have an interactive
option.
Transfer presentation data only - Only transfers the information displayed on screen,
reducing traffic.
Zend Server for IBM i
123
Ability to encapsulate a 5250 program into Web Services - present the application as a
Web service to grant access from any client without limitations.
Free single connection for evaluating the 5250 Bridge even after the trial license expires.
This provides the ability to create a fully functioning Web based application in PHP based
on content currently only accessible from the 5250 emulation.
Extendibility with features only applicable to Web based applications such as Rich-text,
sound and images, AJAX, Mashups.
Note: The Zend Server for IBM ir trial license allows creating unlimited interactive (5250) sessions.
Once the trial license expires the interactive (5250) sessions will be limited to one at a time. Fully
licensed versions permit creating unlimited interactive (5250) sessions.
Zend Server 5 for IBM i Reference Manual
124
Applications The Applications tab is accessed from, Monitor | Applications.
5250 Bridge API Demo Applications
The two Demo Applications demonstrate how the 5250 Bridge API can be used to create
interactive web-applications for 5250 programs. Clicking one of the demo application links open a
new browser Window .The "return to demo page" link displays "The Zend 5250 Bridge Demo
Programs" page. For optimized performance open the demo applications in Mozila Firefox (click
here to download).
Note: The sample application code is located in: /usr/local/zendsvr/5250/demos.
For more information about the Demo Applications and how you can recreate this functionality in
your environment see: Analyzing the Demo Applications.
Zend Server for IBM i
125
Working with the Demo Applications
Subfile Demo
To login, click on the Subfile demo option. You will be directed to a login screen that cannot be
edited. Click login to open the demo.
You will notice there is a "Disconnect" button, use this button to remove the session when you
have finished using the demo.
Comparison:
If you open the Demo Application in a green screen emulation and in the browser and compare
them side by side you will notice that there are a few differences. These differences are not due
to technological constraints rather to demonstrate the ability to extend usability beyond copying
screens. A web application has more flexible display options such as using a button to get details
instead of OPTION 5 and using a popup to display the details instead of moving to another
screen each time you enter a new command. These things should be considered when creating a
web based version of an I5/OS application to make sure you benefit from an optimal range of
advantages.
Behind the Subfile Demo
This demo application was written in PHP using the Zend 5250 Bridge Procedural API Functions
using functions to organize the code and HTML for the display. The source code for the Demo
Applications can be found in /usr/local/zendsvr/5250/demos/subfileExtended. The main file is
called index.php. Sample applications can be viewed in a green screen by logging into IBM i.
When using your emulator, you can view the original format of the demo application by running
the following command in the command area: ADDLIBLE ZENDSVR and CALL ZMI001R.
Extended Subfile Demo
The Extended Subfile Demo, shows how you can use the 5250 Bridge API recreate IBM i
resources in a web based environment without using the 5250 emulation client look and feel. This
like the Subfile Demo, provides a way to extend your IBM i resources to the web and provide a
more user friendly application and in addition demonstrates how you can improve the layout using
HTML and AJAX.
Zend Server 5 for IBM i Reference Manual
126
Working with the Extended Subfile Demo
To login, click on the Extended Subfile demo option. You will be directed to a login screen that
cannot be edited. Click login to open the demo.
You will notice there is a "Disconnect" button, use this button to remove the session when you
have finished using the demo.
Behind the Extended Subfile Demo
This demo application was written in PHP using the Zend 5250 Bridge Object Oriented API using
classes to organize the code and AJAX to create advanced functionality like replacing language
types with flags representing the language and adding pictures to each name.
The source code for the Demo Applications can be found in
/usr/local/zendsvr/5250/demos/subfileExtended. The main file is called index.php. Sample
applications can be viewed in a green screen by logging into IBM i. When using your emulator,
you can view the original format of the demo application by running the following command in the
command area: ADDLIBLE ZENDSVR and CALL ZMI001R.
Zend Server for IBM i
127
Working with the Zend 5250 Bridge The Zend 5250 Bridge provides two different methods for Web-enabling your PHP applications:
1. Zend 5250 Emulator - Takes the back-end logic of your 5250 application and displays it in a
browser format. This is achieved without any work from the developer.
2. Zend 5250 Bridge API - A set of API functions which allow you to use the input and output
data in your 5250 application to construct a PHP application which allows complete flexibility
and customization options.
Which Method Should you Choose?
The method you choose will depend on the amount of time you want to invest in the process, the
programming knowledge and skills that you or your programmers possess, and the amount of
extra customization and functionality that you would like to add to your application:
Zend 5250 Emulator
Use the Zend 5250 Emulator if you:
Need to give users browser access to your 5250 applications and want to invest a
minimum amount of development time.
Want to reduce emulator application deployment costs (licences/time).
Want to make small cosmetic changes (colors etc.) to your screens.
Do not know PHP or JavaScript (though a basic knowledge of HTML/CSS is useful if you
want to customize the 'look' of your screens.)
Want to test the capabilities of the Bridge.
Plan to frequently change your 5250 Display Files.
5250 Bridge API
Use the Zend 5250 Bridge API if you:
Want to make presentation-level changes as well as applying additional display logic
Want to apply complete display-side customization to all or individual screens.
Want to combine several screens into a new view.
Want to remove or filter out content/data for a subset of end-users (e.g. redundant fields).
Have a good knowledge of PHP/HTML/CSS/JavaScript (recommended).
Expect to continue significant development of your RPG 5250 applications and want to
minimize Parallel Maintenance considerations.
Zend Server 5 for IBM i Reference Manual
128
Want to pipeline the data coming from the bridge for usage in other, non browser
applications (Java, Web Services, others.)
For more information on working with the Zend 5250 Bridge see Zend 5250 Bridge Introduction.
Zend Server for IBM i
129
Zend Server for IBM i 5250 Bridge Settings The 5250 Bridge Settings page is accessed from Server Setup | 5250 Bridge Settings.
The 5250 Bridge Settings page enables you to configure your settings for smooth integration with
other current user settings; for instance, language settings and characters, connection type and
performance, server time-out, and print screen as XML. The 5250 Bridge Settings tab includes
the following windows:
Zend 5250 Bridge
Zend 5250 Bridge Configuration
Zend 5250 Bridge
Click the Start service link to begin the service
Note: The same function can be invoked from the 5250 Bridge Management Menu (option 7 in the Zend
Server for IBM i Service Menu).
Zend 5250 Bridge Configuration
The Zend 5250 Bridge Configuration window enables you to integrate with your current user
settings:
I/OS EBCDIC Character Code Page (CCSID) - The values are: English, Italian, French,
German and Spanish. This setting allows to view 5250 screen special characters in a
browser
Persistent Connection - Define the connection type between the 5250 Bridge and your
System i server. Click, Yes for a persistent connection and No for the connection to be
terminated once the script has run. Persistent connections allow to increase 5250 Bridge
server connection-time performance. For more detailed information on persistent
connections,.refer to i5-pconnect in the PHP Toolkit section.
Server Time-Out (in microseconds) - The time to wait for a connection to the IBM i server
before timing-out. Decreasing the server timer-out allows to increase PHP script overall
performance using the 5250 Bridge API. This setting can be set to 0 for V5R4.
Print Screen Image as XML - This can be used by developers to debug their applications
by providing an XML version of the 5250 screen image. Clicking Yes, will add an
additional field for you to specify a path for saving the file containing screen image
information in XML format. After changing the settings, click Save to apply changes.
Zend Server 5 for IBM i Reference Manual
130
Working with the Zend Server 5250 Emulator The Zend 5250 Emulator provides browser access to IBM i resources and applications equivalent
to an IBM® 5250 terminal. This does not require any work from the developers or end users.
However, customization options for the developer are limited to presentation-level via CSS files.
This method is suitable for users who want to test the capabilities of the Bridge or simply need to
give users browser access to their applications without having to deploy telnet or terminal client
applications.
How it Works
The Emulator application automatically displays your 5250 applications in a browser. It does so
by collecting screen information from your 5250 application screens and displaying this
information in a browser, based on the settings configured in one of three included CSS template
files. By default, the Emulator application was designed to render pages in a way which
resembles the original 5250 green screens in order to make the transition easy for the users.
The look and layout of the application is controlled by three CSS files included in the Emulator. In
order to edit the basic layout and look of your screens, you can edit one of these CSS files, which
will apply changes to all screens in your application.
Zend Server for IBM i
131
Connecting to your Emulated Application
By installing the Zend Server for IBM i Package (which includes the Zend 5250 Emulator) onto
your server, you have already completed the process of Web-enabling your application. You now
simply need to browse to your application in order to view it. The Zend 5250 Emulator takes the
input and output fields in your 5250 application and converts them into HTML/CSS based
screens.
Editing the designated CSS file provided with the Zend 5250 Emulator lets you edit the style and
layout of the application.
To connect to your emulated application: 1. Access the emulator through the Applications tab,
-or-
Browse to: <i_server_IP>:10088/Zend5250Login/.
The Zend 5250 Bridge Applications login screen is displayed.
2. In the top section of the screen:
i. Enter your IBM i user and password.
ii. Click Login.
Your green screen application is displayed in a browser. By default, this will be the
IBM i Main Menu, or the initial screen defined for your user level.
Zend Server 5 for IBM i Reference Manual
132
2. You can navigate through the screens using the function keys as you would your
regular 5250 application.
In addition, you can navigate between the input fields on the screen using your
keyboard's arrow keys (as you would in a 5250 terminal emulator), the tab/shift-tab
keys (as you would in a Web based application), or a mouse.
3. The toolbar at the top of your screen provides you with the following options:
User Session - Allows you to create a new session or disconnect from the current
session.
Color Scheme - Allows you to change the color scheme of the displayed screens.
The options are:
• Green Screen - Presents your screens in the 'traditional' green screen
format
• White Background - Presents your screens with a white background
(adopts the 'look' of a traditional Web application).
• Custom - Presents your screens according to the settings configured in
the custom.css file. This is the file which you can edit in order to
Zend Server for IBM i
133
customize the look of the screens. See CSS Editing topic for more
information. By default, this will look the same as the white background
option.
Advanced Settings - Allows you to customize the display options:
Output Field Tooltips - When selected, you can hover your mouse over the fields
to display the fields IDs. This is useful when using the Zend 5250 Bridge API.
Note: The field ID format used in Zend 5250 Bridge 2.0 differs slightly from that used in
previous versions. Applications utilizing those IDs will still work.
System Command Auto-Complete - When selected, entering the first few letters
of a CL command in the input line will auto-complete the relevant command.
Show XML Source - Will open a new browser window with the XML source code
of the current page. This source code can be used for customization when using
the Zend 5250 Bridge API.
Note: If you continue to navigate through your application, you will need to press Enter in
the XML source page in order for the XML code to be updated with the current
screen data.
Function Keys - Displays a screen-based 'soft keyboard' for using function
keys without having to press function keys on the keyboard. This is useful when
your keyboard does not have all the required function keys, or when the required
function keys are used by the browser (e.g. pressing F5 in some browsers will
refresh the page rather than sending the F5 command to the i5).
Zend Server 5 for IBM i Reference Manual
134
Note: The 5250 Bridge installation includes two Javascript files which allow the catching of
function key “presses”. You can find more information about function keys in the Zend
Server for IBM i installation
folder/usr/local/zendsvr/demos/JSfunctionKeyListener/readme.txt.
Print - Opens the print dialog for printing the current screen.
Zoom - Adjusts the screen's zoom level.
Zend Server for IBM i
135
Customizing your Application
By editing the custom.css file provided by the Zend 5250 Emulator you can customize certain
screen display elements, such as text color, background color, background images etc.
To customize the Emulator's CSS file: 1. Using Zend Studio - i5 Edition, open the custom.css file, located in
/usr/local/zendsvr/5250/Emulation/html/styles/themes.
See Opening Files in Zend Studio for more information.
2. Apply customization changes to the file
See CSS Editing topic for more information.
3. Once you have made your changes, save the file.
You will be able to see the changes in your application when browsing to it through
the Zend 5250 Emulator.
Formatting Fonts
Because the 5250 applications are outputted in a 24x80 or 27x132 grid, all characters on the
5250 green screen terminal are monospaced. This means each character takes up the same
sized cell of screen “real estate” and 5250 application developers have found creative ways to
provide basic UI design using absolute values (rows & columns).
In a Web environment, display element possibilities are much richer and can be arranged
relatively and absolutely in a range of alignment and other controls such as DIVs and Tables.
This allows Web developers to use different fonts and font sizes in multiple screen resolutions
and sizes without damaging overall screen layout. The Emulator outputs text exactly as it is
displayed on the Green Screen terminal. Changing the fonts in the Emulator CSS from the default
Monospace ones (Courier), will likely cause significant page element alignment problems. If your
users demand richer application interfaces, you will probably develop new interfaces using the
5250 API a better solution. This will require learning PHP, HTML, CSS and JavaScript.
Zend Server 5 for IBM i Reference Manual
136
CSS Editing Formatting for modern Web applications is normally controlled by a CSS (Cascading Style Sheet)
file. Editing the CSS file will apply global changes to all screens displayed by the Emulator.
Note: Many PHP development teams have pre-designed CSS files created for them. If your company
has standard CSS templates and formats, we recommend using those as much as possible to
ease user adoption and familiarity. You may need to make some adaptations to them.
The following can defined by customizing your CSS file:
Background color
Background images (e.g. logos)
Text colors
Text styles (bold, italic, underline)
Text font and size
Note: 5250 Green Screens are monospaced. Therefore changing your text's font and size from the
default font (Courier) will probably cause alignment problems. If you need to change your
application's fonts, it is recommended to use the Zend 5250 Bridge API.
Note: Zend Studio for i5/OS contains special editors for editing CSS files. See CSS Editing in the Zend
Online Help for more information.
CSS File location
By default, the Emulator's CSS files are situated in
/usr/local/zendsvr/5250l/Emulator/html/styles/themes.
Note: The Emulator provides three default CSS files (greenOnBlack.css, blackOnWhite.css or
custom.css). Whilst all of these can be customized, the custom.css file has been provided
specifically for this purpose.
It is recommended that CSS files are edited in Zend Studio's CSS editor.
See Opening Files in Zend Studio for information on accessing your CSS files through Zend
Studio for Eclipse.
Zend Server for IBM i
137
See 'CSS Editing' in the Zend Studio for Eclipse Online Help for more information on Zend Studio
for Eclipse's CSS editor capabilities.
Examples of CSS Editing Options
1. Editing Background Colors
2. Editing Font Colors
3. Editing Fonts
4. Adding an Image
Below are various examples of the customization that can be performed by editing your CSS file:
Example 1 - Editing Background Colors: In HTML/CSS, colors are defined using a hexadecimal number or letter value corresponding to a
particular color (e.g. #fff = white) or by using the color's name (e.g. by simply typing 'white'.) To
see a list of available colors, go to http://www.w3schools.com/css/css_colornames.asp.
To edit your screens' background color, edit the value in the body's 'background' attribute.
To change the background color from white to black: Change the following code: body { background: #fff; to body { background: #000;
Example 2 - Editing Font Colors: Your CSS files contain font color attributes for each of the font colors available in i5. Editing the
color value of one of these attributes will cause all text in the original color across all screens to
be displayed in the newly defined color.
To change all blue text to black: Change the following code: .color-attr-blue { color: #3366cc; to .color-attr-blue { color: #000;
To see a list of available colors, go to http://www.w3schools.com/css/css_colornames.asp.
Zend Server 5 for IBM i Reference Manual
138
Example 3 - Editing Font Styles In order to change the fonts used in your screens you simply need to edit the 'font-family' attribute
in your CSS file with the required font value.
Note for Emulator users: 5250 Green Screens are monospaced. Therefore, changing your text's font and size from the
default font (Courier) will probably cause alignment problems.
To change the font used from courier to arial: Change the following code: font-family:courier; to font-family:arial;
Example 4 - Adding an Image You can add a background image to all screens through the CSS file.
Before you add code to the CSS file, you will need to add the image to a directory on your i5
server. You then add code to your CSS file which sets the background image position.
To add an image to the top-right corner of all your screens: Add the following code within the body attribute of your CSS file: background: #fff url(my_logo.gif) 98% 25px no-repeat;
Note: In this example, my_logo.gif is situated in the same directory as your .css file. If it was
located in a different directory, you would have to specify the full or relative path to the
image's location.
See http://www.w3schools.com/Css/css_positioning.asp for more on how to set your image's
position.
Zend Server for IBM i
139
Opening Files in Zend Studio Zend Studio is the leading PHP IDE (Integrated Development Environment) for editing and testing
PHP code. It is recommended to use Zend Studio in order to make any edits to the Emulator's
CSS files.
This procedure describes how to create a project in Zend Studio which allows you to access and
edit files on your IBM i server.
To open your files in Zend Studio: 1. Create a new PHP project by going to File | New | PHP Project and entering the
relevant details in the new PHP Project wizard.
2. In the PHP Explorer view, right-click your project and select New | Remote folder.
The New Remote Folder dialog will be displayed.
3. In the 'Remote folder' selection, click Browse.
The Select Folder dialog will open.
4. Click New next to the Connection drop-down list in order to configure a connection
to your IBM i server.
5. In the Select Remote System Type dialog, select FTP or SSH (for a secure
connection) and click Next.
6. In the New Connection dialog, enter your IBM i server IP address and click Finish.
7. In the 'Connection' drop-down list, select the connection you created to your IBM i
server.
8. Your IBM i server files will be displayed.
Zend Server 5 for IBM i Reference Manual
140
9. Expand the Root directory.
If prompted, enter your IBM i User ID and Password.
10. Expand the Root directory.
11. Your IBM i server's file directory will be displayed.
12. Browse to the location of the files you want to edit. Your custom CSS file is situated at:
/usr/local/zendsvr/5250l/Emulator/html/styles/themes/custom.css.
Note: Two additional CSS files are included with the Emulator: A template for a white
background application and one emulating the traditional green screen application.
However, for the purposes of editing It is recommended to use the custom.css file.
13. Click OK.
You will be returned to the New Remote Folder dialog.
14. The link name will be automatically be updated with the name of your folder. Edit
this if required.
15. Click Finish.
16. The folder will be displayed in your workspace with the relevant files.
Most of Studio's functionality, such as Code Assist, Formatting and PHP item
creation will be available to help you edit the file.
Any changes made to the files and folders in your Workspace will be updated in the
files on your server, and conversely any changes made on the server copies will be
updated in your Workspace.
Note: Deleting an FTP/SFTP folder from your Workspace will only delete it from your
Workspace. However, deleting a file contained within a folder will also delete the file
on your server. Adding new files to the linked folder in your workspace will upload the
new files to your server.
Zend Server for IBM i
141
5250 Bridge API The 5250 Bridge API is a more flexible implementation of the Emulator's capabilities which allows
you to access and customize the PHP/CSS and JavaScript code (also used by the emulator) to
create additional functionality.
This is suitable for users who want to make cosmetic changes to their application and apply some
additional display logic. In addition, users can choose to remove or filter out content/data for a
subset of end-users (e.g. redundant fields) or even pipeline the data coming from the bridge for
usage in other, non browser applications (Java, Web Services, others.). Also suitable for users
who expect to continue significant development of their RPG 5250 applications and want to
minimize their Parallel Maintenance considerations.
The 5250 Bridge API offers a number of functions/classes for PHP developers to grab fields and
strings from an interactive (5250) program and wrap them into real web applications. This way
you can seamlessly integrate output of green screen applications into your PHP Web application
without the need to rewrite the business logic and directly access the database. Alternatively you
can use the 5250 Bridge API to directly access the database and create completely new Web
applications (e.g. omit certain fields or integrate fields from different screens into one).
The 5250 Bridge APIs have two interfaces: object oriented and procedural functions. If a
developer is not comfortable using object oriented (class access) methods in PHP he can use
regular procedural functions to access the same APIs.
The 5250 Bridge API accessed information in your 5250 application's input/output fields and
allows you to use this information to 'transform' your application in PHP and HTML, while still
using your 5250 back-end logic.
The Zend 5250 Bridge API has the following purposes: 1. Starting an interactive job or 5250 session.
2. Running IBM i interactive program or menu in an interactive job..
3. Accessing 5250 screen data such as screen size, input/output field values, size, location
and attributes.
4. Updating input-field value content.
5. Sending updated input-fields to an interactive job.
6. Sending a function-key action to an interactive job.
Zend Server 5 for IBM i Reference Manual
142
Examples
To see examples of how the 5250 Bridge API can be used to web-enable your 5250 application,
see the Applications.
Zend Server for IBM i
143
Working with the 5250 Bridge API
Introduction
The 5250 Bridge API is a more flexible implementation of the Emulator's capabilities which allows
you to access and customize the PHP/CSS and JavaScript code (also used by the emulator) to
create additional functionality.
This is suitable for users who want to make cosmetic changes to their application and apply some
additional display logic. In addition, users can choose to remove or filter out content/data for a
subset of end-users (e.g. redundant fields) or even pipeline the data coming from the bridge for
usage in other, non browser applications (Java, Web Services, others.). Also suitable for users
who expect to continue significant development of their RPG 5250 applications and want to
minimize their Parallel Maintenance considerations.
The 5250 Bridge API offers a number of functions/classes for PHP developers to grab fields and
strings from an interactive (5250) program and wrap them into real web applications. This way
you can seamlessly integrate output of green screen applications into your PHP Web application
without the need to rewrite the business logic and directly access the database. Alternatively you
can use the 5250 Bridge API to directly access the database and create completely new Web
applications (e.g. omit certain fields or integrate fields from different screens into one).
The 5250 Bridge APIs have two interfaces: object oriented and procedural functions. If a
developer is not comfortable using object oriented (class access) methods in PHP he can use
regular procedural functions to access the same APIs.
The 5250 Bridge API accessed information in your 5250 application's input/output fields and
allows you to use this information to 'transform' your application in PHP and HTML, while still
using your 5250 back-end logic.
The Zend 5250 Bridge API has the following purposes: 1. Starting an interactive job or 5250 session.
2. Running IBM i interactive program or menu in an interactive job..
3. Accessing 5250 screen data such as screen size, input/output field values, size, location
and attributes.
4. Updating input-field value content.
5. Sending updated input-fields to an interactive job.
6. Sending a function-key action to an interactive job.
Zend Server 5 for IBM i Reference Manual
144
Examples
To see examples of how the 5250 Bridge API can be used to web-enable your 5250 application,
see the Working with the Demo Applications.
Using the 5250 Bridge API There are three ways of discovering the field ID's used in your application: 1. Using the 'hover' function in the emulator demo.
Run the Zend 5250 Emulator. Hovering over the fields will display the field ID.
2. Using the 'Show XML code' option in the Emulator demo.
Clicking the Show XML button will display... containing the field array structure.
3. Using 5250 Bridge API functions such as 'zend_5250_get_input_fields' and
'zend_5250_get_output_fields' in your PHP program.
This will perform a 'screen dump' of the XML information for a screen, which can then be
used to write code for the next screen.
When writing a PHP application, you must first include the 5250 Bridge PHP API library in your
code in order to be able to use the 5250 API functions.
This example shows the include code for 5250 Bridge PHP API procedural functions: set_include_path ('/usr/local/zendsvr/5250/API/' ); require_once ('Zend/ProceduralApi.php');
This example shows the include code for 5250 Bridge PHP API classes: set_include_path ('/usr/local/zendsvr/5250/API/' ); require_once ('Zend/5250.php');
Developing using the Zend 5250 Bridge API then involves using the input and output field data
from your 5250 application screens and setting an appropriate function-key action. Each field has
an id number and certain characteristics such as row column and attributes.
In order to use this screen information in your PHP Program, you must first examine the fields by
using 5250 Bridge API functions such as 'zend_5250_get_input_fields' and
'zend_5250_get_output_fields' in your PHP program.
Zend Server for IBM i
145
For example, start with code which:
Connects to your IBM i server and starts a 5250 session by using the zend_5250_open
and zend_5250_connect functions.
Sends a command to the system to display the input and output field array structure
information for that screen.
<?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/ProceduralApi.php'); // Opens a 5250 session $bridge = Zend_5250_open ( 'simple' ); $response = @zend_5250_connect($bridge); // Get the 5250 screen output fields for the IBM i login screen $outputFields = zend_5250_get_output_fields($response); // Print the output fields information echo "<pre>"; print_r($outputFields); echo "<pre>"; // End the 5250 session zend_5250_disconnect($bridge); ?>
Notes: The Zend 5250 Bridge without a valid Zend Server for IBM i license will enable a single
connection at a time. Therefore, ensure you close the 5250 Bridge connection at the end of a
program by using the zend_5250_disconnect() function.
Running this code will launch your IBM i connection screen and display the array structure
information for this screen as follows (the following information is only partial):
Array ( [0] => Array ( [id] => 0 [row] => 1 [column] => 23 [length] => 33 [value] => Sign On [color] => 3 ) [1] => Array ( [id] => 1 [row] => 2 [column] => 48 [length] => 19 [value] => System . . . . . : [color] => 1 ) [2] => Array (
Zend Server 5 for IBM i Reference Manual
146
[id] => 2 [row] => 2 [column] => 70 [length] => 8 [value] => I5QA2 [color] => 1 ) [3] => Array ( [id] => 3 [row] => 3 [column] => 48 [length] => 19 [value] => Subsystem . . . . : [color] => 1 ) [4] => Array ( [id] => 4 [row] => 3 [column] => 70 [length] => 10 [value] => QINTER [color] => 1 ) [5] => Array ( [id] => 5 [row] => 4 [column] => 48 [length] => 19 [value] => Display . . . . . : [color] => 1 ) [6] => Array ( [id] => 6 [row] => 4 [column] => 70 [length] => 10 [value] => QQF048FE62 [color] => 1 ) [7] => Array ( [id] => 7 [row] => 6 [column] => 17 [length] => 33 [value] => User . . . . . . . . . . . . . . [color] => 1 ) [8] => Array ( [id] => 8 [row] => 7 [column] => 17 [length] => 33 [value] => Password . . . . . . . . . . . . [color] => 1 ) [9] => Array ( [id] => 9 [row] => 8 [column] => 17 [length] => 33 [value] => Program/procedure . . . . . . . . [color] => 1 ) [10] => Array
Zend Server for IBM i
147
( [id] => 10 [row] => 9 [column] => 17 [length] => 33 [value] => Menu . . . . . . . . . . . . . . [color] => 1 ) [11] => Array ( [id] => 11 [row] => 10 [column] => 17 [length] => 33 [value] => Current library . . . . . . . . . [color] => 1 ) [12] => Array ( [id] => 12 [row] => 24 [column] => 40 [length] => 40 [value] => (C) COPYRIGHT IBM CORP. 1980, 2005. [color] => 3 ) )
Using the array structure information displayed for the input and output fields, you can then write
further code utilizing the Zend 5250 Bridge API. You can either create HTML browser based
screens for user input, or automatically continue running the 5250 application by setting input field
values and sending the function key actions.
You must then get array structure information for the next screen in order to continue developing.
For example, the following code will start a 5250 sess5sion, log you in to the IBM i system and
display array structure information for the next screen: <?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/ProceduralApi.php'); // Opens a 5250 session $bridge = Zend_5250_open ( 'simple' ); $response = @zend_5250_connect($bridge); // Sets and submits username and password for the IBM i login screen zend_5250_set_input_field ( $bridge, 0, 'Z5250DEMO' ); zend_5250_set_input_field ( $bridge, 1, 'Z5250DEMO' ); $response = zend_5250_submit ( $bridge ); // Get the 5250 screen output fields for the IBM i login screen // Gets arrays structure information from the next screen $outputFields = zend_5250_get_output_fields($response); $inputFields = zend_5250_get_input_fields($response); // Print the output fields information echo "<pre>"; print_r($outputFields); echo "<pre>"; // Print the input fields information
Zend Server 5 for IBM i Reference Manual
148
echo "<pre>"; print_r($inputFields); echo "<pre>"; // End the 5250 session zend_5250_disconnect($bridge); ?>
You will need to repeat this process to get and use field array structure information for each 5250
screen in your PHP application.
There is an additional way a developer can identify the 5250 screen field type (input/output) and
field id.
Run an interactive (5250) application using the 5250 Bridge Emulator program. Place the cursor
on a screen location where you want to know the screen type and screen id.
For example, in the screen below the cursor is placed on '2.Office tasks' location and the 5250
Bridge emulator program shows that this is an output field and its id is 7.
FLD_06_007. where 06 is a field row and 007 is a field starting colum7.
Identifying 5250 Screen Field Types
Zend Server for IBM i
149
See the 5250 Demo Applications included with the 5250 Bridge for further examples on writing
applications using the 5250 Bridge API. For example, to see the code for the 'subfile' demo
application go to: /usr/local/zend/5250/demos/subfile/index.php. For more sample code, refer to
Zend 5250 Bridge Use Case Examples.
Note: The 5250 Bridge installation includes two Java Script files to catch function key clicks. You can
find more information in the Zend installation folder: /usr/local/zendsvr/5250/demos/
JSfunctionKeyListener on your System i server.
Zend Server 5 for IBM i Reference Manual
150
Troubleshooting the Zend 5250 Bridge Problem Solution
The Zend 5250 Bridge environment is
occasionally 'overloaded'.
1. In the Zend 5250 Management Menu
(accessed by running the command "GO
ZENDSVR/ZSMENU" in your IBM i emulation
screen) select Option 4 - Reset 5250 Bridge
environment.
2. End the ZBRDG5250 job in the ZENDSVR
Subsystem.
3. Clear your Cookies.
The 5250 Bridge does not get the
correct screen information.
1. Increase the Server Time-Out in the Server
Setup ->5250 Bridge Tab
(http://i_server:10088/ZendServer/, Integration
menu)
2. Open your 5250 Bridge Configuration file
(Brdg5250.ini - located in
/usr/local/ZendSrv/5250/etc/Brdg5250.ini) and
increase your system timeout in the
'ReadTimeoutMicro' directive.
Zend Server for IBM i
151
FAQ What is the 5250 Bridge? The 5250 Bridge is a set of APIs for creating interactive
IBM i based applications that run through a browser.
Does the 5250 Bridge generate
HTML?
The 5250 Bridge does not generate HTML.
The 5250 Bridge API offers a number of
functions/classes for PHP developers to grab fields and
strings from an interactive (5250) program and wrap
them into real web
applications. This way you can seamlessly integrate
output of green screen applications into your PHP Web
application without the need to rewrite the business
logic and directly access the database. Alternatively
you can use the 5250 Bridge API to directly access the
database and create completely new Web applications.
What product do I need to install in
order to get the 5250 Bridge API?
The 5520 Bridge API is an integrated part of Zend
Server for IBM i
What IBM i Version does the 5250
Bridge Support?
The 5250 Bridge runs on V5R4, or later and utilizes
5250 CPW interactive processes.
How does the 5250 Bridge API
work from the PHP script?
The basic process is as follows:
1. PHP sends a 'start session' request to the 5250
Program using the 5250 Bridge API.
2. The 5250 Bridge API returns a confirmation to PHP
that the interactive program session has started.
3. The 5250 Bridge API sends current screen
information in XML format to PHP (e.g. input and output
fields, their attributes and cursor position).
4. PHP sends input values and function key actions to
the 5250 Bridge API.
How many concurrent (5250)
sessions does the 5250 Bridge
allow to open?
The 5250 Bridge can handle an unlimited amount of
concurrent 5250 sessions. Only when using an
unlicensed version or trial license expires will the
number of
concurrent connections be limited to one. This single
connection is enough for a developer to be able to
create a Web application utilizing the 5250 Bridge API.
Zend Server 5 for IBM i Reference Manual
152
Are 5250 sessions opened by the
5250 Bridge using IBM i interactive
feature?
The 5250 Bridge uses the IBM WebFace server which
allows the running of interactive (5250) programs in
batch mode.
Does the 5250 Bridge support
Workstation IDs?
The 5250 Bridge utilizes the IBM WebFace server
APIs, which do not support Workstation IDs. The
display device starting with QQF is created and used
by the WebFace APIs.
Is there support for IBM i function
keys such as F3, F12, etc?
(Bridge API)
The 5250 Bridge installation includes two Javascript
files, which allow the catching of function key clicks.
You can find more information about function keys in
the Zend
installation folder
/usr/local/ZendSVR/5250/demos/JSfunctionKeyListener
on your IBM i server.
Why are the demo applications
slow?
The demo applications run on default settings. There
are several optimizations that can be done to improve
performance:
Decrease the server time-out in the 5250 Tab. This
change allows the increase of PHP script overall
performance. This setting is set to 0 in V5R4.
Set the "Persistent Connection" to "Yes" in the 5250
Tab. The Persistent connections allow the increasing of
5250 Bridge server connection-time performance.
Do I need to know OO
programming?
The 5250 Bridge API has two types of interfaces:
classes and procedural. RPG developers who are not
familiar with OO can utilize the 5250 Bridge procedural
functions (similar to RPG/CL). Java developers who are
familiar with OO can utilize 5250 Bridge classes.
Can I incorporate stylesheets into
demo program screens and turn
fields into selection lists or radio
buttons?
You can use the demo application code as a base to
create Web applications utilizing the 5250 Bridge API.
You can enrich your browser applications with Web
features such as Rich-text, sound and images, AJAX
and Mashups.
Zend Server for IBM i
153
Zend Server 5 for IBM i Reference Manual
154
Reference Information This section contains reference information for PHP developers. Here you will find information
about using the Java Bridge, the extensions included in this release and other system-related
information.
The list of extensions provides an overview of all the extensions that are included and their status
(On, Off, Disabled). A description of what each status means can be found in PHP Extensions.
In this section:
Java Bridge Use Cases
Adding Extensions
Compiling PHP Extensions
Info Messages
Zend Server for IBM i
155
Java Bridge Use Cases This section describes some of the common uses for the Java Bridge. The usage scenarios and
examples discussed here provide a framework for the Java Bridge’s uses, rather than a complete
picture. Real world experience indicates that companies are finding more and more applications
for the Java Bridge, beyond what was initially anticipated.
Usage Scenarios
There are two usage scenarios that describe the most common applications for the PHP/Java
Bridge:
Integration with Existing Java Infrastructure - PHP is a fully featured scripting
language engineered to cover virtually all of an enterprise’s requirements. At the same
time, many enterprises have a long history of application development in Java. The Java
Bridge enables enterprises to continue to use their Java infrastructure - applications,
databases, business logic and various Java servers (WebLogic, JBoss, Oracle
Application Server, etc.).
Accessing Java Language and Architecture - Some enterprises require the full set of
PHP capabilities, yet have a specific need for select Java based applications. SIP
signaling in the communications industry or JDBC for creating connectivity to SQL
databases are two examples of impressive, industry specific products. The Java Bridge
enables enterprises to adopt a PHP standard and to use their preferred Java based
applications.
Activities
This section describes two sample activities that indicate some of what you can do with the
PHP/Java Bridge. In the sample activities, it is important to differentiate between Java and J2EE.
The difference will impact on architecture and in turn, on the script code.
The important differences are:
Java is a programming language. Java applications created in Java for the enterprise are
not bound to a specific framework. Therefore, it is possible and perhaps preferable for an
enterprise to relocate code libraries to the server that runs Zend Server for IBM i .
J2EE is a structured framework for application scripts developed for J2EE. It is preferable
that J2EE servers be left intact.
Zend Server 5 for IBM i Reference Manual
156
Example 1: A Case Study in Java Bridge Performance (Java)
The Forever Times newspaper maintains a PHP-based website - let’s call it ForeverOnline.com.
The newspaper has been searching for a real-time Stock Ticker application to add to their already
successful and heavily visited website. The Forever Times Newspaper feels that real-time
financial information is the one thing their website is lacking.
Forever Times believes they have found exactly the Stock Ticker application they need. The
application provides up-to-date quotations from all the major markets, currency rates, and even
links to some of the local exchanges. However, the application is written in Java and uses
existing Java libraries.
Forever Times realizes that a PHP-based Web implementation that handles Java requests - a
Java Bridge - is their best bet. At the same time, they are concerned that the performance of their
Website remains optimal. To Forever Times’ horror, in testing the new application, they find that
loading the site with user-requests for the Stock Ticker slows down the performance of the whole
website.
The following code example illustrates how the Java Bridge applies to this business scenario and
others like it:
Example: <? // create Java object $stock = new Java("com.ticker.JavaStock"); // call the object $news = $stock->get_news($_GET['ticker']); // display results foreach($news as $news_item) { print "$news_item<br>\n"; } ?>
The example code can be understood as follows:
The code example is written in PHP and forms part of a PHP Web application.
The PHP code creates the Java object-"com.ticker.JavaStock"-which is the PHP proxy.
Requests come into the PHP based Website - ForeverOnline.com - which then
references the Stock Ticker application.
Stock Ticker references a custom object- get_news-in the JVM library. This is all in
native Java.
The PHP code then outputs the results on the Website.
As opposed to a typical Java Bridge Implementation, the Zend Server for IBM i Java Bridge
implementation addresses performance issues through the Java Bridge architecture.
Implementing the Java Bridge is a way to address scalability issues by using the Java Bridge to
handle all communication in a single JVM instance, instead of in several instances.
Zend Server for IBM i
157
Note: While the single JVM constitutes a single point of failure, the fact is, Zend’s PHP-Java connection
is the most robust on the market. Failures in systems of this type generally tend to occur when
the Java Server is overloaded, rather than as a result of glitches in the applications. Zend Server
for IBM i ’s system architecture insures performance by diminishing overhead. However, in the
event of failure, the Java Bridge supports a restart feature that makes monitoring the status of the
Java Server and restarting quick and simple. One last point: if the failure was caused by a glitch
in the application, the same thing would most likely occur in each of the JVMs in the non-Zend
system!
Example 2: A Case Study in Management Integration (J2EE)
A company called FlowerPwr.com sells flowers over the Internet. They are a successful East
Coast-based firm that has an aggressive management profile. They are currently in the process
of acquiring a West Coast competitor - let’s call it Yourflowers.com - that provides a similar
service.
FlowerPwr.com has its own website: Its various enterprise applications are written in PHP.
Yourflowers.com also has its own Website: However, all its applications are Java-based and were
developed for J2EE. They have their own J2EE application server. FlowerPwr.com needs to
begin operating as an integrated commercial entity as soon as possible, in a way that conceals
the fact that the companies have merged.
Using the Java Bridge, FlowerPwr.com can create a common portal in PHP. The company can
leave Java up and running and take full advantage of their acquisition’s existing Java services.
FlowerPwr.com can do this over an existing portal using PHP.
The following code example illustrates how the Java Bridge can apply to this business scenario
and others like it:
Example: <? // EJB configuration for JBoss. Other servers may need other settings. // Note that CLASSPATH should contain these classes $envt = array( "java.naming.factory.initial" => "org.jnp.interfaces.NamingContextFactory", "java.naming.factory.url.pkgs" => "org.jboss.naming:org.jnp.interfaces", "java.naming.provider.url" => " jnp://yourflowers.com:1099"); $ctx = new Java("javax.naming.InitialContext", $envt); // Try to find the object $obj = $ctx->lookup("YourflowersBean"); // here we find an object - no error handling in this example $rmi = new Java("javax.rmi.PortableRemoteObject"); $home = $rmi->narrow($obj, new Java("com.yourflowers.StoreHome")); $store = $home->create(); // add an order to the bean $store->place_order($_GET['client_id'], $_GET['item_id']); print "Order placed.<br>Current shopping cart: <br>"; // get shopping cart data from the bean $cart = $store->get_cart($_GET['client_id']); foreach($cart as $item) {
Zend Server 5 for IBM i Reference Manual
158
print "$item['name']: $item['count'] at $item['price']<br>\n"; } // release the object $store->remove(); ?>
The example code can be understood as follows:
1. The code example is written in PHP and forms part of a PHP Web application.
2. The PHP application first initializes an operation with the EJB, located at a specific URL
that has the name:"//yourflowers.com:1099."
3. The code then specifies the bean-YourflowersBean-that the application will look for.
4. Next, the bean object is returned from the EJB server.
5. The application then calls methods-in this case, the Java application includes two
functions:
place_order receiving two numbers - client ID and the item ID to add to shopping
cart
get_cart receiving one number - client ID and returning the list of the items
placed in the shopping cart so far.
After script execution, the referenced class may be disposed.
Zend Server for IBM i
159
PHP Extension List Zend Server for IBM i, supports two PHP versions, PHP 5.2 and PHP 5.3. Each PHP version has
its own list of extensions as follows:
Zend Server for IBM i PHP 5.2 Extensions
Zend Server for IBM i PHP 5.3 Extensions
Zend Server 5 for IBM i Reference Manual
160
Zend Server Extension List - PHP 5.2
Common Extensions
Common extensions are installed and enabled by default in typical installations
Extension Status Description
Bcmath Enabled Arbitrary precision mathematics functions based on the bcmatch (Binary
Calculator) library
bz2 Enabled The bzip2 functions are used to transparently read and write bzip2 (.bz2)
compressed files and streams
calendar Enabled The calendar extension provides functions that simplify conversion between
different calendar formats
ctype Enabled Character Classifications - Checks whether a character or string falls into a certain
character class according to the current locale
curl Enabled Enables you to connect to and communicate with different types of servers using
various protocols - for example HTTP and FTP
date Built-in Enables various date and time related functions that can handle retrieving the
time, date formatting and more
dom Built-in Enables operating on an XML document using the Document Object Model (DOM)
API
exif Enabled Enables access to image EXIF (Exchangeable Image File Format) meta data
filter Built-in Provides a set of functions for validating and filtering data coming from insecure
sources, such as user inputs
ftp Enabled Provides low-level client access to FTP (File Transfer Protocol) servers
gd Enabled Enables creation, manipulation and streaming of images and graphics in various
formats
gettext Enabled Provides a set of functions that allow internationalization of PHP applications
through the GNU gettext API
hash Built-in Enables direct or incremental processing of arbitrary length messages using a
variety of hashing algorithms
i5comm Enabled Provides access to all IBM i system resources such as RPG/COBOL/CL programs,
database files / tables, spooled files, data queue and more
iconv Enabled Enables conversion between different character sets using the iconv library
imap Enabled Provides mail and news access through the IMAP, POP3 and NNTP protocols
intl Enabled Provides Unicode and global localization support to PHP applications using the ICU
library
Zend Server for IBM i
161
Extension Status Description
json Enabled Implements the JavaScript Object Notation (JSON) data-interchange format
ldap Enabled Provides access to LDAP (Lightweight Directory Access Protocol) based directory
servers; Based on the OpenLDAP library
libxml Built-in Provides basic API and infrastructure for other XML processing extensions
mbstring Enabled Enables manipulation of strings encoded in multi-byte character encoding
schemes
mcrypt Enabled Provides support for multiple encryption algorithms using the mcrypt library
mhash Enabled
Provides support for multiple hashing algorithms using the mhash library. Can be
used to create checksums, message digests, message authentication codes, and
more
mime_magic Enabled Eanbles automatic MIME-type detection based on various patterns in files
mysql Enabled Provides legacy access to MySQL database servers. For new applications it is
recommended to use the 'mysqli' extension
mysqli Enabled MySQL Improved - Provides access to MySQL database servers. Enables the
functionality provided by MySQL 4.1 and above
openssl Built-in This module utilizes the OpenSSL library for generation and verification of
signatures and for encrypting and decrypting data and streams
pcre Built-in Provides a set of functions for string matching and manipulation based on Perl
Compatible Regular Expressions syntax
pdo Built-in Base PDO (PHP Data Objects) Driver - Defines a lightweight, consistent interface
for accessing databases in PHP
pdo_mysql Enabled PDO (PHP Data Objects) driver that enable access from PHP to MySQL database
servers
pdo_oci Enabled PDO (PHP Data Objects) driver that enable access from PHP to Oracle database
servers using the OCI library
pdo_pgsql Enabled PDO (PHP Data Objects) driver that enable access from PHP to PostgreSQL
database servers
pdo_sqlite Built-in PDO (PHP Data Objects) driver that enable access from PHP to SQLite database
files
pgsql Enabled Provides access to PostgreSQL database servers
posix Enabled Contains an interface to functions defined in the IEEE 1003.1 (POSIX.1)
standards document which are not accessible through other means
reflection Built-in Adds the ability to reverse-engineer classes, interfaces, functions and methods as
well as extensions
session Built-in Enables data persistence between consecutive requests of the same user session
Zend Server 5 for IBM i Reference Manual
162
Extension Status Description
simplexml Built-in
The SimpleXML extension provides a very simple and easily usable toolset to
convert XML to an object that can be processed with normal property selectors
and array iterators
soap Enabled The SOAP extension can be used to implement SOAP Servers and Clients
sockets Enabled The socket extension implements a set of low-level socket communication
functions, providing the possibility to act as a socket server as well as a client
spl Built-in SPL is a collection of interfaces and classes that can be used to solve standard
problems
sqlite Enabled Enables usage of the SQLite Embeddable SQL Database Engine. Can be used for
SQL database access without running a separate RDBMS process
standard Built-in Standard PHP functions
tidy Enabled Tidy HTML Clean and Repair - enables you to not only clean and otherwise
manipulate HTML documents, but also traverse the document tree
tokenizer Enabled
The tokenizer functions provide an interface to the PHP tokenizer embedded in
the Zend Engine. Using these functions you may write your own PHP source
analyzing or modification tools without having to deal with the language
specification at the lexical level
xml Built-in Enables the creation of event-based XML document parsers using the SAX XML
interface
xmlreader Enabled The XMLReader extension is an XML Pull parser. The reader acts as a cursor going
forward on the document stream and stopping at each node on the way.
xmlwriter Enabled Provides a non-cached, forward-only writer for generating streams or files
containing XML data in an efficient manner
xsl Enabled The XSL extension implements the XSL standard, performing XSLT
transformations using the libxslt library
zip Enabled ZIP Archives - Enables you to transparently read ZIP compressed archives and
the files inside them
zlib Built-in
Enables you to transparently read and write gzip (.gz) compressed files, through
versions of most of the filesystem functions which work with gzip-compressed
files
Zend Server for IBM i
163
Extra / Additional Extensions
Extra extensions are shipped by Zend and can easily be installed but are not installed by default
in typical installations
Extension Status Description
fileinfo Disabled
Allows retrieval of information regarding many different file types. This
information includes file type and encoding, as well as more specific information
such as dimensions, quality or length
gmp Disabled These functions allow you to work with arbitrary-length integers using the GNU
MP library
imagick Enabled Enables image creation and manipulation using the ImageMagick API
memcache Disabled Provides access to memcached - a highly efficient memory based caching
daemon
ming Disabled Provides a set of functions that can be used to create SWF ("Flash") format
animations; Based on the open-source Ming library
mssql Disabled Provides access to MS SQL Server database; Based on the open-source FreeTDS
library
odbc Disabled Provides access to several database servers through the Unified ODBC interface
pcntl Disabled
Process Control Functions - Process Control support in PHP implements the Unix
style of process creation, program execution, signal handling and process
termination
pdo_dblib Disabled PDO (PHP Data Objects) driver that enable access from PHP to MSSQL and other
databases accessible through the FreeDTS interface
pdo_odbc Disabled
PDO (PHP Data Objects) driver that enable access from PHP to different
databases through ODBC drivers or through the IBM DB2 Call Level Interface
(DB2 CLI) library
pspell Enabled Provides spell checking and dictionary management functionality based on the
pspell library
shmop Disabled Shared Memory - Shmop is an easy-to-use set of functions that allows PHP to
read, write, create and delete Unix shared memory segments
sysvmsg Disabled
Enables System V messages support - The messaging functions may be used to
send and receive messages to/from other processes. They provide a simple and
effective means of exchanging data between processes, without the need for
setting up an alternative using Unix domain sockets
sysvsem Disabled
Enables System V semaphore support - Semaphores may be used to provide
exclusive access to resources on the current machine, or to limit the number of
processes that may simultaneously use a resource
Zend Server 5 for IBM i Reference Manual
164
Extension Status Description
sysvshm Disabled Enables System V shared memory support - Shared memory may be used to
provide access to global variables
wddx Disabled WDDX (Web Distributed Data Exchange) - These functions are intended for work
with the WDDX data exchange format
xmlrpc Disabled Provides a set of functions that can be used to write XML-RPC servers and clients
Standalone Extensions
Standalone extensions are provided by Zend but are not included in any of the meta-packages /
categories above.
Extension Status Description
ibm_db2 Enabled Provides functions that enable you to access the IBM DB2 Universal Database,
IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface
pdo_ibm Enabled PDO (PHP Data Objects) driver that enable access from PHP to IBM databases
Zend Server for IBM i
165
Zend Server Extension List - PHP 5.3
Common Extensions
Common extensions are installed and enabled by default in typical installations
Extension Status Description
bcmath Enabled Arbitrary precision mathematics functions based on the bcmatch (Binary
Calculator) library
bz2 Enabled The bzip2 functions are used to transparently read and write bzip2 (.bz2)
compressed files and streams
calendar Enabled The calendar extension provides functions that simplify conversion between
different calendar formats
Core Built-in Core PHP functionality
Ctype Enabled Character Classifications - Checks whether a character or string falls into a certain
character class according to the current locale
Curl Enabled Enables you to connect to and communicate with different types of servers using
various protocols - for example HTTP and FTP
Date Built-in Enables various date and time related functions that can handle retrieving the
time, date formatting and more
Dom Built-in Enables operating on an XML document using the Document Object Model (DOM)
API
Ereg Built-in Provides a set of string pattern matching functions using POSIX extended regular
expressions.
Exif Enabled Enables access to image EXIF (Exchangeable Image File Format) meta data
fileinfo Enabled
Allows retrieval of information regarding many different file types. This
information includes file type and encoding, as well as more specific information
such as dimensions, quality or length
Filter Built-in Provides a set of functions for validating and filtering data coming from insecure
sources, such as user inputs
ftp Enabled Provides low-level client access to FTP (File Transfer Protocol) servers
Gd Enabled Enables creation, manipulation and streaming of images and graphics in various
formats
gettext Enabled Provides a set of functions that allow internationalization of PHP applications
through the GNU gettext API
Hash Built-in Enables direct or incremental processing of arbitrary length messages using a
variety of hashing algorithms
Zend Server 5 for IBM i Reference Manual
166
Extension Status Description
i5comm Enabled Provides access to all IBM i system resources such as RPG/COBOL/CL programs,
database files / tables, spooled files, data queue and more
Iconv Enabled Enables conversion between different character sets using the iconv library
Imap Enabled Provides mail and news access through the IMAP, POP3 and NNTP protocols
Intl Enabled Provides Unicode and global localization support to PHP applications using the ICU
library
Json Enabled Implements the JavaScript Object Notation (JSON) data-interchange format
Ldap Enabled Provides access to LDAP (Lightweight Directory Access Protocol) based directory
servers; Based on the OpenLDAP library
libxml Built-in Provides basic API and infrastructure for other XML processing extensions
mbstring Enabled Enables manipulation of strings encoded in multi-byte character encoding
schemes
mcrypt Enabled Provides support for multiple encryption algorithms using the mcrypt library
mysql Enabled Provides legacy access to MySQL database servers. For new applications it is
recommended to use the 'mysqli' extension
mysqli Enabled MySQL Improved - Provides access to MySQL database servers. Enables the
functionality provided by MySQL 4.1 and above
openssl Built-in This module utilizes the OpenSSL library for generation and verification of
signatures and for encrypting and decrypting data and streams
Pcre Built-in Provides a set of functions for string matching and manipulation based on Perl
Compatible Regular Expressions syntax
Pdo Built-in Base PDO (PHP Data Objects) Driver - Defines a lightweight, consistent interface
for accessing databases in PHP
pdo_mysql Enabled PDO (PHP Data Objects) driver that enable access from PHP to MySQL database
servers
pdo_oci Enabled PDO (PHP Data Objects) driver that enable access from PHP to Oracle database
servers using the OCI library
pdo_pgsql Enabled PDO (PHP Data Objects) driver that enable access from PHP to PostgreSQL
database servers
pdo_sqlite Built-in PDO (PHP Data Objects) driver that enable access from PHP to SQLite database
files
Pgsql Enabled Provides access to PostgreSQL database servers
Phar Enabled Allows running of complete PHP applications out of .phar package files
Posix Enabled Contains an interface to functions defined in the IEEE 1003.1 (POSIX.1)
standards document which are not accessible through other means
Zend Server for IBM i
167
Extension Status Description
reflection Built-in Adds the ability to reverse-engineer classes, interfaces, functions and methods as
well as extensions
session Built-in Enables data persistence between consecutive requests of the same user session
simplexml Built-in
The SimpleXML extension provides a very simple and easily usable toolset to
convert XML to an object that can be processed with normal property selectors
and array iterators
Soap Enabled The SOAP extension can be used to implement SOAP Servers and Clients
sockets Enabled The socket extension implements a set of low-level socket communication
functions, providing the possibility to act as a socket server as well as a client
Spl Built-in SPL is a collection of interfaces and classes that can be used to solve standard
problems
Sqlite Enabled Enables usage of the SQLite Embeddable SQL Database Engine. Can be used for
SQL database access without running a separate RDBMS process
standard Built-in Standard PHP functions
Tidy Enabled Tidy HTML Clean and Repair - enables you to not only clean and otherwise
manipulate HTML documents, but also traverse the document tree
tokenizer Enabled
The tokenizer functions provide an interface to the PHP tokenizer embedded in
the Zend Engine. Using these functions you may write your own PHP source
analyzing or modification tools without having to deal with the language
specification at the lexical level
Xml Built-in Enables the creation of event-based XML document parsers using the SAX XML
interface
xmlreader Enabled The XMLReader extension is an XML Pull parser. The reader acts as a cursor going
forward on the document stream and stopping at each node on the way.
xmlwriter Enabled Provides a non-cached, forward-only writer for generating streams or files
containing XML data in an efficient manner
Xsl Enabled The XSL extension implements the XSL standard, performing XSLT
transformations using the libxslt library
Zip Enabled ZIP Archives - Enables you to transparently read ZIP compressed archives and
the files inside them
Zlib Built-in
Enables you to transparently read and write gzip (.gz) compressed files, through
versions of most of the filesystem functions which work with gzip-compressed
files
Zend Server 5 for IBM i Reference Manual
168
Extra / Additional Extensions
Extra extensions are shipped by Zend and can easily be installed but are not installed by default
in typical installations
Extension Status Description
gmp Disabled These functions allow you to work with arbitrary-length integers using the GNU
MP library
imagick Enabled Enables image creation and manipulation using the ImageMagick API
memcache Disabled Provides access to memcached - a highly efficient memory based caching
daemon
mssql Disabled Provides access to MS SQL Server database; Based on the open-source FreeTDS
library
odbc Disabled Provides access to several database servers through the Unified ODBC interface
pcntl Disabled
Process Control Functions - Process Control support in PHP implements the Unix
style of process creation, program execution, signal handling and process
termination
pdo_dblib Disabled PDO (PHP Data Objects) driver that enable access from PHP to MSSQL and other
databases accessible through the FreeDTS interface
pdo_odbc Disabled
PDO (PHP Data Objects) driver that enable access from PHP to different
databases through ODBC drivers or through the IBM DB2 Call Level Interface
(DB2 CLI) library
pspell Enabled Provides spell checking and dictionary management functionality based on the
pspell library
shmop Disabled Shared Memory - Shmop is an easy-to-use set of functions that allows PHP to
read, write, create and delete Unix shared memory segments
sysvmsg Disabled
Enables System V messages support - The messaging functions may be used to
send and receive messages to/from other processes. They provide a simple and
effective means of exchanging data between processes, without the need for
setting up an alternative using Unix domain sockets
sysvsem Disabled
Enables System V semaphore support - Semaphores may be used to provide
exclusive access to resources on the current machine, or to limit the number of
processes that may simultaneously use a resource
sysvshm Disabled Enables System V shared memory support - Shared memory may be used to
provide access to global variables
wddx Disabled WDDX (Web Distributed Data Exchange) - These functions are intended for work
with the WDDX data exchange format
xmlrpc Disabled Provides a set of functions that can be used to write XML-RPC servers and clients
Zend Server for IBM i
169
Standalone Extensions
Standalone extensions are provided by Zend but are not included in any of the meta-packages /
categories above.
Extension Status Description
ibm_db2 Enabled Provides functions that enable you to access the IBM DB2 Universal Database,
IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface
pdo_ibm Enabled PDO (PHP Data Objects) driver that enable access from PHP to IBM databases
Zend Server 5 for IBM i Reference Manual
170
Adding Extensions This section includes information for the following Operating Systems:
Zend Server on UNIX/Linux
Zend Server Community Edition on UNIX/Linux/Mac
Zend Server for IBM i
Zend Server for IBM i users can benefit from extension management capabilities for third party
extensions as well as for Zend Extensions. This enables users to load and unload all extensions
directly from the Zend Server for IBM i Extensions page.
Important: The newly added extensions will be visible in the Administration Interface's
Extensions page however, the directive configuration option will not be active and directives
belonging to the extension have to be configured directly from the php.ini file.
Disclaimer: Zend Technologies does not provide support for third party products, including extensions.
Therefore, if an issue for support arises, please remove all third party extensions by commenting
out the reference to them in your php.ini before referring to the Support Center -
http://www.zend.com/en/support-center/.
There are two types of extensions: PHP extensions and Zend extensions. The extension provider
should supply information regarding the extension type (Zend or PHP). Make sure to also check
the provider's documentation for possible compatibility issues, PHP version compatibility and any
other additional configurations that may be required.
To add Zend extensions: 1. Download the extension
Note: Zend Server for IBM i for IBM i - AIX Unix/Linux extensions end with the .so
suffix.
2. Place the extension in your extensions directory.
To locate the extensions directory, open the Administration Interface to Monitor | PHP Info and check the value for the directive extension_dir=.
By default, your extensions directory is located in:
<install_path>/zend/lib/php_extensions
3. Add the following line to your php.ini:
zend_extension=<full_path_to_extension_so_file>
4. Restart your server.
5. To restart your server:
Click Restart Server in the Administration Interface.
Zend Server for IBM i
171
Ensure that the extension is properly loaded by checking the output of PHPInfo in
the Administration Interface.
Note: If you try to load a PHP extension as a Zend extension, in Linux you may receive the following
error message in your server's error log: "<extension_name> doesn't appear to be a valid Zend
extension."
If this occurs, remove it and add it as a PHP extension, following the instructions under "To Add
PHP Extensions", below.
To add PHP extensions 1. Download the third party extension. Many third party extensions can be found at
http://pecl.php.net.
Extensions are obtained directly from external web repositories.
2. Place the PHP extension in your extensions directory.
To locate the extensions directory, open your php.ini and check the value for the
directive extension_dir=.
By default, your extensions directory is located in:
<install_path>/lib/php_extensions
3. Add the following line to your php.ini:
extension=<my_extension_name>.so
Ensure that you replace <my_extension_name> with your extension's name.
4. Restart your Web server.
Ensure that the extension is properly loaded by checking the Administration
Interface: See Monitor | PHP Info for the output of PHP Info.
The extensions appear in your Administration Interface under the Extensions tab and you can use
the Administration Interface to load and unload the extension.
Zend Server 5 for IBM i Reference Manual
172
UNIX: Compiling PHP Extensions forZend Server for IBM i This procedure describes how to compile a PHP extension. Zend Server for IBM i includes over
77 extensions however there still may be a PHP extension that you want to compile by yourself.
Requirements:
PHP Tools:
• PECL (PHP Extension Community Library): PECL is a repository for PHP
extensions, providing a directory of all known extensions and hosting facilities for
download and development of PHP extensions. - It is also a tool supplied in the
form of a small shell script with PHP code behind it to retrieve extensions from
the aforementioned repository.
• phpize: a shell script to generate a configure script for PHP extensions
Build Tools:
While PHP can be built using many different tool chains, this article will focus on using
the GNU tool chain. The main tools where PHP is concerned are:
• autoconf: automatic configure script builder. This is called by the phpize script.
• automake: a tool for generating GNU Standards-compliant Makefiles
• libtool: Generic library support script. Libtool hides the complexity of generating
special library types (such as shared libraries) behind a consistent (sort of :) )
interface.
• GNU make: a GNU tool for controlling the generation of executables and other
non-source files of a program from the program's source files
• GCC: PHP extensions are typically written in C. Hence, in order for them to
compile, you would need a C compiler. While GCC now stands for GNU compiler
Collection and is no longer just a GNU C Compiler, for our purposes we only
need the C part of the collection. GNU's elf-binutils package: The programs in
this package are used to assemble, link and manipulate binary and object files.
Zend Server for IBM i
173
Install the following packages:
Users of distributions with package managers (mainly Debian, Ubuntu, RHEL, CentOS and
Fedora Core and many others) should install the following packages from their distribution's
repository: gcc, make, autoconf, automake and libtool. Some of these tools depend on each
other, for instance the libtool package depends on the gcc package, but no damage can be done
from specifying all of them.
Note: Users who utilize distributions that do not have package managers (Linux from scratch anyone?),
can compile these tools themselves or obtain pre-compiled binaries for them quite easily.
Additionally, you can compile a PHP extension from the main PHP source (as opposed to PECL).
This requires installing a package from the Zend Server for IBM i repository called php-5.2-
source-zend-server or php-5.3-source-zend-server, depending on your Zend Server for IBM i's
major PHP version. This package includes full PHP sources as patched, for security or
optimization concerns, by the Zend development team. This ensures that you are using the exact
same source code we used when building Zend Server for IBM i.
Scenario 1: compile a PECL extension called Newt
Newt is a PHP extension for RedHat's Newt (New Terminal) library, a terminal-based window and
widget library for writing applications with user friendly interfaces.
Being what it is, this extension requires the existence of the Newt library development files. If you
are using Debian or Ubuntu you should install a package called libnewt-dev. On RedHat based
distributions the package name is newt-devel. Make sure these are installed before continuing.
NOTE: Other extensions will have other dependencies. For example, the Mcrypt extension will
require the Mcrypt development package.
NOTE: Since PECL will attempt to write the extension onto /usr/local/zend/lib/php_extensions,
you will have to become a super user to perform this procedure. This is only needed for the actual
make install.
Zend Server 5 for IBM i Reference Manual
174
To compile your own extension:
1. Assuming you have the Newt development package installed, run:
# /usr/local/zend/bin/pecl install newt
The truncated output of this command, along with explanations:
PECL retrieves the package from the repository...*/ downloading newt-1.2.1.tgz Starting to download newt-1.2.1.tgz (24,853 bytes) .........done: 24,853 bytes 5 source files, building /*The phpize script is executed...*/ running: phpize Configuring for: PHP Api Version: 20041225 Zend Module Api No: 20060613 Zend Extension Api No: 220060519 building in /var/tmp/pear-build-root/newt-1.2.1 Configure comes into play running: /tmp/pear/download/newt-1.2.1/configure checking for grep that handles long lines and -e... /bin/grep checking for egrep... /bin/grep -E checking for a sed that does not truncate output... /bin/sed checking for gcc... gcc checking for C compiler default output file name... a.out checking whether the C compiler works... yes checking whether we are cross compiling... no checking for suffix of executables... checking for suffix of object files... o Next comes libtool. creating libtool appending configuration tag "CXX" to libtool configure: creating ./config.status config.status: creating config.h The actual compilation process: calls make which internally triggers GCC and LD. running: make /bin/sh /var/tmp/pear-build-root/newt-1.2.1/libtool --mode=compile gcc -I. -I/tmp/pear/download/newt-1.2.1 -DPHP_ATOM_INC -I/var/tmp/pear-build-root/newt-1.2.1/include -I/var/tmp/pear-build-root/newt-1.2.1/main -I/tmp/pear/download/newt-1.2.1 -I/usr/local/zend/include/php -I/usr/local/zend/include/php/main -I/usr/local/zend/include/php/TSRM -I/usr/local/zend/include/php/Zend -I/usr/local/zend/include/php/ext -I/usr/local/zend/include/php/ext/date/lib -I/usr/local/zend/include/php -DHAVE_CONFIG_H -g -O2 -c /tmp/pear/download/newt-1.2.1/newt.c -o newt.lo mkdir .libs gcc -I. -I/tmp/pear/download/newt-1.2.1 -DPHP_ATOM_INC -I/var/tmp/pear-build-root/newt-1.2.1/include -I/var/tmp/pear-build-root/newt-1.2.1/main -I/tmp/pear/download/newt-1.2.1 -I/usr/local/zend/include/php -I/usr/local/zend/include/php/main -I/usr/local/zend/include/php/TSRM -I/usr/local/zend/include/php/Zend -I/usr/local/zend/include/php/ext -I/usr/local/zend/include/php/ext/date/lib -I/usr/local/zend/include/php -DHAVE_CONFIG_H -g -O2 -c /tmp/pear/download/newt-1.2.1/newt.c -fPIC -DPIC -o .libs/newt.o /bin/sh /var/tmp/pear-build-root/newt-1.2.1/libtool --mode=compile gcc -I. -I/tmp/pear/download/newt-1.2.1 -DPHP_ATOM_INC -I/var/tmp/pear-build-root/newt-1.2.1/include -I/var/tmp/pear-build-root/newt-1.2.1/main -I/tmp/pear/download/newt-1.2.1 -I/usr/local/zend/include/php -I/usr/local/zend/include/php/main -I/usr/local/zend/include/php/TSRM -I/usr/local/zend/include/php/Zend -I/usr/local/zend/include/php/ext -I/usr/local/zend/include/php/ext/date/lib -I/usr/local/zend/include/php -DHAVE_CONFIG_H -g -O2 -c
Zend Server for IBM i
175
/tmp/pear/download/newt-1.2.1/newt_vcall.c -o newt_vcall.lo gcc -I. -I/tmp/pear/download/newt-1.2.1 -DPHP_ATOM_INC -I/var/tmp/pear-build-root/newt-1.2.1/include -I/var/tmp/pear-build-root/newt-1.2.1/main -I/tmp/pear/download/newt-1.2.1 -I/usr/local/zend/include/php -I/usr/local/zend/include/php/main -I/usr/local/zend/include/php/TSRM -I/usr/local/zend/include/php/Zend -I/usr/local/zend/include/php/ext -I/usr/local/zend/include/php/ext/date/lib -I/usr/local/zend/include/php -DHAVE_CONFIG_H -g -O2 -c /tmp/pear/download/newt-1.2.1/newt_vcall.c -fPIC -DPIC -o .libs/newt_vcall.o /bin/sh /var/tmp/pear-build-root/newt-1.2.1/libtool --mode=link gcc -DPHP_ATOM_INC -I/var/tmp/pear-build-root/newt-1.2.1/include -I/var/tmp/pear-build-root/newt-1.2.1/main -I/tmp/pear/download/newt-1.2.1 -I/usr/local/zend/include/php -I/usr/local/zend/include/php/main -I/usr/local/zend/include/php/TSRM -I/usr/local/zend/include/php/Zend -I/usr/local/zend/include/php/ext -I/usr/local/zend/include/php/ext/date/lib -I/usr/local/zend/include/php -DHAVE_CONFIG_H -g -O2 -o newt.la -export-dynamic -avoid-version -prefer-pic -module -rpath /var/tmp/pear-build-root/newt-1.2.1/modules newt.lo newt_vcall.lo -lnewt gcc -shared .libs/newt.o .libs/newt_vcall.o -lnewt -Wl,-soname -Wl,newt.so -o .libs/newt.so creating newt.la (cd .libs && rm -f newt.la && ln -s ../newt.la newt.la) /bin/sh /var/tmp/pear-build-root/newt-1.2.1/libtool --mode=install cp ./newt.la /var/tmp/pear-build-root/newt-1.2.1/modules cp ./.libs/newt.so /var/tmp/pear-build-root/newt-1.2.1/modules/newt.so cp ./.libs/newt.lai /var/tmp/pear-build-root/newt-1.2.1/modules/newt.la PATH="$PATH:/sbin" ldconfig -n /var/tmp/pear-build-root/newt-1.2.1/modules ---------------------------------------------------------------------- Libraries have been installed in: /var/tmp/pear-build-root/newt-1.2.1/modules Build complete.
2. Run 'make test'.
3. Use PECL to put the newly built Newt extension into place.
run: make INSTALL_ROOT="/var/tmp/pear-build-root/install-newt-1.2.1"
4. instal the shared extensions by running:
var/tmp/pear-build-root/install-newt-1.2.1//usr/local/zend/lib/php_extensions/
running: find "/var/tmp/pear-build-root/install-newt-1.2.1" | xargs ls -dils 574096 4 drwxr-xr-x 3 root root 4096 Mar 30 20:45 /var/tmp/pear-build-root/install-newt-1.2.1 574119 4 drwxr-xr-x 3 root root 4096 Mar 30 20:45 /var/tmp/pear-build-root/install-newt-1.2.1/usr 574120 4 drwxr-xr-x 3 root root 4096 Mar 30 20:45 /var/tmp/pear-build-root/install-newt-1.2.1/usr/local 574121 4 drwxr-xr-x 3 root root 4096 Mar 30 20:45 /var/tmp/pear-build-root/install-newt-1.2.1/usr/local/zend 574122 4 drwxr-xr-x 3 root root 4096 Mar 30 20:45 /var/tmp/pear-build-root/install-newt-1.2.1/usr/local/zend/lib 574123 4 drwxr-xr-x 2 root root 4096 Mar 30 20:45 /var/tmp/pear-build-root/install-newt-1.2.1/usr/local/zend/lib/php_extensions 574118 244 -rwxr-xr-x 1 root root 241717 Mar 30 20:45 /var/tmp/pear-build-root/install-newt-1.2.1/usr/local/zend/lib/php_extensions/newt.so Build process completed successfully Installing '/usr/local/zend/lib/php_extensions/newt.so' install ok: channel://pear.php.net/newt-1.2.1
5. The Extension has been successfully compiled using PECL.
6. To load the extension, in the php.ini or in a separate file under the scan dir insert
extension=<my_extension_name>.so and replace <my_extension_name> with
your extension's binary name such as "extension=newt.so".
Zend Server 5 for IBM i Reference Manual
176
7. If you're using the DEB and RPM versions of Zend Server for IBM i, the best
practice is to place a file called newt.ini under /usr/local/zend/etc/conf.d.
8. Restart your webserver.
Ensure the extension is properly loaded by checking the output of PHP Info. This can be viewed
in the Zend Server for IBM i PHP Info page.
The extension will now appear in your Administration Interface under Server Setup | Extensions
from which you can also load and unload the extension (for more information see: Working with
Extensions).
Scenario 2: Compile a PHP extension included in the main PHP source called PSpell
Pspell (Portable Spell Checker Interface Library) provides a generic interface to the system
spelling checking libraries. To compile PSpell first install the php-source-zend-[ce|pe] package for
this procedure. Also, since this extension relies on the portable spell-checking interface (pspell)
library, you will need to install its devel package. Debian and Ubuntu users should install the
libpspell-dev package, on RedHat based distributions, the package name is aspell-devel.
To compile your own extension:
1. CD the extension's source dir (in our example, the PHP version is 5.2.9 as it is
the current stable version Zend Server for IBM i is shipped with):
$ cd /usr/local/zend/share/php-source/php-5.2.9/ext/pspell
2. Run phpize:
$ /usr/local/zend/bin/phpize
The output should be similar to this: /Configuring for: PHP Api Version: 20041225 Zend Module Api No: 20060613 Zend Extension Api No: 220060519/ Run the configure script, generated by phpize: $ ./configure --with-php-config=/usr/local/zend/bin/php-config
3. Run make:
$ make
4. Become a super user [root] and run:
# make install
Zend Server for IBM i
177
The output should be: /Installing shared extensions: /usr/local/zend/lib/php_extensions/
5. Insert the "extension=pspell.so" directive either in php.ini or in a separate file
under the scan dir.
6. Restart your webserver.
Ensure the extension is properly loaded by checking the output of PHP Info. This can be viewed
in the Zend Server for IBM i PHP Info page.
The extension will now appear in your Administration Interface under Server Setup | Extensions
from which you can also load and unload the extension (for more information see: Working with
Extensions).
Troubleshooting:
The configure script outputs messages as it goes along and many times you will be able to
understand the problem just by looking at it, however, sometimes, the error doesn't necessarily
reflect the real issue so it is always a good idea to review the config.log. This is a very generic
statement but no other statement can be made as there are many different extensions and issues
one may come across so attempting to list them all will be somewhat futile.
Zend Server 5 for IBM i Reference Manual
178
Info Messages Zend Server for IBM i displays different types of messages that are color coded according to their
level of severity. The following list describes the four different options and what each color
means:
Error Messages
Messages that are Red indicate that some kind of system error has occurred. If you receive a
message like this follow the instructions in the message.
The recommended actions are:
Follow the instructions in the message.
If the message appeared after an action was performed - try to redo the last action (such
as to click Save, Add etc.).
Visit the Support Center - http://www.zend.com/en/support-center/
Open a Support Ticket - Support
Reinstall Zend Server for IBM i - Choosing Which Distribution to Install
Notices
Messages that are Yellow indicate that a non-critical error occurred. If you receive a message like
this it will contain information on how to proceed. This type of error includes messages to the user
about usability issues.
Success Messages
Messages that are Green indicate the success of an action. If you receive a message like this it
means that your last action was completed successfully and no additional actions are required
(such as Restart Server).
Zend Server for IBM i
179
Info Messages
Messages that are Blue indicate that there is an important message. If you receive a message
like this, in most cases no action is required apart from reading the information
.
For example: Log file C:\Program Files\Zend\Apache2\logs\error.log does not exist or missing read permissions
When this Server Error Log Info Message is displayed, one of the following has occurred:
No log files are available
Files have been moved
Permissions have been tampered with
180
API Reference Introduction The API reference includes reference information for working with the API's. Each page includes
a description of the component along with the functions for interacting with the component and
the directives for configuring the component's behavior as follows:
Zend Debugger
Zend Optimizer+
Zend Guard Loader
Zend Data Cache
Zend Java Bridge
Zend Extension Manager
Zend Utils
Zend Page Cache
Zend Monitor
Zend 5250 Bridge API
Zend Monitor Node
Zend Job Queue:Zend Job Queue Zend Job Queue Daemon
Zend Code Tracing
PHP Toolkit for IBM i
API Reference
181
Zend Debugger The Zend Debugger is a remote debugging tool for developers working with Zend Studio.
The Zend Debugger is an API that communicates with the Zend (PHP) Engine to retrieve runtime
information and reveal it in Zend Studio for debugging purposes.
Note: If your machine has multiple IP addresses, make sure you define all IPs as allowed hosts in
Zend Server.
PHP API Function: debugger_start_debug()
Triggers a debug session from within a script
Returns: Available since: 3.6
Function: boolean debugger_connect()
Initiates a tunnel connection
Returns: TRUE the connection is established or FALSE could not connect
Available since: 3.6
INI Directives: zend_debugger.allow_hosts
Specifies the hosts that are allowed to connect (hostmask list) with Zend Debugger when running
a remote debug session with Zend Studio
Default value(s): 127.0.0.1/32,10.0.0.0/8,192.168.0.0/16,172.16.0.0/12:
Type: string
Measurement units: Available since: 3.6
Zend Server 5 for IBM i Reference Manual
182
zend_debugger.deny_hosts
Specifies the hosts that are not allowed to connect (hostmask list) with the Zend Debugger when
running a remote debug session with Zend Studio
Default value(s): :
Type: string
Measurement units: Available since: 3.6
zend_debugger.allow_tunnel A list of hosts (hostmask list) that can use the machine on which Zend Server is installed to
create a communication tunnel for remote debgging with Zend Studio. This is done to solve
firewall connectivity limitations
Default value(s): :
Type: string
Measurement units: Available since: 3.6
zend_debugger.max_msg_size
The maximum message size accepted by the Zend Debugger for protocol network messages
Default value(s): 2097152:
Type: int
Measurement units: Available since: 3.6
API Reference
183
zend_debugger.httpd_uid
The user ID of the httpd process that runs the Zend Debugger (only for tunneling)
Default value(s): -1:
Type: int
Measurement units: Available since: 3.6
zend_debugger.tunnel_min_port A range of ports that the communication tunnel can use. This defines the minimum value for the
range
Default value(s): 1024:
Type: int
Measurement units: Available since: 3.6
zend_debugger.tunnel_max_port A range of ports that the communication tunnel can use. This defines the maximum value for the
range
Default value(s): 65535:
Type: int
Measurement units: Available since: 3.6
Zend Server 5 for IBM i Reference Manual
184
zend_debugger.expose_remotely
Define which clients know that the Zend Debugger is installed:
0 - Never. The presence of the Zend Debugger is not detected by other clients
1 - Always. All clients can detect the Zend Debugger
2 - Allowed Hosts. Only clients listed in zend_debugger.allow_hosts can detect the Zend
Debugger
Any other value makes the Zend Debugger undetectable (same as "Never")
Default value(s): 2:
Type: int
Measurement units: Available since: 3.6
zend_debugger.passive_mode_timeout The Debugger's timeout period (in seconds) to wait for a response from the client (Zend Studio)
Default value(s): 20:
Type: int
Measurement units: seconds
Available since: 3.6
API Reference
185
Zend Optimizer+ The Zend Optimizer+ is a Zend Server component used to speed PHP execution through opcode
caching
The Zend Optimizer+ is bytecode cache and optimization component.
It improves server performance by storing compiled PHP bytecode in shared memory thus saving
the stages of reading it from the disk and compiling it on second access. Optimizer+ works
exclusively with Apache or FastCGI environments (no CLI or CGI support). One of the chief
Optimizer+ advantages is that it requires little or no configuration.
PHP API Function: boolean accelerator_reset()
Resets the contents of the Optimizer+ shared memory storage.
Note: This is not an immediate action. The shared memory storage is reset when a request
arrives while the shared memory storage is not being used by a script.
Returns: Returns TRUE unless the Optimizer+ is disabled.
Available since: 3.6
External Configuration File: Optimizer+ blacklist file The Optimizer+ blacklist file is a text file that holds the names of files that should not be
accelerated. The file format is to add each filename to a new line. The filename may be a full path
or just a file prefix (i.e., /var/www/x blacklists all the files and directories in /var/www that start with
'x'). Files are usually triggered by one of the following three reasons:
1) Directories that contain auto generated code, like Smarty or ZFW cache.
2) Code that does not work well when accelerated, due to some delayed compile time evaluation.
3) Code that triggers an Optimizer+ bug.
Parameters:
INI Directives: zend_optimizerplus.enable
Optimizer+ On/Off switch. When set to Off, code is not optimized.
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
186
zend_optimizerplus.use_cwd
If set to On, use the current directory as a part of the script key
When this directive is enabled, the Optimizer+ appends the current working directory to the script
key, thus elminating possible collisions between files with the same name (basename).
Disablingthe directive improves performance, but may break existing applications.
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_optimizerplus.validate_timestamps
If enabled, the Optimizer+ checks the file timestamps and updates the cache accordingly.
When disabled, you must reset the Optimizer+ manually or restart the webserver for changes to
the filesystem to take effect.
The frequancy of the check is controlled by the directive "zend_optimizerplus.revalidate_freq"
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_optimizerplus.revalidate_freq
How often to check file timestamps for changes to the shared memory storage allocation.
Default value(s): 2:
Type: int
Measurement units: seconds
Available since: 4.0
API Reference
187
zend_optimizerplus.revalidate_path
Enables or disables file search in include_path optimization
If the file search is disabled and a cached file is found that uses the same include_path, the file is
not searched again. Thus, if a file with the same name appears somewhere else in include_path,
it won't be found. Enable this directive if this optimization has an effect on your applications. The
default for this directive is disabled, which means that optimization is active.
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
zend_optimizerplus.inherited_hack
Enable this hack as a workaround for "can't redeclare class" errors
The Optimizer+ stores the places where DECLARE_CLASS opcodes use inheritance (These are
the only opcodes that can be executed by PHP, but which may not be executed because the
parent class is missing due to optimization). When the file is loaded, Optimizer+ tries to bind the
inherited classes by using the current environment. The problem with this scenario is that, while
the DECLARE_CLASS opcode may not be needed for the current script, if the script requires that
the opcode at least be defined, it may not run. The default for this directive is disabled, which
means that optimization is active.
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_optimizerplus.dups_fix
Enable this hack as a workaround for "duplicate definition" errors
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
188
zend_optimizerplus.log_verbosity_level The verbosity of the Optimizer+ log
All Optimizer+ errors go to the Web server log.
By default, only fatal errors (level 0) or errors (level 1) are logged. You can also enable warnings
(level 2), info messages (level 3) or debug messesges (level 4).
For "debug" binaries, the default log verbosity level is 4, not 1.
Default value(s): 1:
Type: int
Measurement units: Available since: 4.0
zend_optimizerplus.memory_consumption
The Optimizer+ shared memory storage size. The amount of memory for storing precompiled
PHP code in Mbytes.
Default value(s): 64:
Type: int
Measurement units: MBytes
Available since: 4.0
zend_optimizerplus.max_accelerated_files
The maximum number of keys (scripts) in the Optimizer+ hash table
The number is actually the the first one in the following set of prime numbers that is bigger than
the one supplied: { 223, 463, 983, 1979, 3907, 7963, 16229, 32531, 65407, 130987 }. Only
numbers between 200 and 100000 are allowed.
Default value(s): 2000:
Type: int
Measurement units: Available since: 4.0
API Reference
189
zend_optimizerplus.max_wasted_percentage
The maximum percentage of "wasted" memory until a restart is scheduled
Default value(s): 5:
Type: int
Measurement units: %
Available since: 4.0
zend_optimizerplus.consistency_checks
Check the cache checksum each N requests
The default value of "0" means that the checks are disabled. Because calculating the checksum
impairs performance, this directive should be enabled only as part of a debugging process.
Default value(s): 0:
Type: int
Measurement units: Available since: 4.0
zend_optimizerplus.force_restart_timeout How long to wait (in seconds) for a scheduled restart to begin if the cache is not being accessed
The Optimizer+ uses this directive to identify a situation where there may be a problem with a
process. After this time period has passed, the Optimizer+ assumes that something has
happened and starts killing the processes that still hold the locks that are preventing a restart. If
the log level is 3 or above, a "killed locker" error is recorded in the Apache logs when this
happens.
Default value(s): 180:
Type: int
Measurement units: seconds
Available since: 4.0
Zend Server 5 for IBM i Reference Manual
190
zend_optimizerplus.blacklist_filename
The location of the Optimizer+ blacklist file
For additional information, see "Extermal Configuration File", above
Default value(s): :
Type: string
Measurement units: Available since: 4.0
zend_optimizerplus.save_comments
If disabled, all PHPDoc comments are dropped from the code to reduce the size of the optimized
code.
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_optimizerplus.fast_shutdown
If enabled, a fast shutdown sequence is used for the accelerated code
The fast shutdown sequence doesn't free each allocated block, but lets the Zend Engine Memory
Manager do the work.
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
API Reference
191
zend_optimizerplus.optimization_level A bitmask, where each bit enables or disables the appropriate Optimizer+ passes
Default value(s): 0xfffffbbf:
Type: int
Measurement units: Available since: 4.0
zend_optimizerplus.enable_slow_optimizations
Enables or disables the optimization passes that may take significant time, based on an internal
runtime calculation
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
192
Zend Guard Loader The Guard Loader is a Zend extension that loads and runs PHP scripts that are encoded with
Zend Guard)
The default setting is 'On' for this component. If you do not plan to use the Guard Loader to run
code encoded by Zend Guard, set the directive zend_loader.enable = 0. This disables the built-in
auto-loading mechanism.
PHP API Function: boolean zend_loader_enabled()
Checks the Zend Optimizer+ configuration to verify that it is configured to load encoded files
Returns: Returns TRUE if the Guard Loader is configured to load encoded files. Returns FALSE
if the Guard Loader is not configured to load encoded files.
Available since: 4.0
Function: boolean zend_loader_file_encoded()
Returns TRUE if the current file was encoded with Zend Guard or FALSE otherwise. If FALSE,
consider disabling the Guard Loader
Returns: TRUE if Zend-encoded, FALSE otherwise
Available since: 4.0
Function: array zend_loader_file_licensed()
Compares the signature of the running file against the signatures of the license files that are
loaded into the License Registry by the php.ini file. If a valid license file exists, the values of the
license file are read into an array. If a valid license does not exist or is not specified in the php.ini,
it is not entered in the PHP server's license registry. If a valid license that matches the product
and signature cannot be found in the license directory, an array is not created. For information on
the proper installation of a license file, as well as the php.ini directive, see the Zend Guard User
Guide
Returns: Returns an array or FALSE.
If an array is returned, a valid license for the product exists in the location indicated in the php.ini
file.
Available since: 4.0
API Reference
193
Function: string zend_loader_current_file()
Obtains the full path to the file that is currently running. In other words, the path of the file calling
this API function is evaluated only at run time and not during encoding
Returns: Returns a string containing the full path of the file that is currently running
Available since: 4.0
Function: boolean zend_loader_install_license(string license_file, boolean overwrite=0)
Dynamically loads a license for applications encoded with Zend Guard.
Parameters: string license_file - Name of the license file
boolean overwrite - Controls if the function overwrites old licenses for the same product
0=Do not overwrite
1=Overwrite
Returns: TRUE if the license was loaded successfully, FALSE otherwise
Available since: 4.0
Function: string zend_obfuscate_function_name(string function_name)
Obfuscate and return the given function name with the internal obfuscation function
Parameters: string function_name - Name of the function to obfuscate
Returns: Returns the obfuscated form of the given string.
Available since: 4.0
Function: int zend_current_obfuscation_level()
Returns the current obfuscation level support (set by zend_optimizer.obfuscation_level_support)
to get information on the product that is currently running.
Returns: Current obfuscation level
Available since: 4.0
Zend Server 5 for IBM i Reference Manual
194
Function: boolean zend_runtime_obfuscate()
Start runtime-obfuscation support to allow limited mixing of obfuscated and un-obfuscated code
Returns: TRUE if succeeds, FALSE otherwise
Available since: 4.0
Function: string zend_obfuscate_class_name(string class_name)
Obfuscate and return the given class name with the internal obfuscation function
Parameters: string class_name - Name of the class to obfuscate
Returns: Returns the obfuscated form of the given string
Available since: 4.0
Function: array zend_get_id(boolean all_ids=false)
Returns an array of Zend (host) IDs in your system. If all_ids is TRUE, then all IDs are returned,
otherwise only IDs considered "primary" are returned
Parameters: boolean all_ids - If all_ids is TRUE, returns all IDs, otherwise returns only IDs that are considered
"primary"
Returns: Array of host IDs
Available since: 4.0
Function: string zend_loader_version()
Returns Zend Guard Loader version
Returns: Zend Guard Loader version
Available since: 4.0
API Reference
195
INI Directives: zend_loader.enable
Enables loading encoded scripts. The default value is On
If you do not plan to use the Zend Guard Loader to load encoded files, you can slightly improve
performance by adding the zend_loader.enable = 0.
This disables the transparent auto-loading mechanism that is built into the Zend Guard Loader
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_loader.disable_licensing
Disable license checks (for performance reasons)
If you do not need to use any licensing features, you can disable the Zend Guard Loader license
request. Setting this option lowers Guard Loader memory usage and slightly enhances
performance
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
zend_loader.obfuscation_level_support The Obfuscation level supported by Zend Guard Loader. The levels are detailed in the official
Zend Guard Documentation. 0 - no obfuscation is enabled
Default value(s): 3:
Type: int
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
196
zend_loader.license_path
Path to where licensed Zend products should look for the product license. For more information
on how to create a license file, see the Zend Guard User Guide
Default value(s): :
Type: string
Measurement units: Available since: 4.0
API Reference
197
Zend Data Cache The Zend Data Cache API is a set of functions for caching data items or output.
The Zend Data Cache is used for the partial caching of content to your shared memory or disk.
PHP API Function: boolean zend_shm_cache_store(string namespace::key, mixed value, int ttl=0)
Stores a variable identified by key into the cache. If a namespace is provided, the key is stored
under that namespace. Identical keys can exist under different namespaces
Parameters: string namespace::key - The data's key. Optional: prefix with a namespace
mixed value - Any PHP object that can be serialized
int ttl - - Time to live, in seconds. The Data Cache keeps an object in the cache as long as the
TTL is not expired. Once the TTL is expired, the object is removed from the cache
Returns: FALSE if cache storing fails, TRUE otherwise
Available since: 4.0
Function: boolean zend_disk_cache_store(string namespace::key, mixed value, int ttl=0)
Stores a variable identified by a key into the cache. If a namespace is provided, the key is stored
under that namespace. Identical keys can exist under different namespaces
Parameters: string namespace::key - The data key. Optional: prefix with a namespace
mixed value - Any PHP object that can be serialized.
int ttl - - Time to live, in seconds. The Data Cache keeps objects in the cache as long as the TTL
is not expired. Once the TTL is expired, the object is removed from the cache
Returns: FALSE if cache storing fails, TRUE otherwise
Available since: 4.0
Zend Server 5 for IBM i Reference Manual
198
Function: mixed zend_shm_cache_fetch(mixed namespace::key)
Fetches data from the cache. The key can be prefixed with a namespace to indicate searching
within the specified namespace only. If a namespace is not provided, the Data Cache searches
for the key in the global namespace
Parameters: mixed namespace::key - The data key or an array of data keys. Optional for key's name: prefix
with a namespace
Returns: FALSE if no data that matches the key is found, else it returns the stored data, If an
array of keys is given, then an array which its keys are the original keys and the values are the
corresponding stored data values
Available since: 4.0
Function: mixed zend_disk_cache_fetch(mixed namespace::key)
Fetches data from the cache. The key can be prefixed with a namespace to indicate searching
within the specified namespace only. If a namespace is not provided, the Data Cache searches
for the key in the global namespace
Parameters: mixed namespace::key - The data key or an array of data keys. Optional for key's name: prefix
with a namespace
Returns: FALSE if no data that matches the key is found, else it returns the stored data, If an
array of keys is given, then an array which its keys are the original keys and the values are the
corresponding stored data values
Available since: 4.0
API Reference
199
Function: boolean zend_shm_cache_delete(mixed namespace::key)
Finds and deletes an entry from the cache, using a key to identify it. The key can be prefixed with
a namespace to indicate that the key can be deleted within that namespace only. If a namespace
is not provided, the Data Cache searches for the key in the global namespace
Parameters: mixed namespace::key - The data key or an array of data keys. Optional for key's name: prefix
with a namespace
Returns: TRUE on success, FALSE on failure.
Available since: 4.0
Function: boolean zend_disk_cache_delete(string namespace::key)
Finds and deletes an entry from the cache, using a key to identify it. The key can be prefixed with
a namespace to indicate that the key can be deleted within that namespace only. If a namespace
is not provided, the Data Cache searches for the key in the global namespace
Parameters: string namespace::key - The data key or an array of data keys. Optional for key's name: prefix
with a namespace
Returns: TRUE on success, FALSE on failure.
Available since: 4.0
Function: boolean zend_shm_cache_clear(string namespace)
Deletes all entries from all namespaces in the cache, if a 'namespace' is provided, only the
entries in that namespace are deleted
Parameters: string namespace - The data key. Optional: prefix with a namespace
Returns: If the namespace does not exist or there are no items to clear, the function will return
TRUE. The function will return FALSE only in case of error.
Available since: 4.0
Zend Server 5 for IBM i Reference Manual
200
Function: boolean zend_disk_cache_clear(string namespace)
Deletes all entries from all namespaces in the cache, if a 'namespace' is provided, only the
entries in that namespace are deleted
Parameters: string namespace - The data key. Optional: prefix with a namespace
Returns: If the namespace does not exist or there are no items to clear, the function will return
TRUE. The function will return FALSE only in case of error.
Available since: 4.0
INI Directives: zend_datacache.shm.max_segment_size
The maximal size of a shared memory segment
Default value(s): 32: for: WindowsAll , for: linux-i386 , for: linux-x86_64 , for: linux-amd64 ,
2: for: darwin , for: sunos , for: freebsd-i386 , for: freebsd-x86_64 , for: aix-ppc ,
Type: int
Measurement units: MBytes
Available since: 4.0
zend_datacache.shm.memory_cache_size
Amount of shared memory to be used by the cache
Default value(s): 32: for: WindowsAll , for: linux-i386 , for: linux-x86_64 , for: linux-amd64 ,
2: for: darwin , for: sunos , for: freebsd-i386 , for: freebsd-x86_64 , for: aix-ppc ,
Type: int
Measurement units: MBytes
Available since: 4.0
API Reference
201
zend_datacache.disk.save_path
The path for storing cached content to the disk
Default value(s): datacache:
Type: string
Measurement units: Available since: 4.0
zend_datacache.disk.dir_level Directory depth, for storing keys
Default value(s): 2:
Type: int
Measurement units: Available since: 4.0
zend_datacache.enable
Enables the Data Cache. The Data Cache cannot work without this directive. The Data Cache
can be turned on or off from the Administration Interface
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_datacache.apc_compatibility
When enabled, the Data Cache extension registers APC compatibility methods
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
202
API Reference
203
Zend Java Bridge The Java Bridge API is a set of functions used to call Java classes and code from within PHP
The Zend Java Bridge is an extension for integrating Java code in PHP by connecting the PHP
object system with the Java object system
PHP API Class: JavaException is a PHP class that inherits from the default PHP5 class "Exception"
Available since: 3.6
Function: public object JavaException::getCause()
Get the Java exception that led to this exception
Returns: A Java exception object, if there was an exception, NULL otherwise
Available since: 3.6
Function: object java(string class_name, ...)
Creates a Java object
Parameters: string class_name - Class name to create
... - Additional arguments are treated as constructor parameters
Returns: The Java object that was created, NULL otherwise
Available since: 3.6
Function: object java_last_exception_get()
Returns a Java exception object for the last exception that occurred in the script: only the last
exception is stored by the Java Bridge
Returns: Java exception object, if there was an exception, NULL otherwise
Available since: 3.6
Zend Server 5 for IBM i Reference Manual
204
API Reference
205
Function: java_last_exception_clear()
Clears the last Java exception object record from the Java Bridge storage
Returns: Available since: 3.6
Function: java_set_ignore_case(boolean ignore)
Sets the case sensitivity for Java calls when there are mixed cases in your PHP script
Parameters: boolean ignore - If set, the Java attribute and method names are resolved, regardless of case
Returns: Available since: 3.6
Function: java_throw_exceptions(int throw)
Controls if exceptions are thrown on Java exception. When an exception is thrown by a Java
application, this function controls if the exception caught by the PHP code will continue to be
thrown or not (if not, it is stored in the Java Bridge's internal memory)
Parameters: int throw - If true, a PHP exception is thrown when a Java exception happens. If set to FALSE,
use java_last_exception_get() to check for exceptions
Returns: Available since: 3.6
Zend Server 5 for IBM i Reference Manual
206
Function: java_set_encoding(string encoding=UTF-8)
Sets encoding for strings received by Java from the PHP code to verify that the encoding is the
same in the PHP and Java code
Parameters: string encoding - Default encoding type is UTF-8
Returns: Available since: 3.6
Function: java_require(string path)
Includes an additional CLASSPATH/JAR in a PHP script context
Parameters: string path - URL pointing to the location of the Jar file. This function accepts the following
protocols:
https://, http://, file://, ftp://
It can also be a local path: E.g., c:\
Returns: Available since: 3.6
Function: java_reload(string new_jarpath)
Reloads Jar files that were dynamically loaded - on demand
Parameters: string new_jarpath - The path to the Jar files
Returns: Available since: 3.6
API Reference
207
INI Directives: zend_jbridge.server_port The TCP port on which the server is listening
Default is 10001. Must be the same as the server's zend.javamw.port
Default value(s): 10001:
Type: int
Measurement units: Available since: 4.0
zend_jbridge.ints_are_longs
Converts PHP integers into java.lang.Long integers, primarily for 64-bit machines
Translates PHP integer values to java.lang.Long integers (64-bit) instead of java.lang.Integer
integers (32-bit). The default setting is off
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
zend_jbridge.encoding
Sets the encoding type that is passed from PHP to Java
Default value(s): UTF-8:
Type: string
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
208
zend_jbridge.use_java_objects
Uses basic Java objects and does not attempt to convert them to primitives
When set to 0, preserves the current implementation (which converts basic Java objects to
primitives (e.g., java.long.Short to short).
When set to 1 for the Java Bridge, returns Java objects and does not convert them to primitives
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
API Reference
209
Zend Extension Manager The Zend Extension Manager (ZEM) manges all the Zend product line extensions.
Because every Zend extension is compiled for each PHP version, the ZEM selects the proper
extension version, depending on the PHP runtime. In addition, the ZEM exposes the C language
API that reflects all the information for the managed extensions and is responsible for managing
the licences of these extensions
Every INI directive of form 'zend_extension_manager.dir.xxx=yyy' string, where 'xxx' is a reserved
name (see below), is considered to be an extension that should be managed. The 'xxx' is called
'extensionId' and 'yyy' is treated as a path to the subtree, where all the extension compilations are
located. The ZEM always selects the proper version
Because the loading order of extensions is significant, there is a special 'load order' file that
specifies the loading order of managed extensions. If the file is not supplied, the declaration order
in the PHP INI files is significant
All Zend product line extensions can only be loaded by the ZEM.
External Configuration File: load order file
The load order file specifies the extension loading order. This file contains plain text with a single
'extensionId' per line. The extension IDs are not necessarily found in php.ini files. The nonexistent
IDs are not considered, but may be reserved for future use (i.e., system upgrade)
This file should not be modified.
INI Directives:
zend_extension_manager.log_verbosity_level Log message verbosity level.
The default level is usually set to 1, which includes very important information messages, errors
and warnings.
Switch the level to 2 to see the notices. Higher levels (up to 5) are reserved for debug purposes
only.
IMPORTANT: The ZEM is absolutely required to load any Zend extension from the Zend product
line. There is other way to load Zend extensions besides using the ZEM.
Default value(s): 1:
Type: int
Measurement units: Available since: 3.6
Zend Server 5 for IBM i Reference Manual
210
zend_extension_manager.load_order_file
The path to the location of the load file. The load file contains the information about the
extensions' loading order
The file should be in plain text. Each line should list only one extensionId. The order of lines
(extensionIds) determines the the order of loading the appropriate extensions. If a particular
extensionId is not managed in any INI file, the ID is skipped.
Default value(s): zem_order:
Type: string
Measurement units: Available since: 3.6
zend_extension_manager.activate_signal_handlers
UNIX only: Activates SIGSEGV and SIGABRT signal handlers.
If enabled, the stack trace is printed when the signal is received. This directive can be combined
with 'zend_extension_manager.wait_for_debugger'.
Default value(s): false:
Type: boolean
Measurement units: Available since: 3.6
zend_extension_manager.wait_for_debugger UNIX only: Automatically pauses the process received by SIGSEGV and SIGABRT.
If enabled, the process is paused when the signal is received, so that 'gdb' can be easily
attached. 'zend_extension_manager.activate_signal_handlers' must be enabled.
Default value(s): false:
Type: boolean
Measurement units: Available since: 3.6
API Reference
211
Zend Utils The Zend Utils extension is used to expose the Zend Extension Manager's functionality via a
PHP API.
Because the Zend Extension Manager (ZEM) is PHP-neutral, it only exposes a C-language API.
The Zend Utils extension takes you one step further and makes the ZEM's API usable from a
PHP runtime environment.
INI Directives: zend_utils.log_verbosity_level Sets the log verbosity level of Zend Utilis logs [0-5]
Verbosity_level for most components that have a log (except Zend Debugger, Zend Guard
Loader and Optimizer+):
0-ZERROR (is always be displayed - indicates an error that can't be recovered)
1-ZWARNING (displays a warning - indicates a warning (recoverable error) that the application
can still run with)
2-ZNOTICE (displays a notice - indicates that something wrong has happened)
3-ZDBG1 (debug purposes only - high priority messages)
4-ZDBG2 (debug purposes only - medium priority messages)
5-ZDBG3 (debug purposes only - low priority messages)
Default value(s): 0:
Type: int
Measurement units: Available since: 4.0
zend_utils.use_graceful_restart Restart API uses a graceful restart
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
212
Zend Page Cache The Zend Page Cache component is used to cache the entire output of PHP scripts without
changing the PHP code.
The Zend Page Cache improves PHP application performance by caching the entire output of
PHP scripts (HTML, XML, etc.) while still maintaining dynamic capabilities through an elaborate
rules system. Rules are configured in the Zend Server Administration Interface.
PHP API Function: page_cache_disable_caching()
Disables output caching for the current request. This overrides any caching settings that are
configured for the current request.
Returns: Available since: 4.0
Function: page_cache_disable_compression()
Does not allow the cache to perform compression on the output of the current request. This
overrides any compression settings that are configured for this request.
Returns: Available since: 4.0
Function: page_cache_remove_cached_contents(string URL)
Clears cached contents for all requests that match a specific URL or regular expression
Parameters: string URL - The URL or regular expression
Returns: Available since: 4.0
API Reference
213
Function: page_cache_remove_all_cached_contents()
Clears all cached contents
Returns: Available since: 4.0
INI Directives: zend_pagecache.enable
Enables the Zend Page Cache extension
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_pagecache.save_path
Location where the cache files are saved. This must point to an existing location.
Default value(s): pagecache:
Type: string
Measurement units: Available since: 4.0
zend_pagecache.dir_depth
Depth of directory tree in which cached files are stored
Default value(s): 2:
Type: int
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
214
zend_pagecache.log_verbosity_level The log verbosity level [0-5]
The extension's log verbosity level. Level 1 includes very important information messages, errors
and warnings. Level 2 displays notices. Greater levels (up to 5) are reserved for debug purposes
Default value(s): 0:
Type: int
Measurement units: Available since: 4.0
zend_pagecache.dependencies_file
The location of the configuration file in which caching rules are stored
Default value(s): page_cache_deps.xml:
Type: string
Measurement units: Available since: 4.0
zend_pagecache.compression_enable
Enables file compression of cached output
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_pagecache.clean_frequency
How often expired entries are removed from the cache. The cleaning frequency is configured in
seconds
Default value(s): 300:
Type: int
Measurement units: seconds
Available since: 4.0
API Reference
215
zend_pagecache.log_rotation_size
The maximum size of the log file before it is rotated
The maximum size of the log file before it is rotated
Default value(s): 10:
Type: int
Measurement units: MBytes
Available since: 4.0
Zend Server 5 for IBM i Reference Manual
216
Zend Monitor The Zend Monitor component is integrated into the runtime environment and serves as an
alerting and collection mechanism for information regarding PHP script problems.
Zend Monitor is a Zend Server component that integrates into the PHP runtime environment and
watches for various events, such as errors, failing functions, slow scripts, database errors, etc.
When an event occurs, the Zend Monitor collects and reposrts all the relevant debugging
information. This information can then be used for debugging and root cause analysis.
PHP API Constant: int ZEND_MONITOR_EVENT_ALL
All event types are reported (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_NONE
No events are reported, except for custom events (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_CUSTOM
Custom event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_SLOWFUNC
Slow function execution event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_FUNCERROR
Function error event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_SLOWSCRIPT
Slow script execution event (for monitor_event_reporting)
Available since: 4.0
API Reference
217
Constant: int ZEND_MONITOR_EVENT_SLOWSCRIPT_REL
Relative slow script execution event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_MEMUSAGE
High memory usage event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_MEMUSAGE_REL
Relative high memory usage event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_OUTPUTSIZE
Large output size event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_PHPERROR
PHP error event (for monitor_event_reporting)
Available since: 4.0
Constant: int ZEND_MONITOR_EVENT_JAVAEX
Java exception event (for monitor_event_reporting)
Available since: 4.0
Zend Server 5 for IBM i Reference Manual
218
Function: monitor_pass_error(int errno, string errstr, string errfile, int errline)
Passes an error to the Monitor component with file and line details. This function is used in error
handlers. An alternative is to use trigger_error. However, this function does not indicate the file
name and line number: It only passes the error message.
Parameters: int errno - Error code
string errstr - Error string
string errfile - Error file
int errline - Error Line
Returns: Available since: 4.0
Function: monitor_custom_event(string class, string text, mixed user_data)
Creates a special (custom) event that is generated from your code. The information collected
consists of the three following parameters: Class, Text and User Data.
Parameters: string class - event type
string text - string to appear in the event
mixed user_data - optional. Any additional data to store with the event
Returns: Available since: 4.0
API Reference
219
Function: void monitor_set_aggregation_hint(string hint)
Incorporates the locations of occurrences in the script when there are events that require those
location for diagnosing the reason an event occured. Only events of the same type are
aggregated. The collected information is viewed in the Zend Server Administration Interface.
Parameters: string hint - aggregation hint string
Returns: Available since: 4.0
Function: int monitor_event_reporting(int new_error_reporting=null)
Enables or disables the event reporting of some event types by passing a bit-mask (as is done in
PHP error_reporting), but with the constants listed above, in ZEND_MONITOR_EVENT*.
Note: You cannot enable events that are disabled in the Event Rules file
Parameters: int new_error_reporting - The new error reporting to use
Returns: The previous error_reporting or FALSE if there is an error
Available since: 4.0
INI Directives: zend_monitor.enable
Enables or disables the Monitor component. This can also be done from the Zend Server
Administration Interface. When set to On, the Monitor collects information to be displayed as
events in Zend Server. When set to Off, the PHP is not monitored at all
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
220
zend_monitor.log_verbosity
Log's Verbosity Level
The extension's log verbosity level. Level 1 includes very important information messages, errors
and warnings. Level 2 displays notices. Greater levels (up to 5) are reserved for debug purposes
Default value(s): 2:
Type: int
Measurement units: Available since: 4.0
zend_monitor.log_rotation_size
The maximum size of the log file before it is rotated
The maximum size of the log file before it is rotated
Default value(s): 10:
Type: int
Measurement units: MBytes
Available since: 4.0
zend_monitor.shm_size
How much shared memory to allocate for event collection. If you exceed the allocated memory,
an error message is reported to the log.
Default value(s): 4194304: for: WindowsAll ZenithPE , for: linux-i386 ZenithPE , for: linux-x86_64 ZenithPE , for:
linux-amd64 ZenithPE ,
2097152: for: darwin ZenithPE , for: sunos ZenithPE , for: freebsd-i386 ZenithPE , for: freebsd-
x86_64 ZenithPE , for: aix-ppc ZenithPE ,
Type: int
Measurement units: Available since: 4.0
API Reference
221
zend_monitor.max_shm_segment_size
The maximum size of a shared memory segment
Default value(s): 4194304: for: WindowsAll ZenithPE , for: linux-i386 ZenithPE , for: linux-x86_64 ZenithPE , for:
linux-amd64 ZenithPE ,
2097152: for: darwin ZenithPE , for: sunos ZenithPE , for: freebsd-i386 ZenithPE , for: freebsd-
x86_64 ZenithPE , for: aix-ppc ZenithPE ,
Type: int
Measurement units: Available since: 4.0
zend_monitor.events_transport_parameter Network Parameter for Event Reporting to the Monitor Node.
The Network Parameter is used for communication for event reporting between the Monitor Agent
and the Monitor Node (IPC communication)
Default value(s): events.sock: for: UnixAll ZenithPE ,
events: for: WindowsAll ZenithPE ,
Type: string
Measurement units: Available since: 4.0
zend_monitor.report_super_globals
Superglobals to include in an event report.
Which PHP Superglobal variables should be included an event report.
The possible options are:
(P)post
(R)raw post data
(G)get
(C)cookies
(V)server
(F)files
(E)env
(S)session
Default value(s): PRGCVF:
Zend Server 5 for IBM i Reference Manual
222
Type: string
Measurement units: Available since: 3.6
zend_monitor.super_globals_to_secure
Superglobals to secure prior to reporting
Which PHP Superglobal variables should be secured, i.e., passed through a security filter prior to
being included in an event report.
The possible options are:
(P)post
(R)raw post data
(G)get
(C)cookies
(V)server
(F)files
(E)env
(S)session
The Super_globals_to_secure directive is directly related to the security_black_list directive,
below. The two directives respectively indicate which superglobals should be secured (as
specified in super_globals_to_secure), and which keys of the superglobal are secured (as
specified in monitor_black_list) - that is, which keys are replaced with the string:
<BLOCKED_VALUE>
Default value(s): PRGCVF:
Type: string
Measurement units: Available since: 3.6
API Reference
223
zend_monitor.security_black_list A comma-separated list of Keywords or the path to a file (with '@' as preffix)that lists the keyword
values to exclude. Each value in the file must be written in a new line (do not use commas as a
separator). If specified as a list or in the file the keyword values will NOT be displayed in Issues
The Keywords are detected from the Super Globals, and its value will be hidden. For example: if
one of the keywords is 'password', this word is searched in all of the Super Globals and the value
pointed by 'password' will be hidden and replaced with the string: <BLOCKED_VALUE>
Default value(s): :
Type: string
Measurement units: Available since: 3.6
zend_monitor.max_super_globals_string_len
The maximum length of a superglobal to include in an event report
When the string is passed, any characters that exceed the limit are truncated and '...' is appended
to the end of the string the end, to indicate that this is a partial value.
Default value(s): 100:
Type: int
Measurement units: Available since: 3.6
zend_monitor.event.request_slow_exec.disabled_on_function_slow_exec_event Disables Slow Request Execution events after Slow Function Execution Events are triggered.
This prevents the Monitor from creating an additional Event Report containing the details of the
same request.
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
224
zend_monitor.event.request_slow_exec.disabled_on_high_load.threshold
Sets the load level to disable Slow Request Execution events for the same request that already
triggered a high load event.
Default value(s): 0:
Type: int
Measurement units: Available since: 4.0
zend_monitor.event.request_relative_slow_exec.min_exec_time
The minimum request execution time for a relativity check.
The minimum execution time for a request to be compared to the average request execution time.
Default value(s): 100:
Type: int
Measurement units: milliseconds
Available since: 4.0
zend_monitor.event.request_relative_large_mem_usage.min_mem_usage
The minimum request memory usage for a relativity check
The minimum memory usage of a request to be compared to the average request memory usage.
Default value(s): 100:
Type: int
Measurement units: KBytes
Available since: 4.0
zend_monitor.event.request_relative_large_output_size.min_output_size
The minimum request output size for a relativity check
The minimum output size of a request to be compared to the average request output size.
Default value(s): 100:
Type: int
Measurement units: KBytes
Available since: 4.0
API Reference
225
zend_monitor.event.zend_error.silence_level This directive controls the Monitor behavior when the silence operator (@) or error_reporting(0)
directives are set
The values are:
0: PHP warnings and errors are reported.
1: PHP warnings and errors are *not* reported.
2: PHP warnings and errors are reported even after error_reporting(0) is set, but not when the
silence operator (@) is used
Default value(s): 1:
Type: int
Measurement units: Available since: 4.0
zend_monitor.requests_statistics.warmup_requests
How many requests to run before deviation events are calculated (to collect data for the average).
This is used to calculate averages for relative events.
Default value(s): 500:
Type: int
Measurement units: Available since: 4.0
zend_monitor.requests_statistics.request_lifetime
How long to wait (in seconds) before statistics are reset if a request is not called
How long (in seconds) to hold statistics in memory. If a request is not called within that time
period, the statistics are reset
Default value(s): 300:
Type: int
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
226
zend_monitor.events_rules_xml_file_name
Event rules XML configuration file.
The name and path to the XML file that contains the defininitons for event rules and actions. This
file should not be edited manually
Default value(s): events_rules.xml:
Type: string
Measurement units: Available since: 4.0
zend_monitor.use_fast_timestamp
Enables fast time sampling which is dependent on CPU cycles and frequency, otherwise, the
directive uses operating system timing (which may be less accurate)
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
API Reference
227
Zend 5250 Bridge API Contents:
Zend 5250 Bridge Object Oriented API
Zend 5250 Bridge Procedural API Functions
Zend 5250 Bridge Use Case Examples
The 5250 Bridge APIs have two interfaces: object oriented and procedural functions. If a
developer is not comfortable using object oriented (class access) methods in PHP he can use
regular procedural functions to access the same APIs.
Zend 5250 Bridge Object Oriented API
'Zend_5250' Class
The 'Zend_5250' is the main class that manages communication with the 5250 Session and
interfaces with 5250 screen information. It includes connection methods, methods to submit
commands, and function key action methods.
The Zend_5250 class uses the following:
The exception class, 'Zend_5250_Exception' for error handling.
The 'Zend_5250_Handler_Session' class by default to save the bridge connections (job
id) and the XML string between requests.
The Zend_5250_Handler interface (can be implemented) to replace the default handler in
the 'Zend_5250'.
The main class returns a Zend_5250_Response object in connection and submit
requests. This object contains information about the page: input and output fields,
focused field and application error.
The Zend_5250_Response object returns input and output fields as
Zend_FieldData_Input and Zend_FieldData_Output objects that contain id, row, column,
length, color, value.
<?php class Zend_5250 { /** * @param string $jobId * @param Zend_5250_Handler $storageHandler If not set, a default (session based) storage will be used */ public function __construct($jobId = null, Zend_5250_Handler $storageHandler = null) { } /** * Returns true if the bridge was already connected, othewise - false
Zend Server 5 for IBM i Reference Manual
228
* * @return boolean */ public function isConnected() { } /** * Create a connection to 5250 bridge and fetch the current stage (either from the bridge or from the storage) * * @param string $username * @param string $password * @return Zend_5250_Response */ public function connect($username = '', $password = '') { } /** * Sends a request to the 5250 bridge * Once user sets all desired data in the input fields (using the setInputField() method), this function * should be called with the command the user has selected (command, can be one of the 'F' keys, enter, * page up, etc.) * @param string $command * @return Zend_5250_Response */ public function submit($command = Zend_5250::ENTER) { } /** * Disconnecting from 5250 bridge (closing connection to application) */ public function disconnect() { } /** * Sets data into input field specified by $id * @param int $id * @param string $value */ public function setInputField($id, $value) { } /** * Sets the focus of the page to a specified field * * @param Zend_FieldData $fieldData */ public function setFocusedField(Zend_FieldData $fieldData) { } /** * Returns the screen size, width x height * * @return array with 2 elements: height and width */ public function getScreenSize() { } /** * Returns an array containing the i5 5250 Bridge color palette * Color code is the key of the array and the color name is the value * * @static * @return array */ public static function getColorPalette() { } const F1 = 'F1'; const F2 = 'F2'; const F3 = 'F3'; const F4 = 'F4'; const F5 = 'F5'; const F6 = 'F6';
API Reference
229
const F7 = 'F7'; const F8 = 'F8'; const F9 = 'F9'; const F10 = 'F10'; const F11 = 'F11'; const F12 = 'F12'; const F13 = 'F13'; const F14 = 'F14'; const F15 = 'F15'; const F16 = 'F16'; const F17 = 'F17'; const F18 = 'F18'; const F19 = 'F19'; const F20 = 'F20'; const F21 = 'F21'; const F22 = 'F22'; const F23 = 'F23'; const F24 = 'F24'; const CLEAR = 'CLEAR'; const ENTER = 'ENTER'; const HELP = 'HELP'; const PAGEDN = 'PAGEDN'; const PAGEUP = 'PAGEUP'; const ROLLLF = 'ROLLLF'; const ROLLRT = 'ROLLRT'; const PRINTKEY = 'PRINT'; const BACKSP = 'BACKSP'; const FORWARD = 'FORWARD'; }?>
'Zend_5250_Handler' Interface
Interface for saving 5250 bridge XML strings. The entire communication between the 5250
session and PHP is done via an XML file that has to be saved between requests in order to
maintain a session with IBM i. The implementation of this interface allows this. The user can
implement this interface in case the default handler provided by Zend is not sufficient, and the
user wants to save XML strings using a different method. <?php interface Zend_5250_Handler { /** * Sets a unique job ID that will be used for storing session data * * @param string $jobId */ public function setJobId($jobId); /** * Returns whether or not a stage (XML string) is stored in this storage * * @return bool */ public function isStored(); /** * Returns the XML string * * @return string */ public function getXmlString(); /** * Sets the XML string * @param string $value */ public function setXmlString($value);
Zend Server 5 for IBM i Reference Manual
230
/** * Unsetting XML string saved so far */ public function destroy(); }?>
'Zend_5250_Response' Class
This Class contains information about the page: input and output fields, focused field and
application error. <?php class Zend_5250_Response { /** * Create a response object for a 5250 bridge request * @param array $inputFields * @param array $outputFields * @param Zend_FieldData|false $focusedField * @param string $applicationError */ public function __construct($inputFields, $outputFields, $focusedField, $applicationError) { } /** * Returns all input fields available at this stage * @return array of Zend_FieldData_Input objects */ public function getInputFields() { } /** * Return input field specified by the given ID * @param int $id * @return Zend_FieldData_Input */ public function getInputField($id) { } /** * Returned the input field currently in focus * @return False/Zend_FieldData_Output in case of no input fields the return value is false */ public function getFocusedField() { } /** * Returns the number of input fields available in this stage * @return int */ public function getInputFieldsCount() { } /** * Return all the output fields available at this stage * @return array of Zend_FieldData_Output objects */ public function getOutputFields() { } /** * Return output field specified by the given ID * @param int $id * @return Zend_FieldData_Output */ public function getOutputField($id) { } /**
API Reference
231
* Returns the number of output fields available in this stage * @return int */ public function getOutputFieldsCount() { } /** * Returns the string of application error or empty string * * @return string */ public function getApplicationError() { } } }?>
'Zend_FieldData_Output' Class
This Class contains information about the output field data: id, row, column, length, color and
value. <?php /** * The Zend_FieldData_Output class represents the output field */ class Zend_FieldData_Output extends Zend_FieldData { }?>
'Zend_FieldData_Input' Class
This Class contains information about the input field data: id, row, column, length, color, value,
font, type and format. <?php class Zend_FieldData_Input { /** * Saves the field's data * * @param integer $id * @param SimpleXMLElement $field */ public function __construct($id, SimpleXMLElement $field) { } /** * @return string */ public function getType() { } /** * @return string */ public function getFont() { } /** * @return string */ public function getFormat() { } ?>
Zend Server 5 for IBM i Reference Manual
232
'Zend_FieldData' Class
This is an abstract class that contains the common data of input and output fields, which are id,
row, column, length, color and value. <?php abstract class Zend_FieldData { public function __construct($id, SimpleXMLElement $field); /** * @return int The unique ID of this field data */ public function getId() { } /** * @return int Height position of the field in the page */ public function getRow() { } /** * @return int Width position of the field in the page */ public function getColumn() { } /** * @return int The length of this field value */ public function getLength() { } /** * @return int Color code as appear in the color pallete */ public function getColor() { } /** * @return string This field value */ public function getValue() { } } ?>
API Reference
233
Zend 5250 Bridge Procedural API Functions The procedural functions are a collection of functions allowing access to the same 5250 Bridge
API as the object oriented classes.
The procedural API is a collection of functions that wrap the real object oriented API.
zend_5250_open($jobId = null) Description: Starts a session according to the provided job id.
Return Values: @return Zend_5250_Resource_Connection
Parameters:
@param string $jobId
zend_5250_connect($connection, $username = '', $password = '') Description: Creates a connection to the 5250 Bridge with the provided username, password
and library.
Return Values: @return Zend_5250_Response
Parameters:
@param Zend_5250_Resource_Connection $connection
@param string $username
@param string $password
@param string $lib
zend_5250_is_connected($connection); Description: Returns true if the bridge was already connected, otherwise - false
Return Values: @return boolean
Parameters:
@param Zend_5250_Resource_Connection $connection
Zend Server 5 for IBM i Reference Manual
234
zend_5250_submit($connection, $command = 'ENTER'); Description: Sends a request to the 5250 bridge. Once the user sets all desired data in the input
fields (using the setInputField() method), this function should be called with the command the
user has selected (commands, can be one of the 'F' keys, enter, page up, etc.)
Return Values: @return Zend_5250_Response
Parameters:
@param Zend_5250_Resource_Connection $connection
@param string $command
zend_5250_disconnect($connection) Description: Disconnects the 5250 bridge (closing the connection to the application)
Return Values:
Parameters:
@param Zend_5250_Resource_Connection $connection
zend_5250_set_input_field($connection, $id, $value); Description: Sets data into an input field specified by $id
Return Values:
Parameters:
@param Zend_5250_Resource_Connection $connection
@param int $id
@param mixed $value
zend_5250_set_focused_field($connection, $filed); Description: Sets the focus of the page to a specified field
Return Values:
Parameters:
@param Zend_5250_Resource_Connection $connection
@param array $field
API Reference
235
zend_5250_get_screen_size($response) Description: Returns the size of the screen, width x height
Return Values: @return array with 2 elements: height and width
zend_5250_get_color_palette(); Description: Returns an array containing the i5 5250 Bridge color palette Color code is the key of
the array and the color name is the value
Return Values: @return array
zend_5250_get_input_fields($response); Description: Returns all input fields available at this stage
Return Values: @return array of arrays
Parameters:
@param Zend_5250_Response $response
zend_5250_get_input_field($response, $id); Description: Returns an input field specified by the given ID
Return Values: @return array
Parameters:
@param Zend_5250_Response $response
@param int $id
zend_5250_get_focused_field($response); Description: Returns the field currently in focus
Return Values: @return array
Parameters:
@param Zend_5250_Response $response
zend_5250_get_input_fields_count($response); Description: Returns the number of input fields available at this stage
Return Values: @return int
Parameters:
@param Zend_5250_Response $response
Zend Server 5 for IBM i Reference Manual
236
zend_5250_get_output_fields($response) Description: Returns the number of output fields available at this stage
Return Values: @return array of arrays
Parameters:
@param Zend_5250_Response $response
zend_5250_get_output_field($response, $id); Description: Returns an output field specified by the given ID
Return Values: @return array
Parameters:
@param Zend_5250_Response $response
@param int $id
zend_5250_get_output_fields_count($response); Description: Returns the number of output fields available in this stage
Return Values: @return int
Parameters:
@param Zend_5250_Response $response
zend_5250_get_application_error($response); Description: Returns an application error if it occurred
Return Values: @return string
Parameters:
@param Zend_5250_Response $response
@param Zend_5250_Response $response
zend_5250_get_error()
Description: Returns a function error if it occurred
Return Values: @return string
API Reference
237
Zend 5250 Bridge Use Case Examples The following code samples demonstrate how to perform various functions using the 5250 Bridge
API, using both Procedural functions and Object Oriented methods.
Use Case 1
The following is sample code for starting and logging on to a 5250 session:
Procedural <?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/5250/Zend_ProceduralApi.php'); $connection = zend_5250_open(); zend_5250_connect($connection); zend_5250_set_input_field($connection ,'0','user'); zend_5250_set_input_field($connection ,'1','password'); // press ENTER zend_5250_submit($connection); zend_5250_disconnect($connection); ?> Object Oriented <?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/5250.php'); $bridge = new Zend_5250(); $response = $bridge->connect(); $bridge->setInputField('0','user'); $bridge->setInputField('1','password'); // press ENTER $response = $bridge->submit(); $bridge->disconnect(); ?>
Use Case 2
The following is sample code for running the "WRKSYSVAL" command in a 5250 session:
Procedural <?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/5250/ProceduralApi.php'); $connection = zend_5250_open(); $response = zend_5250_connect($connection); zend_5250_set_input_field($connection ,'0','user'); zend_5250_set_input_field($connection ,'1','password'); // press ENTER zend_5250_submit($connection); $output_field = zend_5250_get_output_field($response, 5); if (trim($output_field['value']) == 'Press Enter to continue.') { $response = zend_5250_submit($connection); } // get focused field $focusedField = zend_5250_get_focused_field($response); // set input field #0 to 'wrksysval' zend_5250_set_input_field($connection, 0, 'wrksysval'); // press ENTER zend_5250_submit($connection);
Zend Server 5 for IBM i Reference Manual
238
// press EXIT zend_5250_submit($connection, Zend_5250::F12); zend_5250_disconnect($connection); ?> Object Oriented <?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/5250.php'); $bridge = new Zend_5250(); $response = $bridge->connect(); $bridge->setInputField('0','user'); $bridge->setInputField('1','password'); // press ENTER $response = $bridge->submit(); if (trim($response->getOutputField(5)->getValue()) == 'Press Enter to continue.') { $response = $bridge->submit(); } // get focused field $focusedField = $response->getFocusedField(); // set input field #0 to 'wrksysval' $bridge->setInputField(0, 'wrksysval); // press ENTER $response = $bridge->submit(); // press EXIT $response = $bridge->submit(Zend_5250::F12); $bridge->disconnect(); ?>
Use Case 3
The following is sample code for running a ’"multi-request", where 2 different 5250 sessions are
run in parallel from the same PHP application:
Procedural <?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/5250/ProceduralApi.php'); $connection1 = zend_5250_open(1); $response = zend_5250_connect($connection1); zend_5250_set_input_field($connection1 ,'0','user'); zend_5250_set_input_field($connection1 ,'1','password'); // press ENTER zend_5250_submit($connection1); $connection2 = zend_5250_open(2); $response = zend_5250_connect($connection2); zend_5250_set_input_field($connection2 ,'0','user'); zend_5250_set_input_field($connection2 ,'1','password'); // press ENTER zend_5250_submit($connection2); zend_5250_disconnect($connection1); zend_5250_disconnect($connection2); ?> Object Oriented <?php set_include_path('/usr/local/zendsvr/5250/API/'); require_once('Zend/5250.php'); $bridge1 = new Zend_5250(1); $response = $bridge1->connect(); $bridge1->setInputField('0','user'); $bridge1->setInputField('1','password'); $response = $bridge1->submit(); $bridge2 = new Zend_5250(2); $response = $bridge2->connect(); $bridge2->setInputField('0','user'); $bridge2->setInputField('1','password'); $response = $bridge2->submit();
API Reference
239
$bridge1->disconnect(); $bridge2->disconnect(); ?>
Zend Server 5 for IBM i Reference Manual
240
Zend Monitor Node Daemon The Zend Monitor Node Daemon is the node events collector
INI Directives:
zend_monitor.global_directives_ini_file
Global Directives ini File
The .ini file that contains the global directives, as defined in ZendGlobalDirectiveDD.xml
Default value(s): GLOBAL_DIRECTIVES_INI_FILE:
Type: string
Measurement units: Available since: 4.0
zend_monitor.log_verbosity
The Log's verbosity level
The Log's verbosity level
Default value(s): 2:
Type: int
Measurement units: Available since: 4.0
zend_monitor.log_rotation_size
The maximum size of the log file before it is rotated
The maximum size of the log file before it is rotated
Default value(s): 10:
Type: int
Measurement units: MBytes
Available since: 4.0
API Reference
241
zend_monitor.events_rules_xml_file_name
Events Rules XML File Name. For the full path, concatenate it with zend.conf_dir value
The name of the file that contains the XML for the Events Rules and Actions
Default value(s): events_rules.xml:
Type: string
Measurement units: Available since: 4.0
zend_monitor.smtp_server SMTP server
The SMTP server to use to send event mails
Default value(s): :
Type: string
Measurement units: Available since: 4.0
zend_monitor.smtp_port SMTP Port
The SMTP Port that the SMTP server uses to send event mails
Default value(s): 25:
Type: int
Measurement units: Available since: 4.0
zend_monitor.sendmail_from
Send Mail From email Address
An email address to be used as the 'from mail' for Event mails
Default value(s): :
Type: string
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
242
zend_monitor.gui_host_name
Host name (and port) of the Zend Server GUI
This host name is used to build a link to an issue when the user is notified of the issue
Default value(s): :
Type: string
Measurement units: Available since: 4.0
zend_monitor.max_events_queue_size
Maximum size of the Events Queue
The maximum size of the Received Events queue. If events are received beyond the maximum
size, the incoming events are dropped out
Default value(s): 30:
Type: int
Measurement units: MBytes
Available since: 4.0
API Reference
243
Zend Job Queue
PHP API Class: ZendJobQueue is a PHP class that implements a connection to the Job Queue daemon
Available since: 4.1
Constant: int TYPE_HTTP
Type of HTTP job with absolute URL
Available since: 4.1
Constant: int TYPE_HTTP_RELATIVE
Type of HTTP job with relative URL
Available since: 4.1
Constant: int TYPE_SHELL
Type of SHELL job
Available since: 4.1
Constant: int PRIORITY_LOW
Low priority job
Available since: 4.1
Constant: int PRIORITY_NORMAL
Normal priority job
Available since: 4.1
Constant: int PRIORITY_HIGH
High priority job
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
244
Constant: int PRIORITY_URGENT
Urgent priority job
Available since: 4.1
Constant: int STATUS_PENDING
Job is waiting to be processed
Available since: 4.1
Constant: int STATUS_WAITING_PREDECESSOR
Job is waiting for its predecessor's completion
Available since: 4.1
Constant: int STATUS_RUNNING
Job is executing
Available since: 4.1
Constant: int STATUS_COMPLETED
Job execution completed successfully
Available since: 4.1
Constant: int STATUS_FAILED
Job execution failed
Available since: 4.1
Constant: int STATUS_OK
Job was executed and reported its successful completion status
Available since: 4.1
API Reference
245
Constant: int STATUS_LOGICALLY_FAILED
Job was executed but reported failed completion status
Available since: 4.1
Constant: int STATUS_TIMEOUT
Job execution timeout
Available since: 4.1
Constant: int STATUS_REMOVED
Logically removed job
Available since: 4.1
Constant: int STATUS_SCHEDULED
Job scheduled to be executed at some specific time
Available since: 4.1
Constant: int STATUS_SUSPENDED
Job execution is susspended
Available since: 4.1
Constant: int SORT_NONE
disable sortion of result set of getJobsList()
Available since: 4.1
Constant: int SORT_BY_ID
sort result set of getJobsList() by job id
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
246
Constant: int SORT_BY_TYPE
sort result set of getJobsList() by job type
Available since: 4.1
Constant: int SORT_BY_SCRIPT
sort result set of getJobsList() by job script name
Available since: 4.1
Constant: int SORT_BY_APPLICATION
sort result set of getJobsList() by application name
Available since: 4.1
Constant: int SORT_BY_NAME
sort result set of getJobsList() by job name
Available since: 4.1
Constant: int SORT_BY_PRIORITY
sort result set of getJobsList() by job priority
Available since: 4.1
Constant: int SORT_BY_STATUS
sort result set of getJobsList() by job status
Available since: 4.1
Constant: int SORT_BY_PREDECESSOR
sort result set of getJobsList() by job predecessor
Available since: 4.1
API Reference
247
Constant: int SORT_BY_PERSISTENCE
sort result set of getJobsList() by job persistence flag
Available since: 4.1
Constant: int SORT_BY_CREATION_TIME
sort result set of getJobsList() by job creation time
Available since: 4.1
Constant: int SORT_BY_SCHEDULE_TIME
sort result set of getJobsList() by job schedule time
Available since: 4.1
Constant: int SORT_BY_START_TIME
sort result set of getJobsList() by job start time
Available since: 4.1
Constant: int SORT_BY_END_TIME
sort result set of getJobsList() by job end time
Available since: 4.1
Constant: int SORT_ASC
sort result set of getJobsList() in direct order
Available since: 4.1
Constant: int SORT_DESC
sort result set of getJobsList() in reverse order
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
248
Constant: int OK
constant to report completion status from the jobs using setCurrentJobStatus()
Available since: 4.1
Constant: int FAILED
constant to report completion status from the jobs using setCurrentJobStatus()
Available since: 4.1
Function: ZendJobQueue::__construct(string application=, string binding=taken from
daemon_binding directive, int connection_timeout=taken from daemon_connection_timeout
directive)
Creates a Zend_JobQueue object connected to a Job Queue daemon.
Parameters: string application - an optional application name. All jobs created with this object will be
associated with given application and only status of this job may be retrieved. Object created
without application name can access any job.
string binding - an address of TCP or UNIX socket in PHP format (tcp://127.0.0.1:1234,
unix:///tmp/jq, etc)
int connection_timeout - number of seconds to wait for connection before failure
Returns: Available since: 4.1
API Reference
249
Function: int ZendJobQueue::createHttpJob(string url, array vars, mixed options)
Creates new URL based job, to make the Job Queue daemon call given $script with given $vars
Parameters: string url - an absolute URL of script to call
array vars - an associative array of variables which will be passed to script
mixed options - an associative array of additional options. The elements of this array can define
job priority, predecessor, persistence, optional name, additional attributes of HTTP request as
HTTP headers etc. The following options are supported: "name" - optional job name "priority" -
job priority (see corresponding constants) "predecessor" - integer predecessor job id "persistent" -
boolean (keep in history forever) "schedule_time" - time when job should be executed "schedule"
- CRON-like scheduling command "http_headers" - array of additional HTTP headers
Returns: a job identifier which can be used to retrieve the job status
Available since: 4.1
Function: array ZendJobQueue::getJobStatus(int job_id)
Retrieves status of previously created job identified by $job_id.
Parameters: int job_id - a job identifier
Returns: of the job. The array contains status, comletaion_status and output of the Job.
Available since: 4.1
Function: boolean ZendJobQueue::removeJob(int job_id)
Removes Job from queue. Makes all dependent jobs fail. In case Job is in progress it will be
finished but dependent jobs won't be started anyway. For non-existing jobs the function just
returns false. Finished jobs are simple removed from the database.
Parameters: int job_id - a job identifier
Returns: job was removed or not
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
250
Function: boolean ZendJobQueue::restartJob(int job_id)
Restart a previously executed Job and all its followers.
Parameters: int job_id - a job identifier
Returns: if job was restarted or not
Available since: 4.1
Function: boolean ZendJobQueue::isSuspended()
Checks if Queue is suspended and returns true or false
Returns: a Job Queue status
Available since: 4.1
Function: static boolean ZendJobQueue::isJobQueueDaemonRunning()
Checks if the Job Queue daemon is running
Returns: Return true if the Job Queue deamon is running, false otherwise
Available since: 4.1
Function: ZendJobQueue::suspendQueue()
Suspends the Job Queue, so it will accept new Jobs, but won't start them. The jobs which were
executed during call to this function will be completed
Returns: Available since: 4.1
Function: ZendJobQueue::resumeQueue()
the Job Queue, so it will schedule and start queued jobs.
Returns: Available since: 4.1
API Reference
251
Function: array ZendJobQueue::getStatistics()
Returns internal daemon statistics like up-time, number of complete jobs, number of failed jobs,
number of waiting jobs, number of currently running jobs, etc
Returns: associative array
Available since: 4.1
Function: array ZendJobQueue::getConfig()
Returns current value of configuration option of Job Queue daemon
Returns: associative array of configuration variables
Available since: 4.1
Function: boolean ZendJobQueue::reloadConfig()
Re-reads the configuration file of the Job Queue daemon and reloads all directives that are
reloadable
Returns: if configuration file was loaded succesful or not
Available since: 4.1
Function: array ZendJobQueue::getJobInfo(int job_id)
Returns an associative array with properties of Job with given id from daemon database
Parameters: int job_id - a job identifier
Returns: array of job details. The following properties are provided (some of them don't have to
be always set): "id" - job identifier "type" - job type (see TYPE_* constants) "status" - job status
(see STATUS_* constants) "priority" - job priority (see PRIORITY_* constants) "persistent" -
persistence flag "script" - URL or SHELL script name "predecessor" - job predecessor "name" -
job name "vars" - input variables or arguments "http_headers" - additional HTTP headers for
HTTP jobs "output" - output of the job "error" - error output of the job "creation_time" - time when
the job was created "start_time" - time when the job was started "end_time" - time when the job
was finished "schedule" - CRON-like schedule command "schedule_time" - time when the job
execution was scheduled "app_id" - application name
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
252
Function: array ZendJobQueue::getDependentJobs(int job_id)
Returns a list of associative arrays with properties of Jobs which depend from the Job with given
identifier
Parameters: int job_id - a job identifier
Returns: list of jobs
Available since: 4.1
Function: array ZendJobQueue::getJobsList(array query, int total)
Returns a list of associative arrays with properties of Jobs which conform to a given query
Parameters: array query - an associative array with query arguments The array may contain the following keys
which restrict the resulting list: "app_id" - query only jobs which belong to given application
"name" - query only jobs with given name "script" - query only jobs with script name similar to
given one (SQL LIKE) "type" - query only jobs of the given types (bitset) "priority" - query only
jobs with given priorities (bitset) "status" - query only jobs with given statuses (bitset) "rule_id" -
query only jobs produced by given scheduling rule "scheduled_before" - query only jobs
scheduled before given date "scheduled_after" - query only jobs scheduled after given date
"executed_before" - query only jobs executed before given date "executed_after" - query only
jobs executed after given date "sort_by" - sort by given field (see SORT_BY_* constants)
"sort_direction" - sort direction (SORT_ASC or SORT_DESC) "start" - skip the given number of
jobs "count" - retrieve only the given number of jobs
int total - output parameter which is set to the total number of jobs conforming to the given query
ignoring "start" and "count" fields
Returns: list of jobs with their details
Available since: 4.1
Function: array ZendJobQueue::getApplications()
Returns an array of application names known by daemon
Returns: list of applications
Available since: 4.1
API Reference
253
Function: array ZendJobQueue::getSchedulingRules()
Returns array of all registered scheduled rules. Each rule is represented by nested associative
array with the following properties: "id" - scheduling rule identifier "status" - rule status (see
STATUS_* constants) "type" - rule type (see TYPE_* constants) "priority" - priority of the jobs
created by this rule "persistent" - persistence flag of the jobs created by this rule "script" - URL or
script to run "name" - name of the jobs created by this rule "vars" - input variables or arguments
"http_headers" - additional HTTP headers "schedule" - CRON-like schedule command "app_id" -
application name associated with this rule and created jobs "last_run" - the last time the rule was
run "next_run" - the next time the rule will run
Returns: list of scheduling rules
Available since: 4.1
Function: array ZendJobQueue::getSchedulingRule(int rule_id)
Returns associative array with the properties of scheduling rule identified by given argument. The
list of the properties is the same as in getSchedulingRule()
Parameters: int rule_id - rule identifier
Returns: information about the scheduling rule
Available since: 4.1
Function: boolean ZendJobQueue::deleteSchedulingRule(int rule_id)
Deletes scheduling rule identified by given $rule_id and scheduled jobs created by this rule
Parameters: int rule_id - rule identifier
Returns: if scheduling rule was deleted or not
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
254
Function: boolean ZendJobQueue::suspendSchedulingRule(int rule_id)
Suspends scheduling rule identified by given $rule_id and deletes scheduled jobs created by this
rule
Parameters: int rule_id - rule identifier
Returns: if scheduling rule was suspended or not
Available since: 4.1
Function: boolean ZendJobQueue::resumeSchedulingRule(int rule_id)
Resumes scheduling rule identified by given $rule_id and createa corresponding scheduled job
Parameters: int rule_id - rule identifier
Returns: if scheduling rule was resumed or not
Available since: 4.1
Function: boolean ZendJobQueue::updateSchedulingRule(int rule_id, string script, array vars,
array options)
Updates and reschedules existing scheduling rule
Parameters: int rule_id - rule identifier
string script - URL to request
array vars - input variables
array options - the same as in createHttpJob()
Returns: if scheduling rule was updated or not
Available since: 4.1
API Reference
255
Function: static array ZendJobQueue::getCurrentJobParams()
Decodes an array of input variables passed to HTTP job
Returns: job variables
Available since: 4.1
Function: static ZendJobQueue::setCurrentJobStatus(int completion, string msg)
Reports job completion status (OK or FAILED) back to daemon
Parameters: int completion - job completion status (OK or FAILED)
string msg - optional explanation message
Returns: Available since: 4.1
INI Directives: zend_jobqueue.enable
Enables the Job Queue
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.1
zend_jobqueue.daemon_connection_timeout Default connection timeout to Job Queue daemon
Default connection timeout to Job Queue daemon. Can be overridden using a parameter to
Zend_JobQueue ctor
Default value(s): 10:
Type: int
Measurement units: seconds
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
256
API Reference
257
zend_jobqueue.daemon_binding
Default binding to Job Queue daemon
Default binding to Job Queue daemon. Can be overridden using a parameter to Zend_JobQueue
ctor
Default value(s): tcp://127.0.0.1:55555: for: WindowsAll ,
unix://jobqueue.sock:
Type: string
Measurement units: Available since: 4.1
zend_jobqueue.log_verbosity_level The log verbosity level [0-5]
The extension's log verbosity level. Level 1 includes very important info messages, errors and
warnings. Level 2 displays notices. Greater levels (up to 5) server debug purposes only.
Default value(s): 0:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.log_rotation_size
The maximum size of the log file before it is rotated
The maximum size of the log file before it is rotated
Default value(s): 10:
Type: int
Measurement units: MBytes
Available since: 4.1
Zend Server 5 for IBM i Reference Manual
258
Zend Job Queue Daemon The Zend Job Queue Daemon is the daemon that executes jobs
INI Directives: zend_jobqueue.database
A database connection string in PDO like format
A database connection string in PDO like format. Relative sqlite path will be treated as relative to
Zend Server data directory.
Default value(s): "sqlite:file=jobqueue.db":
Type: string
Measurement units: Available since: 4.1
zend_jobqueue.binding
An address of TCP or UNIX socket to listen for requests from clients and management GUI
An address of TCP or UNIX socket to listen for requests from clients and management GUI
Default value(s): tcp://127.0.0.1:55555: for: WindowsAll ,
unix://jobqueue.sock:
Type: string
Measurement units: Available since: 4.1
zend_jobqueue.back_end_server an address of HTTP server to handle URL based jobs
an address of HTTP server to handle URL based jobs. The default value is "http://127.0.0.1". All
URLs with unspecified server goes to back_end server. It is possible to define several back_end
servers. The less loaded server (the server which is executing the less number of jobs) will be
used to perform URL based job in this case.
Default value(s): http://127.0.0.1:
Type: string
Measurement units: Available since: 4.1
API Reference
259
Zend Server 5 for IBM i Reference Manual
260
zend_jobqueue.max_http_jobs
The maximum number of HTTP based jobs which can be executed simultaneously by single
back-end server
The maximum number of HTTP based jobs which can be executed simultaneously by single
back-end server
Default value(s): 4:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.history
The maximum time (in days) a completed, failed or removed job is kept in database.
The maximum time (in days) a completed, failed or removed job is kept in database. If no
directive is provided time is unlimited and jobs are never deleted. Independently on this directive
setting jobs may be kept forever using "persistent" option.
Default value(s): 7:
Type: int
Measurement units: days
Available since: 4.1
zend_jobqueue.client_keep_alive
Number of second while daemon keeps inactive connection from client.
Number of second while daemon keeps inactive connection from client. In case client doesn't
send any request during this time daemon closes the client's connection. (default 3600 seconds =
1 hour)
Default value(s): 3600:
Type: int
Measurement units: Available since: 4.1
API Reference
261
zend_jobqueue.client_read_timeout Number of second while daemon is trying to read request from client.
Number of second while daemon is trying to read request from client. In case client doesn't
respond in this time daemon closes the client's connection. (default 10 seconds)
Default value(s): 10:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.client_write_timeout Number of seconds while daemon is trying to deliver response to client.
Number of seconds while daemon is trying to deliver response to client. In case client doesn't
respond in this time daemon closes the client's connection. (default 10 seconds)
Default value(s): 10:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.connection_timeout Number of milliseconds while daemon trying to establish a connection with back-end server
Number of milliseconds while daemon trying to establish a connection with back-end server
Default value(s): 10:
Type: int
Measurement units: Available since: 4.1
Zend Server 5 for IBM i Reference Manual
262
zend_jobqueue.http_job_timeout Number of seconds while URL based job must complete.
Number of seconds while URL based job must complete. After timeout expiration daemons drops
the connection to back-end server and sets job status to "failed" and completion status to
"timeout".
Default value(s): 10:
Type: int
Measurement units: seconds
Available since: 4.1
zend_jobqueue.job_restart_timeout The minimal number of milliseconds between job startups.
The minimal number of microlliseconds between job startups.
Default value(s): 200:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.http_job_retry_count Number of retries in case of HTTP job failure.
Number of retries in case of HTTP job failure.
Default value(s): 10:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.http_job_retry_timeout The number of seconds between retries of failed HTTP jobs.
The number of seconds between retries of failed HTTP jobs.
Default value(s): 1:
Type: int
Measurement units: seconds
Available since: 4.1
API Reference
263
zend_jobqueue.high_concurrency_margin_allowed
Report an event when the Job Queue Daemon reaches a margin between the number of running
jobs and the maximum allowed
Report an event when the Job Queue Daemon reaches a margin between the number of running
jobs and the maximum allowed
Default value(s): 0:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.job_time_skew_allowed
Report an event when a job is "skewing" from its defined execution time
Report an event when a job is "skewing" from its defined execution time
Default value(s): 120:
Type: int
Measurement units: seconds
Available since: 4.1
zend_jobqueue.log_verbosity_level The Log's verbosity level
The Log's verbosity level
Default value(s): 0:
Type: int
Measurement units: Available since: 4.1
zend_jobqueue.log_rotation_size
The maximum size of the log file before it is rotated
The maximum size of the log file before it is rotated
Default value(s): 10:
Type: int
Measurement units: MBytes
Zend Server 5 for IBM i Reference Manual
264
Available since: 4.1
zend_jobqueue.global_directives_ini_file
Global Directives ini File
The .ini file that contains the global directives, as defined in ZendGlobalDirectiveDD.xml
Default value(s): GLOBAL_DIRECTIVES_INI_FILE:
Type: string
Measurement units: Available since: 4.1
API Reference
265
Zend Tracer The Zend Tracer produces a full trace of all function calls during the request.
The Zend Tracer produces a full trace of all function calls during the request. This allows for
detailed investigation of events and very accurate profiling.
PHP API Function: int zend_trace_options(string options)
Sets and retrieves the tracing options.
Parameters: string options - Optional: set tracing options.
Returns: Old value of the options
Available since: 4.0
Function: array zend_trace_event()
Creates a record of event in the trace log.
Returns: Array containing trace dump ID number and event number inside the dump
Available since: 4.0
INI Directives:
zend_trace.enabled
Is tracing functionality enabled?
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
266
zend_trace.buffer_size
The size of the trace memory buffer
Default value(s): 1M:
Type: int
Measurement units: Bytes
Available since: 4.0
zend_trace.dump_format The type of dump produced
Default value(s): 2:
Type: int
Measurement units: Available since: 4.0
zend_trace.max_string
The maximal length of the string before it is cut
Default value(s): 48:
Type: int
Measurement units: Bytes
Available since: 4.0
zend_trace.max_depth
The maximal depth of the array preserved
Default value(s): 2:
Type: int
Measurement units: Available since: 4.0
API Reference
267
zend_trace.max_elements
The maximal number of the array elements preserved
Default value(s): 10:
Type: int
Measurement units: Available since: 4.0
zend_trace.dump_file
The prefix for the dump file names
Default value(s): /tmp/dumps/dump:
Type: int
Measurement units: Available since: 4.0
zend_trace.trace_enabled
Tracing data collection is enabled
Default value(s): 0:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_time
Timestamp collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
268
zend_trace.trace_source_lines
Source file information collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_internal_functions
Internal functions call collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_user_functions
User functions call collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_includes
Include/require data collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
API Reference
269
zend_trace.trace_arguments
Function call argument collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_return_values
Function return value collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_exceptions
PHP exception data collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_arrays
Array contents recording is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
270
zend_trace.trace_write
Output data (writing) collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_headers
Output headers collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_memory_usage
Memory usage data collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_errors
PHP error collection is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
API Reference
271
zend_trace.trace_events
Zend Monitor event recording is enabled
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_always_dump
Trace data is always persisted
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
zend_trace.trace_dump_on_segv
Trace data is persisted if fatal signal (like Segmentation Fault) happens
Default value(s): 1:
Type: boolean
Measurement units: Available since: 4.0
Zend Server 5 for IBM i Reference Manual
272
PHP Toolkit for IBM i Introduction to the PHP Toolkit for IBM i
This section includes the following topics:
PHP Toolkit for IBM i
PHP Toolkit Functions
PHP Toolkit Data Description
Program Samples
I5 Toolkit Templates
API Reference
273
PHP Toolkit for IBM i PHP Toolkit for IBM i is a Zend Server for IBM i extension. The PHP ToolKit for IBM i
enables Zend Server for IBM i to interact with native i5/OS services.
The PHP APIs enable PHP programs to access System objects such as RPG/COBOL/Java
programs, CL commands, Data Queue, Spooled file, etc. These APIs expose the PHP Object
Oriented programming interface.
From an architectural standpoint, PHP functionality is implemented as a PHP extension that is
enabled during the Zend Server for IBM i Installation process.
The extension implements the client side of the interface.
A server, implementing the native IBM i interface, is installed on the IBM i machine as a native
IBM i service.
PHP Toolkit Classes (sample) The PHP Toolkit also offers sample classes for developers who are comfortable using object
oriented (OO) methods in PHP.
PHP Toolkit classes can be found in the directory /usr/local/zendsvr/apache2/htdocs/.
This directory contains the i5 Toolkit classes file "Toolkit_classes.php", and the
"demo_for_toolkit_classes.php" sample program, which utilizes the Toolkit classes.
The i5 Toolkit class library contains the following classes:
i5_Connection - Connection class
i5_Description - Data type definition class
i5_Program - Program call class
i5_DataQueue - Data Queue class
i5_DataQueueKey - Keyed Data Queue class
i5_SpoolList - Spooled file list class
i5_Userspace_Create - User Space create class
i5_Userspace_Delete - User Space delete class
i5_UserspaceManage - User Space read/write class
i5_DataAreas - Data Area class
i5_JobLogs - Job log class
i5_ActiveJobs - Active Jobs class
i5_ObjectListing - Object list class
i5_NativeFileAccess - Database class
Zend Server 5 for IBM i Reference Manual
274
INSTALLATION No special installation is required, just place the PHP Toolkit class file "Toolkit_classes.php" in
the same directory as your PHP program.
Zend Studio IDE templates Zend Studio IDE for IBM i comes complete with PHP Toolkit function Code Assist and Templates
containing PHP API Toolkit functions.
For a full list of these functions, see IBM i Toolkit Templates.
API Reference
275
PHP Toolkit Functions
All PHP Toolkit functions start with prefix "i5".
Connection Management
i5_connect
resource i5_connect(string server, string user, string password[, array options]).
Description: Connects to the AS/400 server.
Return Values: AS/400 connection resource or false on failure.
Arguments:
• server - Name of the server to connect to. This can be either a symbolic name or
an IP.
• user - Username to use for connecting. Note: Username QSECOFR cannot be used in this function.
• password - Password for the username
• options - Connection options.
Example: $conn = i5_connect("1.2.3.4", "MYUSER", "MYPWD"); if (!$conn) { die(i5_errormsg()); }
Connection Options:
I5_OPTIONS_JOBNAME - job name (machine name by default)
I5_OPTIONS_SQLNAMING - Enables using dotted (.) or slashed (/) notation in SQL requests
I5_OPTIONS_DECIMALPOINT - Enables using dot or comma as decimal separator
I5_OPTIONS_CODEPAGEFILE - Enables using specific code page (CCSID)
I5_OPTIONS_ALIAS - Enables naming a connection. If the name is used in another i5_connect,
then the other i5_connect will use the same connection.
I5_OPTIONS_INITLIBL - Specified libraries are added to the beginning of the initial library list.
I5_OPTIONS_LOCALCP - Sets the local code page used by PHP application.
I5_OPTIONS_RMTCCSID - Sets the EBCDIC CCSID
Zend Server 5 for IBM i Reference Manual
276
i5_pconnect
resource i5_pconnect(string server, string user, string password[, array options]).
Description: Returns a persistent connection to the i5/OS server. This function acts like
i5_connect(), with the following differences:
The connection does not disappear after the web request completion. It will keep job
environment information such as library lists, etc.
The connection can be reused for another web request if the request contains the same
server id, user and password used in the previous web request.
If the previous connection doesn’t exist, a new connection will be created, and will be
kept open until the PHP script ends.
A subsequent call to i5_close() will not close the connection.
Use i5_pclose() to close the connection opened by i5_pconnect() function.
Return Values: i5/OS connection resource or false on failure.
Arguments:
• server - Name of the server to connect to. This can be either a symbolic name or
an IP.
• user - Username to use for connecting.
Note: Username QSECOFR cannot be used in this function.
• password - Password for the username
• options - Connection options.
Example - Basic Connection /* Basic connection to i5/OS */ $conn = i5_pconnect("i.2.3.4","USER","PWD", array(i5_OPTIONS_IDLE_TIMEOUT=>120)) or die(i5_errormsg()); echo " Connection OK <BR>"; /* Connection error detail in case of failure */ $conn = i5_pconnect("i.2.3.4","MYUSER","MYPWD"); if (!$conn) { $error = i5_error(); echo " Error during connection\n"; echo "<BR> Error number: ".$error["num"]; echo "<BR> Error category: ".$error["cat"]; echo "<BR> Error message: ".$ error ["msg"]; echo "<BR> Error description: ".$ error ["desc"]; trigger_error("I5 persistent connection fails", E_USER_ERROR); } else { echo " Connection OK "; $isnew = i5_get_property(I5_NEW_CONNECTION); if ($isnew) ) { echo " New connection. Do some job initialization \n"; } } /* leaves connection without closing it. */
API Reference
277
/* Make it available for another script. */ $ret = i5_close($conn); if($ret){ echo " I5 disconnected"; } else { $ret = i5_errormsg($conn); }
Example - Private Connection <?php /* Private connection to i5/OS */ conId = 0; if (isset($_SESSION['connectionID'])) { $conId = $_SESSION['connectionID']; echo "Connection ID is $conId<BR>"; } else { echo "No connection ID stored.<BR>"; } // I5_OPTIONS_PRIVATE_CONNECTION connection is private for the session // I5_OPTIONS_IDLE_TIMEOUT After a delay with no activity, the job will end. $retcon = i5_pconnect ('SYSTEMI', "USER", "pwd", array( I5_OPTIONS_PRIVATE_CONNECTION => $conId, I5_OPTIONS_IDLE_TIMEOUT=>"60")); if (is_bool($retcon) && $retcon == FALSE) { $errorTab = i5_error(); if ($errorTab['cat'] == 6 && $errorTab['num'] == -12){ echo "Connection ID no longer active<BR>"; $_SESSION['connectionID'] = 0; } else print_r($errorTab); } else { if ($conId == 0) { //Session varaible was 0: Get connection ID and store it in session variable. $ret = i5_get_property(I5_PRIVATE_CONNECTION, $retcon); if (is_bool($ret) && $ret == FALSE) { $errorTab = i5_error(); print_r($errorTab); } else { // Connection ID is stored in session variable $_SESSION['connectionID'] = $ret; } } } ?>
Connection Options:
I5_OPTIONS_IDLE_TIMEOUT - sets the time ( in seconds) to raise an event when the
connection can be closed by another connection request (i5_connect or i5_pconnect). If
this option is not used the connection job will remain open.
I5_OPTIONS_PRIVATE_CONNECTION - Set the ID of the persistent connection to
reuse.
I5_OPTIONS_JOBNAME - job name (machine name by default).
Zend Server 5 for IBM i Reference Manual
278
I5_OPTIONS_SQLNAMING - Enables using dotted (.) or slashed (/) notation in SQL
requests.
I5_OPTIONS_DECIMALPOINT - Enables using dot or comma as decimal separator.
I5_OPTIONS_CODEPAGEFILE - Enables using specific code page (CCSID).
I5_OPTIONS_ALIAS - Enables naming a connection. If the name is used in another
i5_connect, then the other i5_connect will use the same connection.
I5_OPTIONS_INITLIBL - Specified libraries are added to the beginning of the initial
library list.
I5_OPTIONS_LOCALCP - Sets the local code page used by PHP application.
I5_OPTIONS_RMTCCSID - Sets the EBCDIC CCSID
i5_pclose
bool i5_close([resource connection]).
Description: Closes the persistent connection to i5/OS server..
Return Values: Boolean success value.
Arguments:
connection - Result of i5_pconnect
Example: /* Basic connection to i5/OS */ $conn = i5_pconnect("("i.2.3.4","USER","PWD") if ($conn) { echo "Connection succeeds <BR>"; [treatments...] $closing = i5_pclose($conn); if ($closing) { echo "Disconnection succeeds"; } }
API Reference
279
i5_get_property
int/string i5_get_property(int Property, [resource connection]).
Description: Gets a connection status for a connection opened either by i5_pconnect ()
or i5_connect ()
Return Values:
• - 0 : The connection to i5/OS was already opened by the previous PHP script via
i5_pconnect().
• - 1 : New connection which was not used by another PHP script.
Arguments:
• Property - I5_NEW_CONNECTION
• connection - Result of i5_pconnect or i5_connect ()
Example: $isnew = i5_get_property(I5_NEW_CONNECTION, $conn);
i5_close
bool i5_close([resource connection]).
Description: Closes connection to AS/400 server.
Return Values: Boolean success value.
Arguments: connection - Result of i5_connect
i5_adopt_authority
bool i5_adopt_authority(string username, string password, [resource connection]).
Description: Changes authority of the connection to a specific user. All actions will be
executed as this user from now on.
Return Values: Boolean success value.
Arguments:
• username - Name of the user to change to
• password - Password for the user
• connection - Connection - result of i5_connect
Zend Server 5 for IBM i Reference Manual
280
i5_error
bool i5_error([resource connection]).
Description: Retrieves error information for last action that was executed.
Return Values: If there was no error, returns false. Otherwise, returns an array with the
following elements:
• 0 - error number, as in i5_errno().
• 1 - error category.
• 2 - error message, as in i5_errmsg().
• 3 - detailed description of the error.
Arguments: connection - Connection - result of i5_connect
i5_errormsg
string i5_errormsg([resource connection]).
Description: Gets error message for last executed action.
Return Values: Error message string.
Arguments: connection - Connection - result of i5_connect.
API Reference
281
CL Calls
i5_command
bool i5_command(string command[, array inputs, array outputs, resource connection]).
Description: Calls CL command.
Return Values: Boolean success value.
Arguments:
• inputs - Array of name => value parts, name describing the call input parameters.
Names should match i5 cl command parameter names.
If the array is empty or not provided, no input parameters are given. If the value
is integer, integer is passed, if the value is string, quoted string is passed. If the
value is an array, the list of contained values is passed. Note: The output parameter is required if the input parameter is specified.
• outputs - Array which describes output parameters of the command. If not
provided, no output parameters are defined.
Key of the array defined i5 cl command parameter name.
"rc" is a predefined name containing the result of the command.
Value can be string. If so - it defines a php variable name to accept the
parameter or array; it should have 2 elements:
• A php variable name to accept the parameter.
• Description of the parameter
Note: The input parameter is required if the output parameter is specified.
• connection - Connection - result of i5_connect.
Example: i5_command("rtvjoba", array(), array("curlib" => "curl",. "user"=>"user",. "usrlibl" => "userlib",. "syslibl" => array("syslib", "char(165)"), . ). );. print "User : $user<br>" ;. print "User library : $userlib<br>" ;. print "System libs list : $syslib<br>" ;. print "Current library : $curl<br>" ;.
Zend Server 5 for IBM i Reference Manual
282
Program Calls
i5_program_prepare
resource i5_program_prepare(string name[, array description][, resource connection]).
Description: Opens a program and prepares it to be run.
Return Values: Resource if open succeeded, false if open failed.
Arguments:
• name - Program name. If a service procedure call is made, the procedure name
is given in parentheses, e.g. Lib/Service_Program(PROC)
• description - PHP-format program description. This should be provided if the
program is not described on server.
See PHP Data Description for more information.
• connection - Result of i5_connect
i5_program_prepare_PCML
resource i5_program_prepare_PCML (array description[, resource connection]).
Description: Opens a program PCML file and prepares it to be run.
Return Values: Resource if open succeeded, false if open failed.
Arguments:
description - PCML file’s program and parameters information
connection - Result of i5_connect
The program information file (in PCML format) can be created by compiling the RPG program.
Example:
CRTBNDRPG PGM(EACDEMO/TESTSTRUC) SRCFILE(EACDEMO/QRPGLESRC)
SRCMBR(TESTSTRUC) PGMINFO(*PCML) INFOSTMF('/www/zendSvr/htdocs/teststruc.pcml')
The PCML file will contain the program parameters info. There are two ways you can assign the
program parameters to i5-program_prepare_PCML description:
Copy the content of PCML file to you PHP script and assign the i5_program_prepare_PCML
description array to the PCML content. See PCML Example 1 (below).
Assign i5_program_prepare description array to the PCML file located in the same PHP program
directory. See PCML Example 2 (below.
PCML Example 1: $description = "<pcml version=\"4.0\"> <!-- RPG module: TESTSTRUC --> <!-- created: 2006-10-12-11.46.56 --> <!-- source: EACDEMO/QRPGLESRC(TESTSTRUC) -->
API Reference
283
<!-- 5 --> <struct name=\"S2\"> <data name=\"ZOND2\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK2\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK3\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"ALPH2\" type=\"char\" length=\"20\" usage=\"inherit\" /> </struct> <!-- 1 --> <struct name=\"S1\"> <data name=\"ZOND\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK1\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"ALPH1\" type=\"char\" length=\"10\" usage=\"inherit\" /> </struct> <program name=\"TESTSTRUC\" path=\"/QSYS.LIB/EACDEMO.LIB/TESTSTRUC.PGM\"> <data name=\"CODE\" type=\"char\" length=\"10\" usage=\"output\" /> <data name=\"S1\" type=\"struct\" struct=\"S1\" usage=\"inputoutput\" /> <data name=\"S2\" type=\"struct\" struct=\"S2\" usage=\"inputoutput\" /> <data name=\"PACK\" type=\"packed\" length=\"1\" precision=\"1\" usage=\"output\" /> <data name=\"CH10\" type=\"char\" length=\"19\" usage=\"output\" /> <data name=\"CH11\" type=\"char\" length=\"20\" usage=\"output\" /> <data name=\"CH12\" type=\"char\" length=\"29\" usage=\"output\" /> <data name=\"CH13\" type=\"char\" length=\"33\" usage=\"output\" /> </program> </pcml> ";
PCML Example 2: ($description = file_get_contents("/www/zendSvr/htdocs/teststruc.pcml")) or trigger_error("Error while opening PCML file", E_USER_ERROR);
Zend Server 5 for IBM i Reference Manual
284
i5_program_call
bool i5_program_call(resource program, array params[, array retvals]).
Description: Calls the program and optionally accepts results.
Return Values: Boolean success value.
Arguments:
• program - Program resource opened by i5_program_prepare.
• params - Parameters according to description.
Can be given as flat array, then parameters are assigned in order, or as key =>
value pairs then the values are assigned to the parameter named by the key
• retvals - Array of key => value pairs where keys describe output parameter name
and values name PHP variable that would receive the parameter
• Fetch should still work even if the return parameters are defined and assigned.
Example: $prog = i5_program_prepare("DEMOPGM");. if(i5_program_call($prog, array(1,2,"abc"))) {. $result = i5_fetch_assoc($prog);. print "result is $result['retval']<br>";. } else {. print "Program call failed.<br>";. }.
Note: Use i5_COMMAND in order to invoke a program without parameters. For example,
i5_command("call LIB_NAME/PROGRAM_NAME").
i5_program_close
void i5_program_close(resource program).
Description: Frees program resource handle.
Return Values: Boolean success value.
Arguments: program - Program resource opened by program_open.
API Reference
285
Data Retrieval
i5_fetch_array
array i5_fetch_array(resource result [, int option ] ).
array i5_fetch_assoc(resource result [, int option ] ).
object i5_fetch_object(resource result [, int option ] ).
array i5_fetch_row(resource result [, int option] ).
Description: Fetches a row of data from the resource.
Return Values: According to the specific fetch function used, it returns either an array or
an object containing the data:
• array - by index and name.
• assoc - by name.
• row - by index.
• object - by name as object properties.
Arguments:
• result - Resource resulting from operation returning data
• option - Flag specifying which record to fetch.
• Current record - I5_READ_SEEK
• Next record - I5_READ_NEXT
• Previous record - I5_READ_PREV
• First record - I5_READ_FIRST
• Last record - I5_READ_LAST
• Default is I5_READ_NEXT
i5_info
array i5_info ( resource result [, int/string field ] ).
Description: Gets information about the file/record.
Return Values: An array with information about record. If there is no way to return whole
information; false is returned when the field parameter is omitted.
Arguments: result - Resource describing file or other record set
field - Integer or string identifying the field. If this parameter is omitted, whole file
information is given (when possible).
Zend Server 5 for IBM i Reference Manual
286
i5_field_len
int i5_field_len ( resource result, int/string field ).
Description: Gets field length.
Return Values: field's length.
Arguments: result - Resource describing file or other record set
field - Integer or string identifying the field position or name.
i5_field_name
int i5_field_name ( resource result, int field ).
Description: Get field name.
Return Values: field's length.
Arguments: result - Resource describing file or other record set
field - Integer identifying the field position.
i5_field_scale
int i5_field_scale ( resource result, int/string field ).
Description: Gets field scale - number of digits for numeric fields.
Return Values: The number of digits of the field. If the field is not numeric, returns -1.
Arguments: result - Resource describing file or other record set
field - Integer or string identifying the field position or name.
i5_field_type
string i5_field_type ( resource result , int/string field ).
Description: Gets field type.
Return Values: Field's type string.
Arguments: result - Resource describing file or other record set .
field - Integer or string identifying the field position or name.
API Reference
287
i5_list_fields
array i5_list_fields ( resource result ).
Description: Gets list of fields for resource.
Return Values: Array containing field names, in order.
Arguments: result - Resource describing file or other record set.
i5_num_fields
int i5_num_fields ( resource result ).
Description: Get the numbers of fields for resource.
Return Values: Number of fields.
Arguments: result - Resource describing file or other record set.
i5_result
mixed i5_result ( resource result, int/string field]).
Description: Gets one field of the result.
Return Values: Field's contents in current record.
Arguments: result - Resource describing file or other record set.
field - Integer or string identifying the field position or name.
Zend Server 5 for IBM i Reference Manual
288
Native File Access
i5_open
resource i5_open (string fileName [, int mode ][,resource connection]).
Description: Opens native i5 file.
Return Values: Resource, if "open" is successful, false otherwise.
Arguments:
• name - File name, may include library
• mode - File mode to use:
o I5_OPEN_READ - default
o I5_OPEN_READWRITE
o I5_OPEN_COMMIT
o I5_OPEN_SHRRD
o I5_OPEN_SHRUPD
o I5_OPEN_SHRNUPD
o I5_OPEN_EXCLRD
o I5_OPEN_EXCL
• connection - Connection - result of i5_connect
Note: OPEN_READ or I5_OPEN_READWRITE modes are required to be combine with other modes.
For example, $ret = i5_open ("LIB/FILE", I5_OPEN_READWRITE | I5_OPEN_EXCL);
i5_addnew
bool i5_addnew ( resource file [, int mode] ).
Description: Creates new record in the file. Use setvalue() to set values in new record,
then update() to write it to file. i5_new_record() is an atomic function doing all the work.
Return Values: Resource if open succeeded, false if "open" failed.
Arguments:
• file - Opened i5 file.
• mode - I5_ADDNEW_CLEAR: clears all record fields (default).
• I5_ADDNEW_NOCLEAR: does not clear all record fields
API Reference
289
i5_edit
bool i5_edit ( resource file [, int mode] ).
Description: Sets editing mode for the record. In order for a value to be changed, it
should be set in edit mode. This locks the record so that other users cannot edit it
simultaneously.
Return Values: Boolean success value. Returns false if the record is already being
edited by other used.
Arguments:
• file - i5 file resource.
• mode - Editing mode:
o I5_EDIT_ONE leaves edit mode after i5_update() and also after reading
or i5_delete().
o I5_EDIT_ALWAYS remains in edit mode until i5_cancel_edit() is called.
o I5_EDIT_AUTO is called automatically therefore there is no need to call
i5_update() after setting values.
i5_delete
bool i5_delete ( resource file ).
Description: Remove current record.
Return Values: Boolean success value. Return is false if the record is already being
edited by other used.
Arguments:
• file - i5 file resource.
• i5_cancel_edit
• bool i5_cancel_edit ( resource result ).
Zend Server 5 for IBM i Reference Manual
290
i5_setvalue
bool i5_setvalue (resource file, int/string field, mixed value).
bool i5_setvalue (resource file, array values ).
Description: Changes the value of the current record. The record should be in edit mode
after i5_edit() or created by i5_addnew().
Return Values: Boolean success value.
Arguments:
• file - i5 file resource.
• field - Field identifier by name or position.
• value - Value for the field.
• values - Set of key=>value parts describing fields to change and their new
values.
i5_update
bool i5_update ( resource file ).
Description: Commits changes done to the file record after i5_edit() or i5_addnew() into
the file.
Return Values: Boolean success value.
Arguments: file - i5 file resource.
i5_range_from
bool i5_range_from ( resource file,bool included,array values).
Description: Sets an upper range bound for the file. Once the bound is set, the first line
for all seeks becomes the line defined by the range.
Return Values: Boolean success value.
Arguments:
• file - i5 file resource.
• included - True if the field with this key should be included in the range, false
otherwise.
• values - Values for the key fields - array of key=>value pairs.
API Reference
291
i5_range_to
bool i5_range_to (resource result,bool included, array values ).
Description: Sets a lower range bound for the file. Once the bound is set, the last entry
for all seeks becomes the entry defined by the range.
Return Values: Boolean success value.
Arguments:
• file - i5 file resource
• included - True if the field with this key should be included in the range, false
otherwise.
• values - Values for the key fields - array of key=>value pairs.
i5_range_clear
bool i5_range_clear (resource file).
Description: Removes range. Reverses the action of range_from() and range_to().
Return Values: Boolean success value.
Arguments: file - i5 file resource
i5_data_seek
bool i5_data_seek (resource result, int record_number).
Description: Seeks to a specific record of the result.
Return Values: Boolean success value.
Arguments:
• file - i5 file resource.
• Record_number - Number of the record to seek to, starting from 0.
Zend Server 5 for IBM i Reference Manual
292
i5_seek
bool i5_seek (resource file, int/string operator, array keyValue).
Description: Goes to a specific record in query/file.
Return Values: Boolean success value.
Arguments:
• file - i5 file resource
• operator - Comparison operator. Position is set to first record satisfying the
operator. Available operators:
• I5_EQ "="
• I5_GT ">"
• I5_LT "<"
• I5_GE ">="
• I5_LE "<="
• keyValue - values of the keys to compare
i5_bookmark
int i5_bookmark (resource file).
Description: Return Values the ID of the current record.
Return Values: The ID of the current record that can be used with i5_data_seek() to
position on this record again.
Arguments: file - i5 file resource.
i5_free_file
bool i5_free_file (resource file).
Description: Closes file handle and frees file resources.
Return Values: Boolean success value.
Arguments:
• file - i5 file resource.
• Additional functions to the existing API.
API Reference
293
i5_new_record
bool i5_new_record (resource file, array data).
Description: Creates a new record in the file and inserts data into it.
Return Values: Boolean success value.
Arguments:
• file - Opened i5 file resource.
• data - Array of data fields conforming to file description.
• Can be either a flat array or key-value pairs, e.g., i5_setvalue arguments.
i5_update_record
bool i5_update_record (resource file, array data).
Description: Updates the current row with given data.
Return Values: Boolean success value.
Arguments: file - Opened i5 file resource.
data - Array of data fields conforming to file description.
Can be either flat array or key-value pairs, like i5_setvalue arguments.
Example:
$file = i5_open("API/TESTFILE", I5_OPEN_READWRITE);.
$rec = i5_fetch_row($file, I5_READ_FIRST);.
i5_update_record($file, array("CODE" => "C-02", "NOM" => "DUPONT", "TYPE" => 3));.
i5_new_record($file, array('C-105', 'DUPOND', 'Jean', 'Avenue du Qubec', 'Les Ulis', 3, 'FR'));.
Zend Server 5 for IBM i Reference Manual
294
i5_delete_record
bool i5_delete_record(resource file).
Description: Removes current record.
Return Values: Boolean success value. False value is returned if the record is already
being edited by other used.
Arguments: File - Opened i5 file resource.
Example: $file = i5_open("API/TESTFILE", I5_OPEN_READWRITE);. i5_new_record($file, array('C-105', 'DUPOND', 'Jean', 'Avenue du Qubec', 'Les Ulis', 3, 'FR'));. $rec = i5_fetch_row($file, I5_READ_FIRST);. i5_update_record($file, array("CODE" => "C-02", "NOM" => "DUPONT", "TYPE" => 3));. i5_delete_record($file);
i5_get_keys
array i5_get_keys(resource file).
Description: Gets information about key fields in the file.
Return Values: An array of integers specifying positions for key fields in the file. Can
then use i5_info to discover descriptions of these fields.
Arguments:
• file - Opened i5 file resource.
API Reference
295
SQL File Access
i5_query
resource i5_query ( string query [, resource connection] )
Description: Executes an SQL statement directly
Return Values: For SELECT request returns resource if statement was executed
successfully and FALSE in case of error. For INSERT, UPDATE and DELETE requests
returns TRUE if statement was executed successfully and FALSE in case of error.
Note: i5_query function is suitable for SQL requests without parameters. If you plan to issue the same
SQL statement with different parameters, consider using i5_prepare() and i5_execute().
Arguments:
Query - SQL request string such as SELECT, INSERT, DELETE, UPDATES and etc
connection - result of i5_connect
Example: $query = i5_query("SELECT * FROM EACDEMO/SP_CUST"); if(!$query) { echo "Error code: " . i5_errno($query) . " "; echo "Error message: " . i5_errormsg($query) . " "; } else { /* Read records and display */ echo "<table border=1>"; $i = 0; while ($values = i5_fetch_row($query, I5_READ_NEXT) AND ($i < 10)) { $i++; echo "<tr>"; echo "<td>" .$values[0]. "</td>"; echo "<td>" .$values[1]. "</td>"; echo "<td>" .$values[2]. "</td>"; echo "<td>" .$values[3]. "</td>"; echo "<td>" .$values[4]. "</td>"; echo "<td>" .$values[5]. "</td>"; echo "</tr>"; } echo "</table>"; } i5_free_query($query);
Zend Server 5 for IBM i Reference Manual
296
i5_prepare
resource i5_prepare ( string query [, resource connection] )
Description: Prepares an SQL statement to be executed
Query parameter may include one or several SQL variables if question marks (?) are set
at the right places. There are three main advantages using prepared requests in your
script: Performance: While preparing a request, database server creates a return
optimized path in order to collect the requested data's. Later on, when the i5_prepare
prepared request is sent, it will use the path avoiding processor overload with each
request sent. Safety: While preparing a request, it is possible to set markers for entry
values. Processing the prepared request with entry values, PHP Toolkit checks each
entry value to make sure that their type match with the column or the description
parameters. Advanced Functionality: Markers not only allow introducing entry values in
stored procedure, but also allow collecting OUTPUT and INPUT/OUTPUT recording
procedure parameters using i5_bind_param function.
Return Values: Returns a statement resource if the SQL statement was successfully
parsed and prepared by the database server. FALSE if the database server returned an
error.
Arguments:
• query - SQL request to prepare
• connection - result of i5_connect
i5_bind_result
bool i5_bind_result ( resource result/query, mixed &var1 [,mixed &var2 ...] )
-Or-
bool i5_bind_result ( resource result/query, mixed &var, string namefield )
Description: Binds a PHP variable to an SQL statement parameter in a statement
resource returned by i5_prepare().
Returns TRUE on success or FALSE on failure.
Arguments:
• query/stmt - 5_prepare prepared request ID
• var1 , &var2 - variables to associate referenced list
• namfield - request field or associated file name
API Reference
297
i5_execute
bool i5_execute ( resource stmt [,params] )
Description: Executes a prepared SQL statement
i5_execute executes an SQL request prepared with i5_prepare. If the SQL statement
returns a result set, for example, a SELECT statement or a CALL to a stored procedure
that returns one or more result sets, you can retrieve a row as an array from the stmt
resource using i5_fetch_array, i5_fetch_assoc or i5_fetch_row. If the request creates
several results sets, i5_next_result function moves pointer to the next available set.
i5_execute is much more efficient than i5_query if the same request has to be run several
times with only few parameter changes.. Refer to i5_prepare for a brief discussion of the
advantages of using i5_prepare and i5_execute rather than i5_query.
A request may contain markers, identified with "?" sign. These markers can be linked to
PHP variables (seer i5_bind_param), the results may be linked to PHP variables using
i5_bind_result function.
Return Values: Returns Boolean and updated stmt resource in case of success FALSE
if it fails
Arguments:
• stmt - A prepared statement returned from i5_prepare
• params - Input parameters matching any parameter markers contained in the
prepared statement.
Example: $town = "Paris"; /* Prepare a request */ $req = i5_prepare("SELECT area FROM cities WHERE Name=?"); if ($req) { /* Associate SQL variables */ i5__bind_param($req, $town); /* Execute the request */ i5_execute($req); /* Associate the results variables */ i5_bind_result($req, $region); /* Read records */ i5_fetch_row($req); printf("%s is in area %s\n", $town, $region);
Zend Server 5 for IBM i Reference Manual
298
i5_getblob
string i5_getblob( resource result, int position )
-Or-
string i5_getblob( resource result, string namefield )
Description: Reads binary data from a BLOB field type.
This function applies to SELECT type (i5_queryi5_query or i5_executei5_execute)
requests containing one or more BLOB type fields.
Note: Reading and writing a blob requires a transaction.
Return Values: String with BLOB binary chain or FALSE on failure
Arguments:
• result - File ID
• position - BLOB field index
• namfield - BLOB field name
Example: /* Specify isolation level UR (COMMIT(*CHG)) */ i5_query( "SET TRANSACTION ISOLATION LEVEL UR" ); /* One of the select filed is a blob column. */ $sql = "SELECT FLD1, FLD2, BLOB_COLUMN FROM BLOB_TABLE"; $res = i5_query($sql); $line = i5_fetch_row($res, I5_READ_NEXT); /* element $line[2] contains blob ID */ $blob_data = i5_getblob($res, 2); /* now the blob can be displayed or processed */
i5_setblob
bool i5_setblob ( resource stmt, int position, string blob )
Description: Writes a binary data in a BLOB field type.
This function only applies to parameterized requests resources and is used the same
way as i5_setparam function.
Note: Writing a blob requires a transaction.
Return Values: TRUE on success or FALSE on failure
Arguments:
• result - Parameterized file ID
API Reference
299
• position - Parameter index
• blob - Binary chain content
Example: /* Writing jpeg file content in blob */ $sql = "INSERT INTO CONTACTS (NAME, PRENOM, PHOTO) VALUES (?,?,?)"; $req_prepa = i5_prepare($sql); if ($req_prepa) { $name = "DUPONT"; $prenom = "HENRY"; $file_image = fopen("hdupont.jpg", 'r'); $photo = fread($file_image, filesize($file_image)); $ret0 = i5_setparam($req_prepa, 0, $name); $ret1 = i5_setparam($req_prepa, 1, $prenom); $ret2 = i5_setblob($req_prepa, 2, $photo); $ret = i5_execute($req_prepa); if ($ret) {echo "Blob writing successful.\n";} }
i5_bind_param
bool i5_bind_param ( resource stmt, mixed &var1 [, mixed &var2…])
• Description: Binds a PHP variable to an SQL statement parameter in a statement
resource returned by i5_prepare().
Return Values: TRUE on success or FALSE on failure.
Arguments:
• stmt - i5_prepare prepared request ID
• &var1 (…) - Variable to link name
Example: $conn = i5_connect("MY_i5", "USER", "PASSWORD"); if ($conn) { $sql = "SELECT * FROM EACDEMO/SP_CUST WHERE CUST_ID > ? FOR FETCH ONLY"; $stmt = i5_prepare($sql); $lower_limit=1000; $ret = i5_bind_param( $stmt, &$lower_limit ); $result = i5_execute($stm); if (!$result) { echo 'The SQL execute failed '; echo 'SQLSTATE value: ' . i5_errno(); echo ' Message: ' . i5_errormsg(); } else { //read records using i5_fetch_row(($stmt, I5_READ_NEXT ) } }
Zend Server 5 for IBM i Reference Manual
300
i5_setparam
bool i5_setparam ( resource stmt, int position, mixed value)
Description: Allocates parameter to parameterized request.
This function is an alternative to i5_bind_param function (automatically linked). It allows
explicit value allocation to a parameter.
Note: Request must be prepared with i5_prepare function.
Return Values: TRUE on success or FALSE on failure
Arguments:
• stmt - i5_prepare prepared request ID
• position - parameter index (marker) in the request
• value - parameter allocated value
Example 1: $insert = 'INSERT INTO my_library/animals (id, race, name, weight) VALUES (?, ?, ?, ?)'; $req = i5_prepare($insert); $animals = array(1, 'cat', 'Mistinguette', 3.2); if ($req) { $result = i5_execute($req, $animals); if ($result) { print "Mistinguette adding successful.<br>"; } i5_setparam($req, 2, "Hercule"); i5_setparam($req, 3, 3.8); $result = i5_execute($req); if ($result) { print "Hercule adding successful.<br>"; }
Example 2 - Calling stored procedures with IN parameter
The stored procedure in the following example accepts one parameter:
1. Create table
2. An input (IN) parameter that accepts the name of the first animal as input
3. An input-output (INOUT) parameter that accepts the name of the second animal
as input and returns the string TRUE if an animal in the database matches that
name
4. An output (OUT) parameter that returns the sum of the weight of the two
identified animals
API Reference
301
In addition, the stored procedure returns a result set consisting of the animals listed in alphabetic
order starting at the animal corresponding to the input value of the first parameter and ending at
the animal corresponding to the input value of the second parameter. <?php // //CREATE TABLE SQL_LIB/TEST2 (A DATE NOT NULL WITH DEFAULT) // // //create procedure SQL_LIB/test_a1(in parm1 date) //language SQL //begin // //set transaction isolation level UR; //insert into SQL_LIB/TEST2 values(parm1) ; //commit; //end; $user = 'USER'; $password = 'PASS'; $conn_resource = i5_connect('127.0.0.1',$user,$password ); echo "Begin <br>"; if (!$conn_resource) { echo i5_errormsg(); exit(); } $sql = "CALL SQL_LIB/TEST_A1(?)"; $stmt= i5_prepare($sql); $val = '2007-05-22'; $ret = i5_paramdesc($stmt, I5_TYPE_CHAR, 0, 10, 0, I5_INOUT); $ret = i5_setparam($stmt, 0, $val); $result = i5_execute($stmt ); if($result === false){ echo "Execute Error:". i5_errno()." Msg:".i5_errormsg()."<br>"; //echo $err; } else { "<br>executed"; } echo "<br>end"; ?>
i5_paramdesc
bool i5_paramdesc(resource result, int ASType, int sequence, int length, int decimals, int usage).
Description: Stored procedures parameters descriptions
Return Values: TRUE on success or FALSE on failure
Arguments:
• Result - i5_prepare prepared request ID
• ASType – Parameter type (e.g. I5_TYPE_PACKED, I5_TYPE_CHAR)
• Sequence – Parameter sequential number (starting from 0)
• Length – Parameter length
• Decimals – Number of decimal position for the numeric parameter type
• Usage – Parameter input/output (I5_IN, I5_OUT our I5_INOUT)
Zend Server 5 for IBM i Reference Manual
302
Example: $storedProcedure = "CALL LIBRARY/PROGRAM(?,?)"; $result =i5_prepare($storedProcedure); if(!$result) { echo("Prepare failed"); exit(); } // Describe first parameter $ret = i5_paramdesc($result, I5_TYPE_CHAR, 0, 10, 0, I5_IN); $val = "ZENDCORE"; $ret = i5_setparam($result, 0, $val); if(!$ret) { echo("Set Param failed"); exit(); } // Describe second parameter $ret = i5_paramdesc($result, I5_TYPE_CHAR, 1, 10, 0, I5_INOUT); $val2 = " "; $ret = i5_setparam($result, 1, $val2); if(!$ret) { echo("Set Param failed"); exit(); } $hdl = i5_execute($result);
i5_free_query
bool i5_free_query ( resource query )
Description: Frees SQL request result
Removes a query type resource (i5_query or i5_execute) from memory
This function needs only to be called if your script requires too much memory, when a
request returns very large results or if a large requests number are processed and may
overload the web server memory. It is recommended to use this function to free memory
resource used by SQL request. All memory resources are freed when the SQL request is
ended.
Return Values: TRUE on success or FALSE on failure
Arguments: query - query resource
API Reference
303
Transactions
i5_transaction
bool i5_transaction ( int mode [, resource connection] )
Description: Starts transaction.
Return Values: Returns TRUE if transaction has started, FALSE in case of error
Arguments:
• mode - Transaction modes:
o I5_ISOLEVEL_CHG - READ UNCOMMITED, READ WRITE (UR)
- Modified records remain locked.
- Modifications are showed
o I5_ISOLEVEL_CS - READ COMMITED (CS)
- Read records are locked.
- Modified records remain locked.
- Changes are not showed
o I5_ISOLEVEL_ALL - REPEATABLE READ (RS)
- Read records remain locked.
- Modified records remain locked.
- Modifications are not showed.
o I5_ISOLEVEL_NONE - No transactions
- Each record is commited immediately
• connection - result of i5_connect
Example: <?php $conn = i5_connect("MY_i5", "USER", "PASSWORD"); if ($conn) { $res = i5_query("SELECT count(*) FROM animals"); $rec = i5_fetch_array($res ); echo $rec[0] . "\n"; /* Start a transaction */ i5_transaction(I5_ISOLEVEL_NONE, $conn); /* Add records to ANIMALS table */ i5_query("INSERT INTO animals VALUE 'Cat', 'Mistigri'"); $res = i5_query("SELECT count(*) FROM animals"); $rec = i5_fetch_array($res); echo $res[0] . "\n";
i5_commit
bool i5_commit( [string comment] [resource connection])
Description: Commits an in-progress transaction.
Zend Server 5 for IBM i Reference Manual
304
Return Values: TRUE if transaction is valid, FALSE in case of error.
Arguments:
• comment - a transaction comment that will be added to the journal
• Connection - result of i5_connect
Example: $conn = i5_connect("MY_i5", "USER", "PASSWORD"); if ($conn) { $res = i5_query("SELECT count(*) FROM animals"); $rec = i5_fetch_array($res ); echo $rec[0] . "\n"; /* Start a transaction */ i5_transaction(I5_ISOLEVEL_NONE); /* Insert records to ANIMALS table*/ i5_query("INSERT INTO Animals VALUES ('CAT', 'Misstic', 'F', 3.2)"); i5_query("INSERT INTO Language VALUES ('DOG', 'Hercule', 'M', 4.4)"); $res = i5_query("SELECT count(*) FROM animals"); $rec = i5_fetch_array($res); echo $rec[0] . "\n"; /* Commit the changes */ i5_commit($conn); $res = i5_query("SELECT count(*) FROM animals"); $rec = i5_fetch_array($res); echo $rec[0] . "\n"; i5_close($conn); }
i5_rollback
bool i5_rollback ( [resource connection] )
Description: Rolls back a transaction.
Return Values: TRUE on success or FALSE on failure
Arguments:
connection - result of i5_connect
Example: <?php $conn = i5_connect("127.0.0.1", "USER", "PASSWORD"); if ($conn) { /* Start a transaction*/ $tran = i5_transaction(I5_ISOLEVEL_CHG); $res = i5_query("SELECT count(*) FROM my_library/animals"); $rec = i5_fetch_array($res ); echo $rec[0] . " \n"; /* Delete all records from the ANIMALS table */ $res = i5_query("DELETE FROM my_library/animals"); $res = i5_query("SELECT count(*) FROM my_library/animals"); $err = i5_error(); $rec = i5_fetch_array($res); echo $rec[0] . " \n";
API Reference
305
/* Cancel the DELETE operation */ i5_rollback($conn); $res = i5_query("SELECT count(*) FROM my_library/animals"); $rec = i5_fetch_array($res); echo $rec[0] . " \n"; i5_close($conn); } ?>
Zend Server 5 for IBM i Reference Manual
306
Data Queues
i5_dtaq_prepare
resource i5_dtaq_prepare(string name, array description [,int key][,resource connection])
Description: Opens a data queue with optional description.
Return Values: Resource if OK, false if failed.
Arguments:
• name - The queue name
• description - Data description in format defined by program¬_prepare. For more,
see PHP Toolkit Data Description.
• key - key size - for keyed DataQ
• connection - Connection - result of i5_connect
i5_dtaq_receive
mixed i5_dtaq_receive(resource queue[, string/int operator, string key][, int timeout])
Description: Reads data from the data queue.
Return Values: False if could not read because of error or timeout, the data read from
the queue otherwise.
Arguments:
• queue - resource received from dtaq_open
• operator:
• "EQ"
• "GT"
• "LT"
• "GE"
• "LE"
• key- key value to look for
• timeout - timeout value in seconds
API Reference
307
i5_dtaq_send
bool i5_dtaq_send(resource queue, string key, mixed data)
Description: Puts data to the data queue.
Return Values: False if could not be written because of error, true otherwise.
Arguments:
• queue - resource received from dtaq_open
• key - key value to look for
• data - data to put into the queue
The data should conform to the description format, and can be either in flat array or key->value
pair array.
i5_dtaq_close
bool i5_dtaq_close(resource queue)
• Description: Free program resource handle.
• Return Values: Bool success value.
• Arguments: queue - resource received from dtaq_open
Example 1: <?php $description = array("Name"=>"DATA", "Type"=>I5_TYPE_CHAR, "Length"=>50); $dtaqHdl_KEY = i5_dtaq_prepare("EACDEMO/DTAQ_KEY", $description, 5); $ret = i5_dtaq_send($dtaqHdl_KEY, "mykey", "the dataqueue test data"); var_dump($ret); if(!$ret) var_dump(i5_error()); $ret = i5_dtaq_receive($dtaqHdl_KEY, "EQ", "mykey"); var_dump($ret); ?>
Example 2: <?php $descriptionC = array("DSName"=>"PS", "DSParm"=>array( array("Name"=>"PS1", "Type"=>I5_TYPE_CHAR, "Length"=>"10"), array("Name"=>"PS2", "Type"=>I5_TYPE_PACKED, "Length"=>"10.4"), array("Name"=>"PS3", "Type"=>I5_TYPE_CHAR, "Length"=>"10") ) ); $dtaqHdl_KEY = i5_dtaq_prepare("EACDEMO/DTAQ_KEY", $descriptionC, 10); $parameter = array("PS1"=>"test1", "PS2"=>13.1415, "PS3"=>"test2"); $key = "abcd"; $ret = i5_dtaq_send($dtaqHdl_KEY, $key, $parameter); var_dump($ret); $ret = i5_dtaq_receive($dtaqHdl_KEY, "EQ", $key); var_dump($ret); ?>
Zend Server 5 for IBM i Reference Manual
308
System Values
i5_get_system_value
string i5_get_system_value(string name[, resource connection]).
Description: Retrieves system value
Return Values: System value, false if not found.
Arguments:
• name - Name of the system value.
• connection - Connection - result of i5_connect.
Example:
print "Date is: ".i5_get_system_value("QDATE");.
API Reference
309
User Spaces
i5_userspace_create
bool i5_userspace_create(properties[, resource connection]).
Description: Creates a new user space object.
Return Values: Boolean success value
Arguments:
• properties -
o I5_INITSIZE - The initial size of the user space being created. This value
must be from 1 byte to 16, 776, 704 bytes.
o I5_DESCRIPTION - user space description
o I5_INIT_VALUE - The initial value of all bytes in the user space.
o I5_EXTEND_ATTRIBUT - extended attribute. The extended attribute
must be a valid *NAME. For example, an object type of *FILE has an
extended attribute of PF (physical file), LF (logical file), DSPF (display
file), SAVF (save file), and so on.
o I5_AUTHORITY - The authority you give users who do not have specific
private or group authority to the user space
o I5_LIBNAME - Library name where the user space is located
o I5_NAME - User space name (10 char max)
• connection - Result of i5_connect
i5_userspace_prepare
resource i5_userspace_prepare(string name, array description [, resource connection]).
Description: Opens a user space and prepares it to be run.
Return Values: Resource if open succeeded, false if open failed.
Arguments:
• name - User space name in library/object format
• description - Data description in format defined by program_prepare. See PHP
Data Description.
• connection - Result of i5_connect
Zend Server 5 for IBM i Reference Manual
310
i5_userspace_get
resource i5_userspace_get(resource user space, array params)
Description: Retrieve user space data.
Return Values: Boolean success value.
Arguments:
• user space - User Space resource opened by i5_userspace_prepare
• params - Parameters according to description. If given as flat array, then
parameters are assigned in order
i5_userspace_put
bool i5_userspace_put(resource user space, params)
Description: Add user space data
Return Values: Boolean success value.
Arguments:
• user - space User Space resource opened by i5_userspace_prepare
• params - Parameters according to description. If given as flat array, then
parameters are assigned in order
API Reference
311
Job Log List
i5_jobLog_list
resource i5_jobLog_list( [array elements, resource connection] )
Description: Opens job log.
Return Values: The resource for fetching job log list if OK and false if failed.
Arguments:
• elements - JobName, JobUser, JobNumber, MaxMessage, Direction (default is
current job)
• connection - Result of i5_connect
Use i5_jobLog_list_read function to retrieve the job entries from this handle.
i5_jobLog_list_read
array i5_jobLog_list_read(resource list)
Description: Get an array for a job log entry.
Return Values: Array with the message element if OK, false if failed.
Arguments: list - Resource returned by i5_jobLog_list function
i5_jobLog_list_close
bool i5_jobLog_list_close (resource handle)
Description: Close handle received from i5_jobLog_list().
Return Values: Boolean success value
Arguments: handle - Job list handle as returned by i5_jobLog_list()
Zend Server 5 for IBM i Reference Manual
312
Active Job List
i5_job_list
resource i5_job_list( [array elements, resource connection] )
Description: Open active job list.
Return Values: The resource for fetching job list if OK and false if failed.
Arguments:
• elements - JobName, JobUser, JobNumber, JobType, Direction (default is
current job)
• connection - Result of i5_connect
Use i5_job_list_read function to retrieve the job entries from this handle.
i5_job_list_read
array i5_job_list_read(resource list)
Description: Get an array for an active job entry.
Return Values: Array with the job entry element if OK, false if failed.
Arguments: List - Resource returned by i5_job_list function
i5_job_list_close
bool i5_job_list_close (resource handle)
Description: Close handle received from i5_job_list().
Return Values: Boolean success value
Arguments:
• handle - Job list handle as returned by 15_job_list()
API Reference
313
Data Areas
i5_data_area_create
bool i5_data_area_create(string name, int size[, resource connection]).
Description: Creates data area of given size
Return Values: Boolean success value.
Arguments:
• name - Name of the data area.
• size - Size in bytes of the data area.
• connection - result of i5_connect .
i5_data_area_read
string data_area_read(string name[, int offset, int length][, resource connection]).
Description: Reads data from the area
Return Values: String data if read successful, false if read failed (including when offset is
wrong).
Arguments:
• name - Name of the data area.
• offset - Offset for the data.
• length - Length of the data to read, -1 means whole area.
• connection - Connection - result of i5_connect.
If no offset is specified, all the area is read.
Zend Server 5 for IBM i Reference Manual
314
i5_data_area_write
bool data_area_write(string name, string value[, int offset, int length][, resource connection]).
Description: Writes data to the area
Return Values: Boolean success value.
Arguments:
• name - Name of the data area.
• value - Value to write.
• Offset - Offset for the data.
• length - Length of the data to read.
• connection - result of i5_connect
If no offset is specified, all the area is written. If value is shorter than length it is padded to the
length. If it's longer it is truncated.
i5_data_area_delete
bool data_area_delete(string name[, resource connection]).
Description: Delete the data area
Return Values: Boolean success value.
Arguments:
• name - Name of the data area.
• connection - Connection - result of i5_connect.
API Reference
315
Spooled File
i5_spool_list
resource i5_spool_list([array description][, resource connection])
Description: Create an spool file lists, of certain output queue or for all queues.
Return Values: resource if OK, false if failed
Arguments:
• description - The data by which the sppol files will be filtered, array with following
keys:
• username - username that created the job
• outq - qualified name for the output queue containing the spool file
• userdata - the user-supplied key data for the spool file. All keys are optional and
can be provided together
• connection - result of i5_connect.
i5_spool_list_read
array i5_spool_list_read(resource spool_list)
Description: Gets spool file data from the queue.
Return Values: next spool file data array in the list, or false if queue is empty.
The data will be formated using SPLF0300 format. See following link for more details:
http://publib.boulder.ibm.com/infocenter/iseries/v5r4/index.jsp?topic=/apis/QUSLSPL.htm
Arguments: Spool_list resource received from i5_spool_list
i5_spool_list_close
void i5_spool_list_close(resource spool_list)
Description: Free spool list resource
Return Values: Boolean success value
Arguments: Queue - resource received from i5_spool_list
Zend Server 5 for IBM i Reference Manual
316
i5_spool_get_data
string i5_spool_get_data(string spool_name, string jobname, string username, integer
job_number, integer spool_id [,string filename])
Description: Get the data from the spool file.
Return Values: String if no file name passed as parameter, false if function failes
Arguments:
• spool_name - The spool file name
• job_name - The name of the job that created the file
• job_number - The number of the job that created the file
• username - The username of the job that created the file
• spool_id - ID of the spool file in the queue (as returned by outq_read)
• filename - IFS filename to store the data. If not provided, the data is returned as
string
API Reference
317
Object Listing
i5_objects_list
resource i5_objects_list(string library, [string name, string type, resource connection])
Description: Open an object list.
Return Values: Resource for fetch if everything is OK, false on error.
Arguments:
• library - Library name (can be also *CURLIB or I5_CURLIB)
• name - Name or wildcard of objects to read, default is ”r;all”.
• type - Object type to fetch (*ALL or I5_ALL_OBJECTS for all)
• connection - Connection - result of i5_connect
i5_objects_list_read
array i5_objects_list_read (resource list)
Description: Get an array for an object list entries.
Return Values: Array with the object element if OK; false if failed.
Arguments: List - Resource returned by i5_objects_list
i5_ objects_list _close
bool i5_ objects_list_close (resource handle)
Description: Close handle received from i5_ objects_list ().
Return Values: Boolean success value
Arguments: handle - Object list handle as returned by i5_ objects_list ()
Zend Server 5 for IBM i Reference Manual
318
PHP Toolkit Data Description
Short Data Format
Data structures are defined via PHP as follows:
Main data is an array of key-value pairs, where key is the parameter name and value is the array
of:
type - one of Data types
type modifier
• for CHAR, BYTE - integer describing length. Length can be number or name of
the variable holding the length in the data structure.
• for PACKED, ZONED - string "NUMBER.NUMBER" defining length and precision
• for STRUCT - array containing data definition of the structure
• for INT, FLOAT - ignored
direction (optional) - one of I/O values
count (optional)
if integer - repetition count if the field is an array
if string - reference to the repetition count field
Example: <?php $person = array( "name" => array(I5_TYPE_CHAR, 50), "age" => array(I5_TYPE_INT, 0), "ID" => array(I5_TYPE_BYTE, 10) ); $data = array( "person" => array(I5_TYPE_STRUCT, $person), "last_accesses" => array(I5_TYPE_INT, 0, I5_OUT, 3), "account_balance" => array(I5_TYPE_PACKED, "10.3", I5_OUT) ); $prg = i5_program_prepare("MYLIB/PERSONPGM", $data); ?>
In any place data description is required; the name of the file with external data structure
description can be used instead.
API Reference
319
Long Data Format
Data structure is defined via PHP as follows:
Main data is the array of values, having following fields:
Name - name of the field
Type - type of the field, can be one of Data types
Length
• for CHAR, BYTE - integer describing length. Length can be number or name of
the variable holding the length in the data structure.
• for PACKED, ZONED - string "NUMBER.NUMBER" defining length and precision
• for STRUCT - array containing data definition of the structure
• for INT, FLOAT - ignored
IO - can be one of I/O values
Data structure is defined via PHP as follows:
• DSName - name of the parameter
• DSParm (optional) - array of the parameter of the Data structure. Each
parameter is defined by a data definition in the same format as described here.
• Count (optional) - repetition count if the field is an array
• CountRef (optional) - reference to the repetition count if the field is an array
Example: <?php $description = Array( array("Name"=>"P1", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10", "count"=>5), array("Name"=>"P2C", "IO"=>I5_INOUT, "Type"=>I5_TYPE_LONG), array("Name"=>"P2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>"1", "countRef"=>"P2C"), array("DSName"=>"PS", "count"=>2, "DSParm"=>array( array("Name"=>"PS1", "IO"=>I5_IN|I5_OUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10"), array("Name"=>"PS2", "IO"=>I5_IN|I5_OUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10"), array("Name"=>"PS3", "IO"=>I5_IN|I5_OUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10"), ) ) ); $prg = eac_program_prepare("MYLIB/PERSONPGM", $description); ?>
Zend Server 5 for IBM i Reference Manual
320
Data Types
I5_TYPE_CHAR
I5_TYPE_PACKED
I5_TYPE_FLOAT
I5_TYPE_STRUCT (long format uses
DSName to define structure)
I5_TYPE_INT
I5_TYPE_ZONED
I5_TYPE_BYTE
I/O Values
I5_IN
I5_OUT
These values can be OR'ed together to get input-output value:
I5_TYPE_RETVAL - return value for procedure call
I5_TYPE_BYVAL - by-value parameter for procedure call
default is input
Error Types
I5_ERR_OK
I5_ERR_TOOMUCHOPEN
FILE
I5_ERR_INVALIDPTR
I5_ERR_INVALIDFIELDNB
R
I5_ERR_INVALIDKEYNBR
I5_ERR_INVALIDOPENMO
DE
I5_ERR_RECORDLOCKED
I5_ERR_FILELIMITS
I5_ERR_INVALIDSEQ
I5_ERR_NOLINKDEFINED
I5_ERR_NULLNOTALLOW
ED
I5_ERR_WRONGLOGIN
I5_ERR_FIELDNULL
I5_ERR_INVALIDINFO
I5_ERR_PHP_COMMAND_E
RROR
I5_ERR_PHP_GET_SYSVAL
I5_ERR_PHP_BAD_DEF
I5_ERR_PHP_NO_DS_VALU
E
I5_ERR_ENDOFOCC
I5_ERR_DESC_UNEXP
I5_ERR_DESC_WRONG_DA
TAOP
I5_ERR_PHP_BAD_PROG_
NAME
I5_ERR_PHP_NOT_DTAQ_K
EY
I5_ERR_PHP_DESC_EMPTY
I5_ERR_PHP_LIST_PROP
I5_ERR_PHP_API_LENGTH
I5_ERR_ERROR
I5_ERR_PHP_HDLBAD
I5_ERR_PHP_OPTIONSNUM
BER
I5_ERR_PHP_TYPEPARAM
I5_ERR_PHP_TYPEGET
I5_ERR_PHP_BOOKMARK
I5_ERR_PHP_CALL_BINDPA
RAM
I5_ERR_PHP_BINDPARAM
I5_ERR_PHP_BLOBSIZE
I5_ERR_PHP_INTERNAL
I5_ERR_PHP_NO_COMMAND
I5_ERR_PHP_NO_KEYNAME
I5_ERR_PHP_NO_ZVALUE
I5_ERR_PHP_DATAREA_REA
D
I5_ERR_PHP_ELEMENT_MIS
SING
API Reference
321
I5_ERR_RECORDCHANG
ED
I5_ERR_NOTINTRAN
I5_ERR_PHP_HDLCONN
I5_ERR_PHP_OPTIONSTY
PE
I5_ERR_PHP_RESOURCE
_BAD
I5_ERR_PHP_NBPARAM_
BAD
I5_ERR_PHP_OPERATOR
_BAD
I5_ERR_PHP_NOT_BOOK
MARK
I5_ERR_PHP_GETPARAM
I5_ERR_PHP_PARAM_DE
SC
I5_ERR_PHP_VARIABLE
I5_ERR_PHP_EXECUTE
I5_ERR_PHP_EMPTY_AR
RAY
I5_ERR_PHP_NO_PARMN
AME
I5_ERR_MEMALLOC
I5_ERR_FIELDNOTFOUND
I5_ERR_INVALIDKEYLEN
I5_ERR_NOTENABLETOUP
DATE
I5_ERR_RECORDNOTFOUN
D
I5_ERR_BEOF
I5_ERR_NOTCONNECTED
I5_ERR_NORANGESET
I5_ERR_NOCURRENTRECO
RD
I5_ERR_BADSESSION
I5_ERR_NOTENOUGHRIGH
TS
I5_ERR_INVALIDTYPE
I5_ERR_NOTTYPEPROPER
TY
I5_ERR_ALLREADYINTRAN
I5_ERR_PHP_HDLDFT
I5_ERR_PHP_BAD_KEYNAM
E
I5_ERR_PARAMNOTFOUND
I5_ERR_PHP_BAD_DS_INPU
T
I5_ERR_DQDESC_UNSUPP
I5_ERR_INCORRECTVALUE
I5_ERR_PHP_AS400_MESSA
GE
I5_ERR_PHP_DTAQ_BADKE
Y
I5_ERR_PHP_BAD_LEN_PRO
P
I5_ERR_PHP_SPOOL_FILE_F
OPEN
Data structures are defined via PHP as follows:
Main data is the array of values, having the following fields:
Name - name of the field
Type - type of the field, can be:
• I5_TYPE_SHORT
• I5_TYPE_LONG
• I5_TYPE_DOUBLE
• I5_TYPE_BIN
• I5_TYPE_DATE
• I5_TYPE_TIME
• I5_TYPE_TIMESTP
• I5_TYPE_DBCS
Zend Server 5 for IBM i Reference Manual
322
• I5_TYPE_LONG8
• I5_TYPE_NUMERICCHAR
• I5_TYPE_BLOB
• I5_TYPE_CLOB
• I5_TYPE_UNICODE
• I5_TYPE_VARCHAR
• I5_TYPE_VARBIN
Length
• For CHAR, BYTE - integer describing length. Length can be number or name of
the variable holding the length in the data structure.
• For PACKED, ZONED - string "NUMBER.NUMBER" defining length and
precision
• For STRUCT - array containing data definition of the structure
• For INT, FLOAT - ignored
IO
• I5_IN
• I5_OUT
• default is input, these values can be OR'ed together to get input-output value
Count (optional) - repetition count if the field is an array
CountRef (optional) - reference to the repetition count if the field is an array
Data structure is defined via PHP as follows:
DSName - name of the parameter
DSParm (optional) - array of the parameter of the Data structure. Each parameter is defined by a simple data definition.
Example: <?php $description = Array( array("Name"=>"P1", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10", "count"=>5), array("Name"=>"P2C", "IO"=>I5_INOUT, "Type"=>I5_TYPE_LONG), array("Name"=>"P2", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>"1", "countRef"=>"P2C"), array("DSName"=>"PS", "count"=>2, "DSParm"=>array( array("Name"=>"PS1", "IO"=>I5_IN|I5_OUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10"), array("Name"=>"PS2", "IO"=>I5_IN|I5_OUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10"), array("Name"=>"PS3", "IO"=>I5_IN|I5_OUT, "Type"=>I5_TYPE_CHAR, "Length"=>"10"), ) ) ); $prg = i5_program_prepare("MYLIB/PERSONPGM", $description); ?>
API Reference
323
Command Constants
I5_CURLIB (Default Value = "*CURLIB")
I5_ALL_OBJECTS (Default value = "*ALL")
I5_ALL_NAMES (Default value = "*")
I5_LIST_MINIMAL
I5_LIST_DETAILED
I5_LIST_FULL
Active Job (i5_job_list) array elements constants
i5_JOB_ACT_JOB_STS
I5_JOB_BRKMSG
I5_JOB_CNTRYID
I5_JOB_POOL_ID
I5_JOB_PROCESS_UNIT_TIM
E_DB
I5_JOB_DATETIME_SCHED
I5_JOB_DATSEP
I5_JOB_DFTWAIT
I5_JOB_DFTCCSID
I5_JOB_ENDSEV
I5_JOB_FUNC_NAME
I5_JOB_GRPPRFNAME
I5_JOB_ACCOUNT_CODE
I5_JOB_QUEUE_NAME
I5_JOB_JOBMSGQFL
I5_JOB_USRID_SETTING
I5_JOB_TYPE_ENHANCED
I5_JOB_LOGCLPGM
I5_JOB_MODE_NAME
I5_JOB_MAX_THREADS
I5_JOB_MSGRPL
I5_JOB_ MCH_LCKW
I5_JOB_OUTQ_NAME
I5_JOB_PRTDEVNAME
I5_JOB_PROG_RETCODE
I5_JOB_RESPONSE_TIME
I5_JOB_ALW_MULTI_THRE
ADS
I5_JOB_CANCEL_KEY
I5_JOB_USRPRF
I5_JOB_CHAR_ID_CTRL
I5_JOB_DATETIME_ACTIVE
I5_JOB_DATETIME_JOBQ
I5_JOB_DBCS_CAP
I5_JOB_DEVRCYACN
I5_JOB_DECFMT
I5_JOB_ENDSTS
I5_JOB_FUNC_TYPE
I5_JOB_GRPPRFNAME_SU
P
I5_JOB_DATE
I5_JOB_QUEUE_PTY
I5_JOB_JOBMSGQ_SIZE
I5_JOB_END_REASON
I5_JOB_LANGID
I5_JOB_LOGSEV
I5_JOB_MAX_PROC_UNIT_
TIME
I5_JOB_MAX_TMP_STG_M
I5_JOB_INTERACTIVE_TRS
I5_JOB_NONDB_LCKW
I5_JOB_OUTQ_PTY
I5_JOB_PURGE
I5_JOB_ACT_ENDJOB_ST
S
I5_JOB_CCSID
I5_JOB_COMPLETION_ST
S
I5_JOB_PROCESS_UNIT_
TIME
I5_JOB_DATETIME_IN
I5_JOB_DATFMT
I5_JOB_DDM_HANDLE
I5_JOB_DEVNAME
I5_JOB_DATETIME_END
I5_JOB_EXITKEY
I5_JOB_SIGNED_JOB
I5_JOB_INQMSGRPLY
I5_JOB_DESC_NAME
I5_JOB_SWITCHES
I5_JOB_USRID
I5_JOB_LOG_PENDING
I5_JOB_LOGLVL
I5_JOB_LOGTEXT
I5_JOB_MAX_TMP_STG_K
I5_JOB_MEM_POOL_NAM
E
I5_JOB_DB_LCKWAIT
I5_JOB_AUX_IOREQ
I5_JOB_PRTTEXT
Zend Server 5 for IBM i Reference Manual
324
I5_JOB_STRSEQ
I5_JOB_SBMJOB
I5_JOB_SYSPOOLID
I5_JOB_SGNSTS
I5_JOB_TIMSEP
I5_JOB_TMPSTGK
I5_JOB_TIME_NONDB_LCKW
I5_JOB_PENDING_SGNSET
I5_JOB_RUNPTY
I5_JOB_STS_MSGHDL
I5_JOB_SBMMSGQ
I5_JOB_SPCLENV
I5_JOB_SVRTYPE
I5_JOB_TIMESLICE
I5_JOB_TIME_DB_LCKW
I5_JOB_THREADCNT
I5_JOB_PRD_RETCODE
I5_JOB_PROCESS_ID
I5_JOB_ROUTING_DATA
I5_JOB_STS_JOBQ
I5_JOB_SBSD
I5_JOB_SGNBLK_MASK
I5_JOB_SPLFILE_ACTION
I5_JOB_TIMESLICE_END
I5_JOB_TIME_MCH_LCKW
Job Log Constants (i5_jobLog_list) array elements constants
I5_LOBJ_MESSAGE_SEVERITY
I5_LOBJ_MESSAGE_IDENTIFIE
R
I5_LOBJ_MESSAGE_FILELIBRA
RY
I5_LOBJ_TIMESENT_MICRO
I5_LOBJ_MESSAGE_TY
PE
I5_LOBJ_DATASENT
I5_LOBJ_MESSAGE_FILENA
ME
I5_LOBJ_TIMESENT
I5_LOBJ_ALERTOPT
I5_LOBJ_MSGDTA
I5_LOBJ_MSGHLPDTAFMT
I5_LOBJ_SNDTYPE
I5_LOBJ_SNDPROC
I5_LOBJ_RCVMOD
I5_LOBJ_PROBLEMID
I5_LOBJ_RQSLVL
I5_LOBJ_RPLDATA1
I5_LOBJ_MSGHLP
I5_LOBJ_DFTRPLY
I5_LOBJ_SNDPGM
I5_LOBJ_RCVTYPE
I5_LOBJ_RCVPROC
I5_LOBJ_RPLYSTS
I5_LOBJ_TXTCCSID
I5_LOBJ_MSG
I5_LOBJ_MSGHLPDTA
I5_LOBJ_SNDNAME
I5_LOBJ_SNDMOD
I5_LOBJ_RCVPROG
I5_LOBJ_MSGFILE
I5_LOBJ_RQSSTS
I5_LOBJ_DATACCSID
Errors
I5_TYPE_CHAR
I5_ERR_OK
I5_ERR_ERROR
I5_ERR_TOOMUCHOPENFILE
I5_ERR_MEMALLOC
API Reference
325
Data Retrieval Errors
I5_ERR_INVALIDPTR
I5_ERR_FIELDNOTFOUND
I5_ERR_INVALIDFIELDNBR
I5_ERR_INVALIDKEYLEN
I5_ERR_INVALIDKEYNBR
I5_ERR_NOTENABLETOUPDATE
I5_ERR_INVALIDOPENMODE
I5_ERR_RECORDNOTFOUND
I5_ERR_RECORDLOCKED
I5_ERR_BEOF
I5_ERR_FILELIMITS
I5_ERR_NOTCONNECTED
I5_ERR_INVALIDSEQ
I5_ERR_NORANGESET
I5_ERR_NOLINKDEFINED
I5_ERR_NOCURRENTRECORD
I5_ERR_NULLNOTALLOWED
I5_ERR_BADSESSION
I5_ERR_WRONGLOGIN
I5_ERR_NOTENOUGHRIGHTS
I5_ERR_FIELDNULL
I5_ERR_INVALIDTYPE
I5_ERR_INVALIDINFO
I5_ERR_NOTTYPEPROPERTY
I5_ERR_RECORDCHANGED
I5_ERR_ALLREADYINTRAN
I5_ERR_NOTINTRAN
Function Errors
I5_ERR_PHP_HDLDFT
I5_ERR_PHP_HDLCONN
I5_ERR_PHP_HDLBAD
I5_ERR_PHP_OPTIONSTYPE
I5_ERR_PHP_OPTIONSNUMBER
I5_ERR_PHP_RESOURCE_BAD
I5_ERR_PHP_TYPEPARAM
I5_ERR_PHP_NBPARAM_BAD
I5_ERR_PHP_TYPEGET
I5_ERR_PHP_OPERATOR_BAD
I5_ERR_PHP_BOOKMARK
I5_ERR_PHP_NOT_BOOKMARK
I5_ERR_PHP_CALL_BINDPARAM
I5_ERR_PHP_GETPARAM
I5_ERR_PHP_BINDPARAM
I5_ERR_PHP_PARAM_DESC
I5_ERR_PHP_BLOBSIZE
I5_ERR_PHP_VARIABLE
I5_ERR_PHP_NO_ZVALUE
I5_ERR_PHP_COMMAND_ERROR
I5_ERR_PHP_DATAREA_READ
I5_ERR_PHP_GET_SYSVAL
I5_ERR_PHP_ELEMENT_MISSING
I5_ERR_PHP_BAD_DEF
I5_ERR_PHP_BAD_KEYNAME
I5_ERR_PHP_NO_DS_VALUE
I5_ERR_PARAMNOTFOUND
I5_ERR_ENDOFOCC
I5_ERR_PHP_BAD_DS_INPUT
I5_ERR_DESC_UNEXP
I5_ERR_DQDESC_UNSUPP
I5_ERR_DESC_WRONG_DATAOP
I5_ERR_INCORRECTVALUE
I5_ERR_PHP_BAD_PROG_NAME
I5_ERR_PHP_AS400_MESSAGE
I5_ERR_PHP_NOT_DTAQ_KEY
Zend Server 5 for IBM i Reference Manual
326
I5_ERR_PHP_INTERNAL
I5_ERR_PHP_EXECUTE
I5_ERR_PHP_NO_COMMAND
I5_ERR_PHP_EMPTY_ARRAY
I5_ERR_PHP_NO_KEYNAME
I5_ERR_PHP_NO_PARMNAME
I5_ERR_PHP_DTAQ_BADKEY
I5_ERR_PHP_DESC_EMPTY
I5_ERR_PHP_BAD_LEN_PROP
I5_ERR_PHP_LIST_PROP
I5_ERR_PHP_SPOOL_FILE_FOPEN
I5_ERR_PHP_API_LENGTH
API Reference
327
Program Samples
i5 Program Call
The i5 program call process contains the following PHP functions:
i5_connect
i5_program_prepare
i5_program_call
i5_close
The sample PHP script below invokes an i5 program: <?php $conn = i5_connect($i5_server_ip, $i5_uname, $i5_pass); if ($conn === false) { print ("FAIL : Failed to connect to server : $i5_server_ip, with user name : $i5_uname and password : $i5_pass <br>\n"); $errorTab = i5_error(); var_dump($errorTab); die(); } /* Prepare File for execution */ $desc = array ( array ("name"=>"code", "io"=>I5_INOUT, "type" => I5_TYPE_CHAR, "length"=> "10"), array ("name"=>"name", "io"=>I5_INOUT, "type" => I5_TYPE_CHAR, "length"=> "10"), ); $prog = i5_program_prepare("EACDEMO/TESTSTP2", $desc); if ($prog === FALSE) { $errorTab = i5_error(); echo "Program prepare failed <br>\n"; var_dump($errorTab); die(); } /* Execute Program */ $params = array ("code"=>" ","name"=>" "); $retvals = array("code"=>"code","name"=>"name"); $ret = i5_program_call($prog, $params, $retvals) ; echo "The return values are: <br>", "Name: ", $name, "<br> Code: ", $code, "<br>"; if ($ret === FALSE) { $errorTab = i5_error(); echo "FAIL : i5_program_call failure code <br>"; var_dump($errorTab); die(); } $close_val = i5_program_close ($prog); if ($close_val === false ) { print ("FAIL : i5_program_close returned fales, closing an open prog.<br>\n"); $errorTab = i5_error(); var_dump($errorTab); } i5_close($conn) || print ("FAIL : Failed to disconnect from server :$i5_server_ip"); ?>
Zend Server 5 for IBM i Reference Manual
328
Service Program
<?php // This program calls a service program (*SRVPGM), which was created using the following i5/OS commands: // CRTRPGMOD SRCFILE(EACDEMO/QRPGLESRC) SRCMBR(TESTMOD) // CRTSRVPGM SRVPGM(EACDEMO/TESTSTRUC2) MODULE(EACDEMO/TESTMOD) EXPORT(*ALL) $Hdlcon = i5_connect($connect, $user, $pass, array(I5_OPTIONS_JOBNAME => "PHPAIX")); if (is_bool($Hdlcon) && $Hdlcon == FALSE) die(i5_errormsg()); echo "Connected!<BR>"; $desc = array ( array ("name"=>"code", "io"=>I5_INOUT, "type" => I5_TYPE_CHAR, "length"=> "10"), array ("name"=>"name", "io"=>I5_INOUT, "type" => I5_TYPE_CHAR, "length"=> "10"), ); $ret = $prog = i5_program_prepare("EACDEMO/TESTP2SRV(TESTSTMOD)", $desc); if (!$ret){ getError(I5_ERR_OK, -1); } else { echo "1. Prepare - It works! <br>"; } $hdlPgm = $ret; $parameter = array("code"=>" ", "name"=>" "); $parmOut = array("code"=>"code", "name"=>"name"); $ret = i5_program_call($hdlPgm, $parameter, $parmOut); if (!$ret){ getError(I5_ERR_OK, -1); } else { echo "2. Call - It works! <br>"; } echo "code : $code<BR> name : $name<BR>"; ?>
Data Retrieval
<?php $Hdlcon = i5_connect($connect, $user, $pass); if (!$Hdlcon) { die(i5_errormsg()); } $HdlFile = i5_open("eacdemo/sp_cust", I5_OPEN_READWRITE, $Hdlcon); if (!is_bool($HdlFile)) { echo "It works <br>\n"; } $fealds = i5_list_fields($HdlFile); $fetch_array = i5_fetch_array($HdlFile,I5_READ_FIRST); $fetch_assoc = i5_fetch_assoc($HdlFile,I5_READ_NEXT); $fetch_object = i5_fetch_object($HdlFile,I5_READ_PREV); $fetch_row = i5_fetch_row($HdlFile,I5_READ_LAST); print_r($fetch_array); echo"<br>\n <br>\n"; print_r($fetch_assoc); echo"<br>\n <br>\n"; print_r($fetch_object); echo"<br>\n <br>\n"; print_r($fetch_row); echo"<br>\n <br>\n"; $info = i5_info($HdlFile,1); print_r($info); echo"<br>\n <br>\n"; $field_length = i5_field_len($HdlFile,1); $field_name = i5_field_name($HdlFile,1); $field_type = i5_field_type($HdlFile,1); $field_scale = i5_field_scale($HdlFile,1); echo "Field Name: {$field_name} <br>\n Field Lenght: {$field_length} <br>\n Field Type: {$field_type} <br>\n Field Scale: {$field_scale}<br>\n"; $list_fields = i5_list_fields($HdlFile); print_r($list_fields); $num_fields = i5_num_fields($HdlFile); echo "<br>\n {$num_fields}"; $result = i5_result($HdlFile,2);
API Reference
329
echo "<br>\n {$result}"; i5_close($Hdlcon); ?>
Native File Access sample
<?php $conn = i5_connect($connect, $user, $pass); if ($conn === false) die(i5_errormsg()); $file = i5_open("EACDEMO/SP_CUST", I5_OPEN_READWRITE, $conn); if ($file === false) die(i5_errormsg()); i5_addnew($file); i5_setvalue($file,array('11111', 'Kauai', 'Erica', 'Norm', '4-976 Hwy', 'Suite 103', 'Kapaa', 'HI', '94766', 'US', '808-555', '808-555')); i5_update($file); i5_edit($file); i5_delete($file); i5_cancel_edit($file); $tabf = array(1500); i5_range_from($file, FALSE, $tabf); $tabf = array(1600); i5_range_to($file, FALSE, $tabf); $fetch = i5_fetch_row($file, I5_READ_FIRST); echo $fetch[0], " ",$fetch[1], " ", $fetch[2], "<br>"; $fetch = i5_fetch_row($file, I5_READ_NEXT); echo $fetch[0], " ",$fetch[1], " ", $fetch[2], "<br>"; i5_range_clear($file); $fetch = i5_fetch_row($file, I5_READ_FIRST); echo $fetch[0], " ",$fetch[1], " ", $fetch[2], "<br><br>"; i5_data_seek($file, 2); $rowTab = i5_fetch_row($file); echo $rowTab[0], " ",$rowTab[1], " ", $rowTab[2], "<br>"; $tab=array(1510); $seek = i5_seek($file, "=", $tab); $rowTab = i5_fetch_row($file); echo $rowTab[0], " ",$rowTab[1], " ", $rowTab[2], "<br>"; $id = i5_bookmark($file); echo $id, "<br>"; i5_new_record($file, array('1229', 'Kauai Dive Shoppe ', 'Irica', 'Norman', '4-976 Sugarloaf Hwy', 'Suite 103', 'Kapaa Kauai', 'HI', '94766-1234', 'US', '808-555-0269', '808-555-0278')); i5_fetch_row($file,I5_READ_FIRST); i5_update_record($file,array("FIRSTNAME"=>"Lina","LASTNAME"=>"Karasko")); i5_delete_record($file); $keys = i5_get_keys($file); echo $keys; i5_free_file($file); ?>
Zend Server 5 for IBM i Reference Manual
330
Data Queues
Data Queue Without Key
<?php $conn = i5_connect($i5_server_ip, $i5_uname, $i5_pass); if (!$conn) { die(i5_errormsg()); } $description = array("Name"=>"DATA", "Type"=>I5_TYPE_CHAR, "Length"=>"50"); $queue = i5_dtaq_prepare("eacdemo/DTAQ_FIFO", $description); $ret = i5_dtaq_send($queue,"","the dataqueue test data"); var_dump($ret); echo "<br>\n"; if(!$ret) var_dump(i5_error()); $ret = i5_dtaq_receive($queue); var_dump($ret); i5_dtaq_close($queue); i5_close($conn); ?>
Data Queue With key
<?php $conn = i5_connect($i5_server_ip, $i5_uname, $i5_pass); if (!$conn) { die(i5_errormsg()); } $descriptionC = array("DSName"=>"PS", "DSParm"=>array( array("Name"=>"PS1", "Type"=>I5_TYPE_CHAR, "Length"=>"10"), array("Name"=>"PS2", "Type"=>I5_TYPE_PACKED, "Length"=>"10.4"), array("Name"=>"PS3", "Type"=>I5_TYPE_CHAR, "Length"=>"10") ) ); $dtaqHdl_KEY = i5_dtaq_prepare("EACDEMO/DTAQ_KEY", $descriptionC,10); var_dump($dtaqHdl_KEY); echo "<br>\n"; $parameter = array("PS1"=>"test1", "PS2"=>13.1415, "PS3"=>"test2"); $key = "abcd"; $ret = i5_dtaq_send($dtaqHdl_KEY, $key, $parameter); var_dump($ret); echo "<br>\n"; $ret = i5_dtaq_receive($dtaqHdl_KEY, "EQ", $key); var_dump($ret); i5_dtaq_close($dtaqHdl_KEY); i5_close($conn); ?>
System Values
<?php $conn = i5_connect($i5_server_ip, $i5_uname, $i5_pass); print "Date is: ".i5_get_system_value("QDATE"); i5_close($conn); ?>
User Spaces
<?php $conn = i5_connect($connect, $user, $pass); if (!$Hdlcon) { die(i5_errormsg()); } $property = array( I5_INITSIZE=>10,
API Reference
331
I5_DESCRIPTION=>"Created by PHP", I5_INIT_VALUE=>"A", I5_EXTEND_ATTRIBUT=>"File", I5_AUTHORITY=>"*ALL", I5_LIBNAME=>"EACDEMO", I5_NAME=>"USERSPACE" ); $ret = i5_userspace_create($property); if ($ret) echo "1. It works! <br>\n"; $description = Array( array("Name"=>"filler0", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>"64"), array("Name"=>"generic", "IO"=>I5_INOUT, "Type"=>I5_TYPE_LONG), array("Name"=>"filler", "IO"=>I5_INOUT, "Type"=>I5_TYPE_CHAR, "Length"=>"36"), array("Name"=>"outputsize", "IO"=>I5_INOUT, "Type"=>I5_TYPE_LONG), array("Name"=>"offsetInput", "IO"=>I5_INOUT, "Type"=>I5_TYPE_LONG) ); $parameter = Array( "filler0"=>"AAAA", "generic"=>10, "filler"=>"BBB", "outputsize"=>100, "offsetInput"=> 0 ); $parmOut = array("filler0"=>"filler0", "filler"=>"filler", "generic"=>"generic", "outputsize"=>"outputsize", "offsetInput"=>"offsetInput"); $UspcHdlBad = i5_userspace_prepare("EACDEMO/USERSPACE", $description); if ($UspcHdlBad) echo "2. It works! <br>\n"; $ret = i5_userspace_put($UspcHdlBad, $parameter); if ($ret) echo "3. It works! <br>\n"; $ret = i5_userspace_get($UspcHdl, $parmOut); if (!$ret) echo "4. It works! <br>\n"; if ($ret) echo "5. It works!"; var_dump($ret);*/ $ret = i5_command("DLTUSRSPC USRSPC(EACDEMO/USERSPACE)"); if ($ret) echo "6. It works!"; i5_close($conn); ?>
Active Job List
<?php $Hdlcon = i5_connect($connect, $user, $pass, array(I5_OPTIONS_JOBNAME => "PHPAIX")); if (is_bool($Hdlcon) && $Hdlcon == FALSE){ die(i5_errormsg());} echo "i5_job_list: "; $ret = i5_job_list(); if (!$ret) die(i5_errormsg()); else echo "It works!<br>"; $listHdl = $ret; echo 'i5_job_list_read: '; $ret = i5_job_list_read($listHdl); if (!$ret) die(i5_errormsg()); else echo "It works! <br>"; echo 'i5_job_list_close: '; $ret = i5_job_list_close($listHdl); if (!$ret) { die(i5_errormsg()); } else { echo "It works! <br>";
Zend Server 5 for IBM i Reference Manual
332
} $listHdl = i5_job_list(array(I5_JOBNAME=>"*ALL", I5_JOBTYPE=>"S")); if (is_bool($listHdl)) die(i5_errormsg()); else echo "List <BR>"; $a= 0; $ret = true; while($ret && $a < 3){ echo "<p>Message $a<BR>"; $ret = i5_job_list_read($listHdl); $a ++; if (is_bool($ret)) die(i5_errormsg()); else { print_r($ret);echo "<p>"; echo "Job queue Name : " . $ret[I5_JOB_QUEUE_NAME] . ", Response Id : " . $ret[I5_JOB_PROCESS_ID] . "<BR>"; echo "I5_JOB_JOBMSGQFL : " . $ret[I5_JOB_JOBMSGQFL] . "<BR>"; } } $ret = i5_job_list_close($listHdl); ?>
Job Log List
<?php $Hdlcon = i5_connect($connect, $user, $pass, array(I5_OPTIONS_JOBNAME => "PHPAIX")); if (is_bool($Hdlcon) && $Hdlcon == FALSE){ die(i5_errormsg());} $listHdl = i5_jobLog_list(); if (is_bool($listHdl)) die(i5_errormsg()); else echo "List<BR>"; $a= 0; $ret = true; while($ret && $a < 2){ echo "Message $a<BR>"; $ret = i5_jobLog_list_read($listHdl); $a ++; if (is_bool($ret)) die(i5_errormsg()); else { print_r($ret);echo "<p>"; echo "Message : " . $ret[I5_LOBJ_MSG]. ",<BR> data : ". $ret[I5_LOBJ_MSGDTA] . "<BR>"; } } $ret = i5_jobLog_list_close($listHdl); if (is_bool($ret)) die(i5_errormsg()); else { print_r($ret);echo "<p>"; echo "Message : " . $ret[I5_LOBJ_MSG]. ",<BR> data : ". $ret[I5_LOBJ_MSGDTA] . "<BR>"; ?>
API Reference
333
Data Areas
<?php $Hdlcon = i5_connect($connect, $user, $pass); if (!$Hdlcon) { die(i5_errormsg()); } $ret = i5_data_area_create("eacdemo/MYDTA", "50"); if ($ret) echo "1.It works! <br>"; $ret = i5_data_area_write("eacdemo/MYDTA", "'coucou'"); if ($ret) echo "3.It works! <br>"; $ret = i5_data_area_read("eacdemo/MYDTA", 2, 4); if ($ret) echo "4.It works!: ", $ret, "<br>"; $ret = i5_data_area_read("eacdemo/MYDTA"); if ($ret) echo "5.It works!: ", $ret, "<br>"; $ret = i5_data_area_write("eacdemo/MYDTA", "'lina'", 5, 45); if ($ret) echo "6.It works! <br>"; $ret = i5_data_area_read("eacdemo/MYDTA", 1, 5); if ($ret) echo "7.It works!: ", $ret, "<br>"; $ret = i5_data_area_read("eacdemo/MYDTA"); if ($ret) echo "8.It works!: ", $ret, "<br>"; $ret = i5_data_area_delete("eacdemo/MYDTA"); if ($ret) echo "9.It works! <br>"; ?>
Spooled Files
<?php $conn = i5_connect($connect, $user, $pass); if (!$conn) die("<br>Connect fail"); echo "<br>================<br>"; echo "<br>connected."; $spool = i5_spool_list(array("username"=>"lina"),$conn); if ($spool) { $count = 0; while (($a = i5_spool_list_read($spool)) && ($count <= 2)) { echo "<br>================<br>"; var_dump($a); echo "<br>data {$count}:<br>"; $data = i5_spool_get_data($a['SPLFNAME'], $a['JOBNAME'], $a['USERNAME'], $a['JOBNBR'], $a['SPLFNBR']); if (is_bool($data)) var_dump(i5_error()); var_dump($data); $count++; } i5_spool_list_close($spool); } else echo "No spool today."; i5_close($conn); XII. Object Listing $conn = i5_connect($connect, $user, $pass); if (!$conn) die("<br>Connect fail"); echo "<br>================<br>"; echo "<br>connected. <br>"; $objects = i5_objects_list("EACDEMO", "*ALL", "*PGM"); if ($objects) echo "1.It works! <br>"; $HdlObj = $objects; $objects = i5_objects_list_read($HdlObj); if (!is_bool($objects)) { echo "2.It works! <br>"; print_r($objects); echo "<br>"; } $continue = true;
Zend Server 5 for IBM i Reference Manual
334
$count = 0; while($continue) { $objects = i5_objects_list_read($HdlObj); if (is_bool($objects) && $objects == FALSE ) $continue = false; else { echo "3.It works! <br>"; print_r($objects); echo "<br>"; } $count ++; if ($count == 2) break; } $objects = i5_objects_list_close($HdlObj); if (is_bool($objects) && $objects == FALSE) $continue = false; else echo "4.It works! <br>"; ?>
API Reference
335
PCML Program Call - PCML Description Used in the PHP Program <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>Program call example using PCML</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <link href="style.css" rel="stylesheet" type="text/css"> <link rel="shortcut icon" type="image/x-icon" href="favicon.ico"> </head> <body> <?php include("conn.php"); /* connection step */ $Hdlcon = i5_connect($connect,$user, $pass, array(I5_OPTIONS_JOBNAME=>"I5JOB")); // This is the PCML taken from the following i5/OS command: // CRTRPGMOD SRCFILE(EACDEMO/QRPGLESRC) SRCMBR(TESTSTRUC) PGMINFO(*PCML) INFOSTMF('/tmp/teststruc.pcml') // we only defined some parameters as "output" to have minimal network load // we also changed the program name tag to specify the "path" value for the program // we also replace " with \" to have a correct PHP syntax. We also could load it from the IFS. $description = "<pcml version=\"4.0\"> <!-- RPG module: TESTSTRUC --> <!-- created: 2006-10-12-11.46.56 --> <!-- source: EACDEMO/QRPGLESRC(TESTSTRUC) --> <!-- 5 --> <struct name=\"S2\"> <data name=\"ZOND2\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK2\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK3\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"ALPH2\" type=\"char\" length=\"20\" usage=\"inherit\" /> </struct> <!-- 1 --> <struct name=\"S1\"> <data name=\"ZOND\" type=\"zoned\" length=\"10\" precision=\"5\" usage=\"inherit\" /> <data name=\"PACK1\" type=\"packed\" length=\"19\" precision=\"5\" usage=\"inherit\" /> <data name=\"ALPH1\" type=\"char\" length=\"10\" usage=\"inherit\" /> </struct> <program name=\"TESTSTRUC\" path=\"/QSYS.LIB/EACDEMO.LIB/TESTSTRUC.PGM\"> <data name=\"CODE\" type=\"char\" length=\"10\" usage=\"output\" /> <data name=\"S1\" type=\"struct\" struct=\"S1\" usage=\"inputoutput\" /> <data name=\"S2\" type=\"struct\" struct=\"S2\" usage=\"inputoutput\" /> <data name=\"PACK\" type=\"packed\" length=\"1\" precision=\"1\" usage=\"output\" /> <data name=\"CH10\" type=\"char\" length=\"19\" usage=\"output\" /> <data name=\"CH11\" type=\"char\" length=\"20\" usage=\"output\" /> <data name=\"CH12\" type=\"char\" length=\"29\" usage=\"output\" /> <data name=\"CH13\" type=\"char\" length=\"33\" usage=\"output\" /> </program> </pcml> "; // define some input values $pack3value=7789777.44;
Zend Server 5 for IBM i Reference Manual
336
$alph2value=4; // now, prepare the program (only pcml parsing at this stage) ($hdlPgm = i5_program_prepare_PCML($description)) or trigger_error("Error while parsing PCML: " . i5_errormsg(), E_USER_ERROR); // let's define some input values $in_parameters = Array( "S1"=>Array("ZOND"=>54.77, "PACK1"=>16.2, "ALPH1"=>"MyValue"), "S2"=>Array("ZOND2"=>44.66, "PACK2"=>24444.99945, "PACK3"=>$pack3value, "ALPH2"=>$alph2value) ); // now we need to define where to place output values; it will create new local variables $out_parameters = array( "S1"=>"S1_Value", "S2"=>"S2_Value", "CH10"=>"CH10_Value", "CH11"=>"CH11_Value", "CH12"=>"CH12_Value", "CH13"=>"CH13_Value", "CODE"=>"Code_Value", "PACK"=>"Pack" ); // the call is made here i5_program_call($hdlPgm, $in_parameters, $out_parameters) or trigger_error("Error while executing program: " . i5_errormsg(), E_USER_ERROR); // all variables are now filled with program results. echo "<br>S1:"; var_dump($S1_Value); echo "<br>S2:"; var_dump($S2_Value); echo "<br>CH10:"; var_dump($CH10_Value); echo "<br>CH11:"; var_dump($CH11_Value); echo "<br>CH12:"; var_dump($CH12_Value); echo "<br>CH13:"; var_dump($CH13_Value); echo "<br>Code:"; var_dump($Code_Value); echo "<br>Pack:"; var_dump($Pack); ?> </body> </html>
API Reference
337
PCML Program Call 2 - PCML File External to PHP Program <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html> <head> <title>Program call example using PCML</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <link href="style.css" rel="stylesheet" type="text/css"> <link rel="shortcut icon" type="image/x-icon" href="favicon.ico"> </head> <body> <?php include("conn.php"); /* connection step */ $Hdlcon = i5_connect($connect,$user, $pass, array(I5_OPTIONS_JOBNAME=>"I5JOB")); // This is the PCML taken from the following i5/OS command: // CRTRPGMOD SRCFILE(EACDEMO/QRPGLESRC) SRCMBR(TESTSTRUC) PGMINFO(*PCML) INFOSTMF('/tmp/teststruc.pcml') // we only defined some parameters as "output" to have minimal network load // we also changed the program name tag to specify the "path" value for the program // we also replace " with \" to have a correct PHP syntax. We also could load it from the IFS. // the PCML file is located in the same location as the PHP program ($description = file_get_contents("/www/zendcore/htdocs/teststruc.pcml")) or trigger_error("Error while opening PCML file", E_USER_ERROR); // define some input values $pack3value=7789777.44; $alph2value=4; // now, prepare the program (only pcml parsing at this stage) ($hdlPgm = i5_program_prepare_PCML($description)) or trigger_error("Error while parsing PCML: " . i5_errormsg(), E_USER_ERROR); // let's define some input values $in_parameters = Array( "S1"=>Array("ZOND"=>54.77, "PACK1"=>16.2, "ALPH1"=>"MyValue"), "S2"=>Array("ZOND2"=>44.66, "PACK2"=>24444.99945, "PACK3"=>$pack3value, "ALPH2"=>$alph2value) ); // now we need to define where to place output values; it will create new local variables $out_parameters = array( "S1"=>"S1_Value", "S2"=>"S2_Value", "CH10"=>"CH10_Value", "CH11"=>"CH11_Value", "CH12"=>"CH12_Value", "CH13"=>"CH13_Value", "CODE"=>"Code_Value", "PACK"=>"Pack" ); // the call is made here i5_program_call($hdlPgm, $in_parameters, $out_parameters) or trigger_error("Error while executing program: " . i5_errormsg(), E_USER_ERROR); // all variables are now filled with program results. echo "<br>S1:"; var_dump($S1_Value); echo "<br>S2:"; var_dump($S2_Value); echo "<br>CH10:"; var_dump($CH10_Value); echo "<br>CH11:"; var_dump($CH11_Value); echo "<br>CH12:"; var_dump($CH12_Value); echo "<br>CH13:"; var_dump($CH13_Value); echo "<br>Code:"; var_dump($Code_Value); echo "<br>Pack:"; var_dump($Pack); ?> </body> </html>
Zend Server 5 for IBM i Reference Manual
338
List of an RPG Program, "TESTSTRUC", Called by the PCML Sample Programs D S1 DS D ZOND 1 10S 5 D pack1 11 20P 5 D alph1 21 30 D S2 DS D ZOND2 1 10S 5 D pack2 11 20P 5 D pack3 21 30P 5 D alph2 31 50 D SDS D $PGM 1 10 D $LIB 81 90 D $JOB 244 253 D $USER 254 263 D $JOBNM 264 269 D INFDS DS D KEY 369 369 D PAGRRN 378 379B 0 D* D F03 C CONST(X'33') C*------------------------------------------------------------------- ****************** C *ENTRY PLIST C PARM CODE 10 C PARM S1 C PARM S2 C PARM PACK 1 1 C PARM ch10 19 C PARM ch11 20 C PARM ch12 29 C PARM ch13 33 ********************** C MOVEL 'HELLO' CODE C Z-SUB 0.5 PACK C eval ch10 = *all'A' C eval ch11 = *all'B' C eval ch12 = *all'ZX' C eval ch13 = *all'5' C eval ZOND = 0 - zond C eval pack1 = 0 - pack1 C eval alph1 ='alph1' C - service side eval ZOND2 = 0 - zond2 C eval pack2 = 0-pack2 C eval pack3 =0 - pack3 C eval alph2 ='alph2' C* C SETON LR C RETURN
API Reference
339
Web Services <?php /* This service invokes a RPG program with two parameters */ class i5_program_service { private $conn = false; function __construct() { $this->conn = i5_connect('127.0.0.1', 'user', 'password'/*, $connection_parameters*/); if (!is_resource($this->conn)) { throw new SoapFault('i5_program_service', 'Connection to i5 server failed, use i5_errormsg() to get the failure reason'); } } public function service_for_i5_program($var_0, $var_1) { $description = Array ( array ('Name' => 'code', 'IO' => I5_INOUT, 'Type' => I5_TYPE_CHAR, 'Length' => '10'), array ('Name' => 'name', 'IO' => I5_INOUT, 'Type' => I5_TYPE_CHAR, 'Length' => '10')); $prog = i5_program_prepare('eacdemo/teststp2', $description, $this->conn); if (is_resource($prog)) { /* Execute Program */ $params = array ( 'code' => $var_0, 'name' => $var_1); $retvals = array( 'code' => 'ret_val_1', 'name' => 'ret_val_2'); $ret = i5_program_call($prog, $params, $retvals) ; if ($ret === true) { $ret = array($ret_val_1, $ret_val_2); return $ret; } else { throw new SoapFault('i5_program_service', 'Failed to call the program, use i5_errormsg() to get the failure reason'); } if (!i5_program_close ($prog) ) { throw new SoapFault('i5_program_service', 'Failed to free program resource handle, use i5_errormsg() to get the failure reason'); } } else { throw new SoapFault('i5_program_service', 'Program prepare failed, use i5_errormsg() to get the failure reason'); } } function __destruct() { if (!i5_close($this->conn)) { // Failed to disconnect from i5 server, use i5_errormsg() to get the failure reason } } } ini_set('soap.wsdl_cache_enabled', '0'); $server = new SoapServer('zend.wsdl'); $server->setClass('i5_program_service'); $server->handle();
Zend Server 5 for IBM i Reference Manual
340
?>
Web Services - Client Side <?php /* This client calls the above service using ’r;zend.wsdl’ XML file generated by the WSDL Wizard in the Zend Studio. /* ini_set('soap.wsdl_cache_enabled', '0'); $my_client = new SoapClient('zend.wsdl'); try{ var_dump($my_client->service_for_i5_program('111', ' ')); } catch (SoapFault $exception) { echo $exception; } ?
API Reference
341
IBM i Toolkit Templates Zend Studio IDE for i5 comes complete with the following code templates containing i5 PHP API
Toolkit functions:
I5 Template Explanation
i5ActiveJobs Enables retrieving the system's active jobs, it:
1. Connects to i5 server
2. Opens active job list
3. Gets array for an active job entry
4. Closes handle received from i5_job_list function
5. Closes connection to i5 server
i5Connect Enables connecting to the i5 server, it:
1. Connects to i5 server
2. Closes connection to i5 server
i5DataAreaCreate Creates the data area, it:
1. Connects to i5 server
2. Creates data area of given size
3. Closes connection to i5 server
i5DataAreaDelete Enables deleting the data area, it:
1. Connects to i5 server
2. Deletes data area
3. Closes connection to i5 server
i5DataAreaRead Enables reading from a data area, it:
1. Connects to i5 server
2. Reads from data area
3. Closes connection to i5 server
i5DataAreaWrite Enables reading from a data area, it:
1. Connects to i5 server
2. Reads from the data area
3. Closes connection to i5 server
i5DtaqReceive Enables reading data from the data queue without key, it:
1. Connects to i5 server
2. Reads data from the data queue without key
3. Closes connection to i5 server
i5DtaqReceiveKey Enables reading data from the data queue with key, it:
Zend Server 5 for IBM i Reference Manual
342
I5 Template Explanation
1. Connects to i5 server
2. Reads data from the data queue with key
3. Closes connection to i5 server
i5DtaqSend Enables putting data to the data queue without key, it:
1. Connects to i5 server
2. Puts data to the data queue without key
3. Closes connection to i5 server
i5DtaqSendKey Enables putting data into the data queue without a key, it
1. Connects to i5 server
2. Puts data to the data queue without key
3. Closes connection to i5 server
i5JobLogs Enables retrieving job log entries, it:
1. Connects to i5 server
2. Opens job log
3. Gets array for a job log entry
4. Closes handle received from i5_jobLog_list function
5. Closes connection to i5 server
i5ObjectListing Enables getting an array with the message element for an object
list entry, it:
1. Connects to i5 server
2. Opens object list
3. Gets for a object list entry
4. Closes handle received from i5_objects_list function
5. Closes connection to i5 server
i5Program Enables calling a program and accept results from it, it:
1. Connects to i5 server
2. Opens a program or service procedure and prepares it to be
run
3. Calls the program and optionally accepts results
4. Free program resource handle
5. Closes connection to i5 server
i5ProgramService Creates Web Services class enabling invoking an RPG program,
it:
1. Connects to i5 server
2. Opens a program or service procedure and prepares it to be
API Reference
343
I5 Template Explanation
run
3. Calls the program and optionally accepts results
4. Free program resource handle
5. Closes connection to i5 server
i5Spool Enables getting spool file data from the queue and getting the
data from the spool file, it:
1. Connects to i5 server
2. Creates an pool file lists, of certain output queue or for all
queues
3. Gets spool file data from the queue
4. Get the data from the spool file
5. Free spool list resource
6. Closes connection to i5 server
i5UserSpaceCreate Creates a new user space object, it:
1. Connects to i5 server
2. Creates new user space object
3. Closes connection to i5 server
i5UserSpaceDelete Enables deleting a user space object, it:
1. Connects to i5 server
2. Deletes user space object
3. Closes connection to i5 server
i5UserSpaceGet Retrieves user space data, it:
1. Connects to i5 server
2. Opens a user space and prepares it to be run
3. Retrieves user space data
4. Closes connection to i5 server
i5UserSpacePut Enables to add user space data, it:
1. Connects to i5 server
2. Opens a user space and prepares it to be run
3. Adds user space data
4. Closes connection to i5 server
344
Zend Server for IBM i Installation Guide The IBM i Installation guide includes the following information:
Installing Zend Server for IBM i
• Uninstalling Zend Server for IBM i
• Choosing Which Distribution to Install for IBM i
• Silent Installation
• Interactive Installation
• MySQL Installation
• Zend Server Extensions
• Post Installation Instructions
Welcome to Zend Server for IBM i
• Registration
Zend Server for IBM i Setup Menu
• Sign-On
• Main menu
• Change Password
• Update using PTFs menu
• Run Support Tool
• Service Management
• MySQL Management menu
• 5250 Bridge Management menu
Zend Server for IBM i Installation Guide
345
Installing Zend Server for IBM i There are two installation modes, Silent, Interactive and Windows-Based.
After Installation, Zend Server for IBM i users benefit from access to Zend Server's regular
Updates and Security Fixes.
Note: If you have a previously installed version of Zend Server for IBM i, see the instructions under
'Upgrading Zend Server for IBM i', below.
Installation Directories The Zend Server is installed in the following folder on your server :
IBM i: /usr/local/zendsvr
/www/zendsvr
Zend Server 5 for IBM i Reference Manual
346
Choosing Which Distribution to Install for IBM i Zend Server for IBM i is available, in several distribution formats:
The distributions for all product versions are:
1. SAVF format - Download the package from zend.com.
2. Windows InstallShield format - Download the package from zend.com. (Available in GA)
IBM i Supported Operating Systems:
V5R4
V6R1
Choose the most suitable type of installation according to your operating system by selecting it
from the table below.
If you are unable to complete the installation, please refer to our Best Practices to see if these
were already handled. Only if there is no article on the subject please see the Zend Support
Center for further assistance.
Package Name Operating System Installation Type
IBM i V5R4 SAVF
V6R1 SAVF
V5R4 Windows
InstallShield
(Available in GA)
V6R4 Windows
InstallShield
(Available in GA)
Zend Server for IBM i Installation Guide
347
Silent Installation The following procedure describes how to install Zend Server in Silent Mode. The silent mode
performs the complete installation without an installation interface
To run a silent installation: 1. Download the installation package.
Create a SAVF in QGPL under the name ZSVRSAVF.
2. Log on to the IBM i system with a user profile of *SECOFR user class with all special
authorities.
Create a SAVF in QGPL under the name ZSVRSAVF.
This can be done by running the following command:
CRTSAVF FILE(QGPL/ZSVRSAVF) TEXT(`Zend Server product save file')
3. Transfer the package by binary FTP to the SAVF ZSVRSAVF in QGPL.
This can be done by executing the following steps:
a. Verify that FTP is running on your IBM i system by running the following
command and looking for 'FTP' or '21' in the Local Port column: NETSTAT *CNN
b. Open a command prompt and change directory to the directory that contains the
files you extracted from the ZIP file.
c. Run the FTP command, specifying the name of your i5/OS system. e.g: ftp IBM i_system_name/TCP address
d. If requested, enter a valid user profile and password.
Enter the bin command to specify a binary transfer.
e. Transfer the save file to the IBM i system by running the following command: put zsvrsavf.savf
4. When the SAVF is loaded into the IBM i QGPL library, return to your 5250 session and
run the following command: SBMJOB CMD(RSTLICPGM LICPGM(ZSVRPI) DEV(*SAVF) SAVF(QGPL/ZSVRSAVF)) Zend Server for IBM i will be automatically installed without interactive dialogs being displayed.
Note: The silent installation will not install the MySQL Database.
For information about Uninstalling, see Uninstalling Zend Server for IBM.
Zend Server 5 for IBM i Reference Manual
348
Interactive Installation
To run an interactive installation:
1. Download the installation package.
2. Log on to the IBM i system with a user profile of *SECOFR user class with all special
authorities.
3. Create a SAVF in QGPL under the name ZSVRSAVF.
This can be done by running the following command: CRTSAVF FILE(QGPL/ZSVRSAVF) TEXT(`Zend Server product save file')
4. Transfer the package by binary FTP to the SAVF ZSVRSAVF in QGPL.
This can be done by executing the following steps:
a. Verify that FTP is running on your IBM i system by running the following
command and looking for 'FTP' or '21' in the Local Port column: NETSTAT *CNN
b. Open a command prompt and change directory to the directory that contains the
files you extracted from the ZIP file.
c. Run the FTP command, specifying the name of your i5/OS system. e.g: ftp IBM i_system_name/TCP address
b. If requested, enter a valid user profile and password.
c. Enter the bin command to specify a binary transfer.
d. Transfer the save file to the IBM i system by running the following command: put zsvrsavf.savf
6. When the SAVF is loaded into the IBM i QGPL library, return to your 5250 session and
run the following command: RSTLICPGM LICPGM(21ZSVRPI) DEV(*SAVF) SAVF(QGPL/ZSVZRSAVF) The installation screens will load automatically.
Zend Server for IBM i Installation Guide
349
Restore Licensed Program (RSTLICPGM)
Type choices, press Enter.
Product . . . . . . . . . . . . > 2ZSVRPI Character value
Device . . . . . . . . . . . . . > *SAVF Name, *SAVF
+ for more values
Optional part to be restored . . *BASE *BASE, 1, 2, 3, 4, 5, 6, 7...
Type of object to be restored . *ALL *ALL, *PGM, *LNG
Language for licensed program . *PRIMARY Character value, *PRIMARY...
Output . . . . . . . . . . . . . *NONE *NONE, *PRINT
Release . . . . . . . . . . . . *FIRST Character value, *FIRST
Replace release . . . . . . . . *ONLY Character value, *ONLY, *NO
Save file . . . . . . . . . . . zsvrsavf Name
Library . . . . . . . . . . . QGPL Name, *LIBL, *CURLIB
Restore Licensed Program Screen
Press Enter to start running the installation. The installation welcome screen will
appear.
Zend Technologies Ltd. - Welcome
System: I5QA2
Please read the documentation and Trial License Agreement.
You are about to install Zend Server product.
This installation procedure will create
Zend Server 5 for IBM i Reference Manual
350
o ZENDADMIN and ZS5250DEMO User Profiles
o ZENDSVR Zend Server Library
o zendsvr directory will be placed under /usr/local
o Auto start jobs in ZENDSVR subsystem
Bottom
F3=Exit Enter=Accept
Copyright Zend Technologies LTD (2009)
The Installation welcome screen contains details of what the installation procedure
contains.
Press Enter to continue to the license agreement screen.
Zend Technologies Ltd. - License
System: I5QA2
ZEND SUBSCRIPTION AGREEMENT
Zend Server
Zend Server for IBM i Installation Guide
351
THIS SUBSCRIPTION AGREEMENT ("AGREEMENT") IS BETWEEN ZEND
TECHNOLOGIES
LTD. AND THE SUBSCRIBER TO, PURCHASER, LICENSEE OR USER OF, ZEND
PRODUCTS OR SERVICES. IMPORTANT: READ THESE TERMS CAREFULLY
BEFORE
DOWNLOADING THIS SOFTWARE. BY CLICKING THE "I ACCEPT" BUTTON, YOU
(THE
"SUBSCRIBER") ACKNOWLEDGE THAT YOU HAVE READ THIS AGREEMENT,
AND THAT
YOU AGREE TO BE BOUND BY ITS TERMS AND CONDITIONS. IF YOU ARE
ACTING ON
BEHALF OF AN ENTITY, THEN YOU REPRESENT THAT YOU HAVE AUTHORITY
TO ENTER
INTO THIS AGREEMENT ON BEHALF OF THAT ENTITY. IF YOU DO NOT AGREE
TO ALL
OF THE TERMS AND CONDITIONS OF THIS AGREEMENT, YOU MAY NOT USE
THE
SOFTWARE, AND IT IS YOUR RESPONSIBILITY TO TERMINATE THE
DOWNLOAD
PROCESS WITHOUT DOWNLOADING THE SOFTWARE.
1. Terms and Conditions.
1.1. Definitions "Confidential Information" is defined in Section 6.1.
More...
F3=Exit Enter=Accept
Zend Server 5 for IBM i Reference Manual
352
7. The program will be installed.
Zend Server for IBM i Installation Guide
353
Windows-Based Installation Zend Server for IBM i can be installed on your i5/OS server through your Windows Operating
System, using interactive dialogs.
To install Zend Server for IBM i through Windows:
1. Download the Windows installation package.
2. Unzip the download file to your temp directory.
3. Double-click the Setup.exe file to start the installation.
The Welcome Screen will appear.
4. Click Next.
5. Select whether to accept the terms of the agreement by selecting the relevant option.
If you choose not to accept the agreement, the installation process will terminate.
6. Click Next to continue.
7. Enter the following details:
IBM i Server address - Your i5/OS server TCP/IP address.
User ID - Your IBM i login User ID.
Password - Your IBM i login password.
8. Mark the checkbox if you want MySQL to be installed on your IBM i server during the
Zend Server for IBM i installation. The minimum supported IBM i version is V5R4.
9. Mark the relevant checkboxes for MySQL and/or Zend Platform 3.6.0 to be installed
together with Zend Server for IBM i.
Note: The minimum supported i5/OS version for MySQL installation is V5R4.
In addition, if your server language is not English, you must sign on using a user profile
that has CCSID set to 37 in order to install MySQL. To do this, run the command
"CHGUSRPRF USRPRF(QSECOFR) CCSID(37)" in your i5/OS server.
See the 'Testing your MySQL Connection using Zend Studio', section for more on
connecting to the MySQL database.
10. Click Next.
Details of the installation process will appear in the 'Installation log' window.
11. Once the installation process has completed, an installation details screen will appear:
Zend Server 5 for IBM i Reference Manual
354
Note: See the 'Getting Started' section for more information on logging in to your Zend Server
for IBM i Web Administration GUI, and the Zend Server for IBM i Setup Tool section for
more on using the Zend Server for IBM i Setup Tool.
11. Click Next.
12. An installation confirmation screen will appear.
13. Mark the checkbox to view the Zend Server for IBM i Release Notes.
14. Click Finish to exit.
Zend Server for IBM i Installation Guide
355
MySQL Installation
This section describe how to install MySQL if you skip the MuSQL installation option during the
interactive installation or used the silent installation
To begin MySQL Installation select Option 6 ‘MySQL Management menu ’ from the Send server
Service menu (GO ZENDSVR/ZSMENU):
MySQL installation (optional)
Press ENTER to start MySQL installation or press F3 to skip
MySQL installation
F3=Exit
MySQL Installation Option
Press Enter to start the MySQL installation or F3 to skip MySQL installation.
Note: You can install the MySQL database later using the Setup Tool. To install MySQL following installation: 1. Open the Setup Tool by running the command go zendsvr/zcmenu in your i/OS emulator
screen.
2. Select Option 6 - MySQL management menu.
3. You will be prompted to install the MySQL database. Note: MySQL must be installed by QSECOFR.
If you pressed Enter and MySQL is already installed in the directory /usr/local/MySQL, the
following prompt will appear:
MySQL installation (optional)
MySql is already installed.
F3=Exit
MySQL already installed
If this prompt has appeared, MySQL is already installed. Press F3 to finish the installation.
If MySQL has not been previously installed, it will be installed now:
Zend Server 5 for IBM i Reference Manual
356
MySQL installation (optional)
MySQL is being installed and configured.
Please wait ...
F3=Exit
MySQL installation
A dialog will appear reminding you to set a password for the MySQL root user:
PLEASE REMEMBER TO SET A PASSWORD FOR THE MySQL root USER !
To do so, start the server, then issue the following commands:
./bin/mysqladmin -u root password 'new-password'
./bin/mysqladmin -u root -h ZEND825.ZEND.NET password 'new-password'
See the manual for more instructions.
You can start the MySQL daemon with:
cd . ; ./bin/mysqld_safe &
You can test the MySQL daemon with mysql-test-run.pl
cd mysql-test ; perl mysql-test-run.pl
Please report any problems with the ./bin/mysqlbug script!
The latest information about MySQL is available on the web at
http://www.mysql.com
Support MySQL by buying support/licenses at http://shop.mysql.com
Press ENTER to end terminal session.
MySQL Instructions
In addition to the instructions in the dialog, the MySQL Daemon can later be stopped/started
through the Zend Core Setup Tool.
To start/stop your MySQL Deamon (after the MySQL installation): 1. Open the Zend Core for i5 Setup Tool by running the following command: go zendsvr/zsmenu 2. Select Option 6 - MySQL Management Menu.
3. In the following screen, select Option 4 - Start MySQL daemon or Option 5 - Stop
MySQL daemon.
Press Enter to continue.
Zend Server for IBM i Installation Guide
357
MySQL installation (optional)
MySQL is installed in directory /usr/local/MySql
and library ZMYSQL
F3=Exit
MySQL Installation Confirmation
A confirmation message will appear stating the location of your MySQL installation.
See the 'Testing your MySQL Connection using Zend Studio', section, below, for more on
connecting to the MySQL database.
Press F3 to finish and exit the installation process.
Testing your MySQL Connection using Zend Studio
If you installed MySQL, you can use Zend Studio in order to test your MySQL connection and
access your database.
Note: See http://www.zend.com/en/products/studio/for-i5os for more on Zend Studio for i/OS.
To test your MySQL connection: 1. Open Zend Studio.
2. From Studio's File Manager, click the SQL tab.
3. Right-click and select the Add SQL Server option.
The Add SQL Server dialog will appear.
4. Enter the SQL Server Settings in the fields.
The settings include:
Server Type - Select MySQL.
Server Name (Alias) - Enter a server name. This will appear on the SQL Tree
(of the File Manager).
Host Name/IP - Enter your server address.
Port - When you choose a Server Type, the default port appears in this field
automatically.
Database Name - Enter 'mysql'.
User Name - Enter the default password 'root'.
Zend Server 5 for IBM i Reference Manual
358
Password - Leave the password field blank.
5. Click Test to attempt to connect to the SQL Server using the settings and
connections currently entered in the Add SQL Server dialog box.
If the connection is successful, a 'Connection Successful' dialog will appear.
6. Click OK.
Your SQL Server will be added to the SQL tab, and you will be able to view and
access the tables contained in it.
See the Zend Studio for i/OS User Guide for more information.
Note: To uninstall MySQL: 1. Stop the ZMYSQL subsystem.
2. Delete ZMYSQL library.
3. Remove the /usr/local/mysql-5.0.45-i5os-power-64bit directory.
4. Remove the /usr/local//mysqldata directory.
5. Remove the /usr/local/mysql link.
See http://dev.mysql.com/doc/refman/5.0/en/installation-i5os.html for more information.
Zend Server for IBM i Installation Guide
359
Uninstalling Zend Server for IBM i In order to save your current Zend Server for IBM i product library and files installed on your
server, follow the installation steps detailed in the section "Upgrading Zend Server for IBM i",
above.
To uninstall Zend Server for IBM i: 1. Sign on a 5250 session to your IBM i system, using a user profile of *SECOFR user
class with all special authorities.
2. Run the following Delete Licensed Program (DLTLICPGM) command to uninstall
Zend Server for IBM i: DLTLICPGM LICPGM(2ZSVRPI)
Once the programme has been uninstalled, the following message will be displayed:
”r;*PGM objects for product 2ZSVRPI option *BASE release V5R4M0 deleted. Objects for product
2ZSVRPI option *ALL release *ONLY deleted”.
Note: The uninstaller deletes Zend Server for IBM i product library and files and creates a copy of the
Zend Server for IBM i directories in /usr/local/ZendSvr+timestamp directory.
Zend Server 5 for IBM i Reference Manual
360
Post Installation
This section includes the following Post Installation instructions:
Package Setup and Control Scripts IBM i
Ports and Services for IBM i
Installed Components for IBM i
Upgrading Zend Server for IBM i
Updating Zend Server for IBM i
Zend Server for IBM i Installation Guide
361
Package Setup and Control Scripts IBM i Package setup and control scripts, refers to the management of the different components
included in Zend Server for IBM i.
A list of the components that are installed and running on your system can be found in the
Administration Interface in Server Setup | Components.
Which components are installed depends on the chosen installation method, and product version.
Starting Zend Components on IBM i The Zend Server Service menu allows to control the Zend components that come with Zend
Server for IBM i.
To control the Apache webserver: Select Option 5 and choose Stop/Start/Restart Apache webserver
You can also use IBM's "Web Administration for i5/OS" which will be running on port
2001 (http://<YOUR_IP>:2001 for advanced configurations.
To set the Administration Interface's password, run: Select Option 1
To control (start/stop) the PHP Toolkit service, run: Select Option 5 and choose “PHP Toolkit Management Menu” which lets to Stop/Start
PHP Toolkit job
To control (start/stop) the Zend Server Monitor daemon, run: Select Option 5 and choose “Monitor Management Menu” which lets to Stop/Start/Restart
Monitor daemon
To control (start/stop) the Java Bridge daemon, run: Select Option 5 and choose “Java Management Menu” which lets to Stop/Start/Restart
Java Bridge daemon
To control (start/stop) the Job Queue daemon, run: Select Option 5 and choose “Job Queue Management Menu” which lets to
Stop/Start/Restart Job Queue daemon To obtain random number (PRNGD) used as an entropy source to feed other software, especially software based on OpenSSL
Select Option 5 and choose “PRNGD job Management Menu” which lets to Start/Stop
PRNGD job
Zend Server 5 for IBM i Reference Manual
362
Ports and Services for IBM i This section lists the services that run after installing Zend Server for IBM i and the ports these
services listen to.
IBM i
After the installation the following ports will be used by Zend Server for IBM i's components:
Apache server: listens on port 10088. Use the Zend Server for IBM i Service Menu to
stop/start/restart the Apache jobs - Option 6/ Option 5/ Option 7
Java Server: The job name is " ZSTRJAVAMW" and it listens on port 10001. To start/stop
this service from the Zend Server for IBM i Service Menu use Option 5 | Option 1243.
Changing the Apache Port If you have changed your port configuration, you need to also update your zend-server.ini file with
the change.
When Zend Server for IBM i is installed, it is assumed that the Zend Server for IBM i
Administration Interface listens to 10088. If your environment is configured differently, when you
try to access the Administration Interface, you receive a " Zend Server Exception Caught" error
message.
Note: The Web Server (Apache) listens to port 10088.
To fix this, the port settings must be changed.
To set the Administration Interface's settings to listen to a different Web server port:
After changing your Apache's port setting to another port, Change the
Administration Interface's port setting as follows:
1. Go to to /www/zendsvr/conf
2. Change conf.httpd file
3. Restart Apache.
You can also use IBM's "Web Administration for i5/OS" which will be running on port 2001
(http://<YOUR_IP>:2001.
363
Installed Components for IBM i The following text provides a description of each of the Zend Server for IBM i components that are installed in your environment Along with the
installation location of each component.
Installation Directories
Component Loaded Description Installation Path Comments
PHP + The Zend certified version of
PHP 5.2.x that includes
commonly used and Zend
extensions.
IBM i : <install_path>/lib/php/libphp5.so
Zend Optimizer+
+ Zend’s extension for using
opcode caching and
optimizations for PHP.
IBM i : <install_path>/lib/optimizerplus
Zend Guard Loader
+ The Zend Guard Loader for
running PHP, encoded with
Zend Guard.
IBM i : <install_path>/lib/loader
Zend Debugger
+ Zend’s extension for server
side debugging, profiling and
code coverage.
IBM i : <install_path>/lib/debugger
Zend Server 5 for IBM i Reference Manual
364
Component Loaded Description Installation Path Comments
Zend Cache + A Zend extension for PHP
data caching and partial PHP
output caching.
IBM i : <install_path>/lib/datacache
Java Server - The Java PHP extension,
Java daemon and setup files.
IBM i : PHP Extensions -
<install_path>/lib/jbridge/php.5.2.x/zendbridge.so
Java Daemon -
<install_path>/lib/jbridge/jawamw.jar
Java Bridge + Enables integration of Java
libraries and classes within
PHP applications.
IBM i : <install_path>/lib/jbridge Note: Requires SUN’s JRE 1.4 or
later or IBM's Java 1.4.2 or
later. 64 bit JRE is not
supported.
More information see:
SUN Microsystems’s website.
Monitor + Collects information for
monitoring and improving the
quality of your PHP
IBM i: <install_path>/lib/monitor
Zend Server for IBM i Installation Guide
365
Component Loaded Description Installation Path Comments
application.
Page Cache + A URL based HTML output
cache for PHP scripts.
IBM i: <install_path>/lib/pagecache
Zend Framework
+ Installs Zend's open-source
framework for developing
Web Applications and Web
Services in PHP.
IBM i : <install_path>/share/ZendFramework This installs libraries
containing the Zend
framework components.
phpMyAdmin - A popular open-source
management tool for handling
MySql Database over a Web
interface.
Available in GA
Only relevant for MySql
Database user.
MySQL - Installs a complete MySql
database on the Web Server.
IBM i: <install_path>/usr/local/MySQL
MySQL server's user name and password
IBM i : Default - "root" and no password
Downloaded during
installation. (Usually the
password is "root" for
administrators). For more
Zend Server 5 for IBM i Reference Manual
366
Component Loaded Description Installation Path Comments
information see: Working with
phpMyAdmin to Manage
MySQL
367
Upgrading Zend Server for IBM i
To install a newer version of Zend Server for IBM i on top of an older version, start the installation
process by running the installation file. The Zend Server for IBM i installation script will identify
whether a previously installed version is present. If so, a prompt will appear asking if you want to
override current settings or retain them.
There are several options for upgrading Zend Server for IBM i. These options change according
to the version you may have already installed on your system.
Upgrading to a Newer Version of Zend Server for IBM i The following instructions pertain to the process of installing a newer version of the same product,
for example, upgrading from version 4.02 to 4.03.
Zend Server for IBM i Installation Type
Zend Server for IBM i
Configuration Information
Comments
IBM i +
-
A separate backup of :
/usr/local zendsvr+Date
Stamp/etc/ and
/www/zendsvr+Date
Stamp are created.
The RSTLICPGM automatically
identifies if it is a new installation
or an upgrade.
Upgrading Zend Server for IBM i There are several options for upgrading Zend Server for IBM i. These options change according
to the version you may have already installed on your system.
Installing Zend Server for IBM i over an existing installation of Zend Server for IBM i
automatically upgrades the previous version installed in your server.
When the Zend Server for IBM i installation is run, the RSTLICPGM command creates a copy of
the etc directory as follows:
/usr/local/zendzvr/ is copied to /usr/local/zendzvr+timestamp directory/etc
/www/zendsvr is copied to /usr/local/+ timestamp directory
To transfer these settings to your new Zend Server for IBM i installation, copy files such as the
Apache configuration file and PHP.INI from the saved Zend Server for IBM i directories to the
new Zend Server for IBM i installation directories.
Zend Server 5 for IBM i Reference Manual
368
Zend Server for IBM i Installation Guide
369
Updating Zend Server for IBM i The product update process is using native IBM i update mechanism called Program Temporary
Fix (PTF). Zend will provide the product updates in Program Temporary Fix (PTF) format and
user will utilize the PTF commands to load and apply Zend Server updates.
Manual Rollback The recommended directories to backup before Manual Rollback are:
In IBM i: • /user/local/zendsvr/etc/
• /user/local/zendsvr/GUI/application/data/
• zendsvr/www/zendsvr/htdoc
• zendsvr/www/zendsvr/conf
Zend Server 5 for IBM i Reference Manual
370
Welcome to Zend Server for IBM i
Welcome to Zend Server for IBM i automatically opens after the Initial Password access - and
can thereafter be hidden by clicking the check-box at the bottom of the screen.
It includes 2 main areas:
7 Ways to Get Started with PHP on IBM i
Accessing PHP Open Source Applications
7 Ways to Get Started with PHP on IBM i Welcome to Zend Server for IBM i consists of the following 7 Ways to Get Started with PHP on
IBM i:
1. Zend Server for IBM i user interface - lets you manage your Zend Server and PHP
configuration
2. PHP Toolkit API - enables you to call RPG/COBOL applications, system objects and
data queses
3. Zend Navigator Demo - shows PHP Toolkit access to active jobs, spooled files, user
profiles, system values and more
4. Zend Studio for Eclipse - helps you build your first PHP application
5. 5250 Bridge - Web-enables 5250 applications
6. Zend framework - gives you a head start with secure, reliable, and modern Web 2.0
applications and Web services
7. Foundations for IBM i Programmers and Quick Start: PHP for RPG Programmers
online training courses get started with the basics of PHP
Zend Server for IBM i Installation Guide
371
Accessing PHP Open Source Applications A list of PHP applications which have been successfully run on IBM i.
Zend Server 5 for IBM i Reference Manual
372
Registration
The first time Zend Server runs, the Password and License page is displayed.
This page is also displayed when your license expires or when you reset your password. After
you define your password the first time, you can always change your password from the
Administration Interface. For more information, see Password Management.
From the Password and License page, you can set your Administration Interface password and
enter your license details.
Setting a Password Your password is used to log in to the Administration Interface, either from the main login page
accessed from your browser or from the Zend Controller.
If you are using the Zend Controller locally or remotely (i.e., Zend Server for IBM i and Zend
Controller are located on separate machines), make sure that the Zend Controller settings match
your Zend Server settings. Click here for instructions on how to change your Zend Controller
settings according to your operating system.
Passwords must be between 4 - 20 characters long.
Zend Server for IBM i Installation Guide
373
Licenses You are not required to enter a license to use Zend Server for IBM i . However, you must have a
valid license to use the complete edition of Zend Server for IBM i .
How do I just take a look at the product? If you enter Zend Server for IBM i without a license, you can run Zend Server for IBM i in the
Community Edition Mode. In this mode, Zend Server 's Community Edition features ( PHP 5.x,
Zend Data Cache, Zend Debugger, Zend Guard Loader, Zend Java Bridge and Zend Optimizer+)
are available and the features that require a license are visible and disabled.
To enter the Community Edition mode, do not enter an Order Number and License Key.
Click to start using Zend Server for IBM i in Community Edition
mode.
As soon as you enter a valid license, all licensed features are automatically activated for the
license period.
How do I get a License? If you do not already have a license, go to the licensing page on zend.com to find out how to get
a license.
I already have a License - what do I do? If you have already purchased a license, you should have received a confirmation e-mail that
includes your Order Number and License Key.
If you have just installed Zend Server for IBM i : To enter a license, enter your Order Number and License Key as stated in your
confirmation e-mail and click .
If you have already been running Zend Server for IBM i in Community Edition Mode or with an evaluation license:
In the Administration Interface go to Administration | Password and License.
Enter your new license details into the "Update License" area.
Click to apply the changes.
Zend Server for IBM i will start to run in a fully functional mode.
Zend Server 5 for IBM i Reference Manual
374
License Expiration Before a license expires, a notification is displayed at the bottom of the Administration Interface,
telling you how long you have left until your license expires and where to go to renew your
license.
Once a license expires, Zend Server for IBM i reverts to Community Edition mode until a new
license is entered. During this time, all licensed features are unavailable. However, their settings
are kept and are restored, along with the functionality, when a new license is entered.
Zend Server for IBM i Installation Guide
375
Zend Server for IBM i Setup Menu The Zend Server for IBM i Setup Menu allows you to configure all aspects of Zend Server for IBM
i, and lets you download and install Updates and additional components. This section incudes the
following information:
Sign-On
Main menu
Zend Server 5 for IBM i Reference Manual
376
Sign-On
The Sign-On can be opened by logging into the Zend Server for IBM i screen and running the
following command: go zendsvr/zsmenu
Sign -On to the IBM i System using the Sign-On screen.
To sign-on to IBM i: 1. Type in your User name.
2. Press Tab, and then type in your Password.
3. Press Enter.
Sign On
System . . . . . : I5ITS5V4
Subsystem . . . . : QINTER
Display . . . . . : QPADEV0008
User . . . . . . . . . . . . . .
Password . . . . . . . . . . . .
Program/procedure . . . . . . . .
Menu . . . . . . . . . . . . . .
Current library . . . . . . . .
3. Press Enter to continue.
The Main Menu is opened.
Zend Server for IBM i Installation Guide
377
Main Menu The Zend Server for IBM i Setup Menu includes the following options:
Change password for Web Administration Console
Update using Zend Server PTFs menu
Run Support Tool
Service Management menu
MySQL Management menu
5250 Bridge Management Menu
Reset Zend Server Environment - This option clears shared memory used by Zend
Server. All server jobs are stopped and started.
ZSMENU Zend Server for IBM i Setup Menu
System: I5ITS5V4
Select one of the following:
1. Change password for Web Administration Console
2. Update using Zend Server PTFs menu
3. Run Support Tool
5. Service Management menu
6. MySQL Management menu
7. 5250 Bridge Management Menu
9. Reset Zend Server Environment
90. Signoff
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Copyright Zend Technologies LTD (2009)
Zend Server 5 for IBM i Reference Manual
378
(C) COPYRIGHT IBM CORP. 1980, 2005.
Zend Server for IBM i Installation Guide
379
Changing the Administration Console Password Allows you to change your password for accessing the Zend Server for IBM i Administration Web
GUI.
Access this menu by selecting Option 1 from the Main menu:
To change your password: Enter a new password and press Enter.
You must restart your web server after changing your password.
Zend Server Web Administration Console
Please enter password:
F3=Exit Enter=Continue
Zend Server 5 for IBM i Reference Manual
380
Update using PTFs menu
This option lets you to display Program Temporary Fix (PTF) for Zend Server.
Access this menu by selecting Option 2 from the Main menu:
Work with PTF
System: I5BUILD
Product ID . . . . . . . . . . . . . : 2ZSVRPI
Release of base option . . . . . . . : V5R3M0
Type options, press Enter. To work with assigned PTF IDs, press F18.
1=Create 4=Delete 5=Display details 9=Work with problems
11=Load/Apply ...
Cover
Opt PTF Status Letter
(No PTFs available)
Bottom
Parameters or command
===>
F3=Exit F11=Display option F12=Cancel F17=Position to
F18=Work with assigned PTF IDs F23=More options F24=More keys
Zend Server for IBM i Installation Guide
381
Runing the Support Tool
The Zend Support Tool is a tool for gathering information about your system configuration and
setup. This tool allows the Zend Support Team to solve problems in a more comprehensive and
efficient way.
Access this menu by selecting Option 3 from the Main menu:
To send a support file for analysis by the Support Team: Create a file and specify the destination directory where the file will be created.
After the file is created it can be sent to Zend Support if the need for support arises.
See Support Tool Information for a complete list of the information collected by the
Support Tool.
Note: By downloading Run Support Tool, you have received a one year, first-level Silver Support
Subscription. For more on Zend Support Subscriptions, and to register for other programs, see
the Run Support Tool Support page at http://www.zend.com/en/products/zendserver
Zend Server 5 for IBM i Reference Manual
382
Zend Server for IBM i Service Management
This menu allows you to control your Zend Server for IBM i subsystem, Apache web server, PHP
toolkit service I5_COMD, Monitor, Java Bridge daemon and PRNGD job.
Access this menu by selecting Option 5 from the Main menu:
ZSVMENU Zend Server for IBM i Service Menu
System: I5ITS5V4
Select one of the following:
1. Start Zend Server Subsystem
2. Stop Zend Server Subsystem
3.Work with Zend Server subsystems
5. Start Apache server instances
6. Stop Apache server instances
7. ReStart Apache server instances
8.Work with Apache logs directory
10. PHP Toolkit Management Menu
11. Monitor Management Menu
12. Java Bridge Management Menu
13. Job Queue Management Menu
11. PRNGD (ZS_STR_PRN) job Management Menu
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Start Zend Server Subsystem Starts the Zend Server process.
Zend Server for IBM i Installation Guide
383
Stop Zend Server Subsystem Stops the Zend Server process.
Start Apache server instances Starts Apache.
Stop Apache server instances Stops Apache.
ReStart Apache server instances Restarts Apache
Start PHP Toolkit service (i5_COMD) Starts PHP Toolkit service. Allows you to configure your PHP Toolkit Daemon.
Start i5_COMD Daemon (ZCCSTREACD)
Type choices, press Enter.
Library . . . . . . . . . . . . > ZENDSVR Product library ZENDSVR
i5_COMD Service Port number . . 6079 Character value, *DFT, *JOBD
Enable Prestart Jobs . . . . . . *OFF *ON, *OFF, *AUTO
Restart i5_COMD if running . . . *NO *YES, *NO, *YES, *NO
Bottom
F3=Exit F4=Prompt F5=Refresh F12=Cancel F13=How to use this display
F24=More keys
Note: If you change the i5_COMD Service Port number, the daemon will open on a different TCP/IP
port number. The new port number (i5comm.port entry) is updated in the
/usr/local/send/svr/etc/php.ini file.
Zend Server 5 for IBM i Reference Manual
384
Stop PHP Toolkit service (i5_COMD) Stops the PHP Toolkit Daemon.
Monitor Management Menu Manages the Monitor daemon.
The Monitor Management Menu includes the following options: 1. Start Monitor - Starts the Monitor daemon.
2. Stop Monitor - Stops the Monitor daemon.
3. Restart Monitor - Restarts the Monitor
ZSMMENU Zend Server for IBM i PRNGD Job Management Menu
System: I5ITS5V4
Select one of the following:
1. Start Monitor
2. Stop Monitor
3. Restart Monitor
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Zend Server for IBM i Installation Guide
385
Java Bridge Management Menu Manages the Java Bridge daemon
The Java Bridge Management Menu includes the following options:
1. Start Java Bridge - Starts the Java Bridge
2. Stop Java Bridge - Stops the Java Bridge
3. Restart Java Bridge- Restarts the Java Bridge
ZSJMENU Zend Server for IBM i Java Bridge Management Menu
System: BUILD54
Select one of the following:
1. Start Java Bridge
2. Stop Java Bridge
3. Restart Java Bridge
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Zend Server 5 for IBM i Reference Manual
386
PRNGD (ZC_STR_PRN) job Management Menu The PRNGD (ZC_STR_PRN) job Management Menu includes the following options: 1. Start PRNGD (ZS_STR_PRN) job
2. Stop PRNGD (ZS_STR_PRN) job
4. Add restart PRNGD (ZS_STR_PRN) job to scheduler
5. Work with PRNGD (ZS_STR_PRN) scheduled jobs
ZSPMENU Zend Server for IBM i PRNGD Job Management Menu
System: I5ITS5V4
Select one of the following:
1. Start PRNGD (ZS_STR_PRN) job
2. Stop PRNGD (ZS_STR_PRN) job
4. Add restart PRNGD (ZS_STR_PRN) job to scheduler
5. Work with PRNGD (ZS_STR_PRN) scheduled jobs
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Start PRNGD (ZS_STR_PRN) job Starts the job.
Stop PRNGD (ZS_STR_PRN) job Stops the job.
Zend Server for IBM i Installation Guide
387
Add restart PRNGD (ZS_STR_PRN) job to scheduler
14:36:02 PRNGD Job restart set up
Please enter the time to restart ZC_STR_PRN job 1:00 hh:mm
F3=Exit Enter=Continue
Work with PRNGD (ZS_STR_PRN) scheduled jobs
Work with Job Schedule Entries I5ITS5V4
04/28/09 09:45:08
Type options, press Enter.
2=Change 3=Hold 4=Remove 5=Display details 6=Release
8=Work with last submission 10=Submit immediately
Next
-----Schedule------ Recovery Submit
Opt Job Status Date Time Frequency Action Date
ZS_STR_PRN SCD *ALL 01:00:00 *WEEKLY *SBMRLS 04/29/09
ZS_STR_PRN SCD *ALL 01:00:00 *WEEKLY *SBMRLS 04/29/09
ZS_STR_PRN SCD *ALL 01:00:00 *WEEKLY *SBMRLS 04/29/09
ZS_STR_PRN SCD *ALL 01:00:00 *WEEKLY *SBMRLS 04/29/09
Bottom
Parameters or command
===>
Zend Server 5 for IBM i Reference Manual
388
F3=Exit F4=Prompt F5=Refresh F6=Add F9=Retrieve
F11=Display job queue data F12=Cancel F17=Top F18=Bottom
Java Bridge Management Menu PHP integration with Java.
ZSJMENU Zend Server for IBM i Java Bridge Management Menu
System: I5ITS5V4
Select one of the following:
1. Start Java Bridge
2. Stop Java Bridge
3. Restart Java Bridge
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Note: To apply changes, stop and start the Zend Server for IBM i subsystem by selecting Options 2
(start) and 1 (stop) on the System Management Menu.
Zend Server for IBM i Installation Guide
389
MySQL Management menu
Access this menu by selecting Option 6 from the Main menu:
The MySQL Management menu includes the following options: 1. Start MySQL subsystem
2. Stop MySQL subsystem
3. Start MySQL daemon
4. Stop MySQL daemon
ZCMYSQL Zend MySQL management.
System: I5ITS5V4
Select one of the following:
1. Start MySQL subsystem
2. Stop MySQL subsystem
4. Start MySQL daemon
5. Stop MySQL daemon
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Copyright Zend Technologies LTD (2007)
Start MySQL subsystem Starts the MySQL process.
Stop MySQL subsystem Stops the MySQL process.
Start MySQL daemon Starts the MySQL service. The MySQL Daemon allows access to the MySQL database.
Zend Server 5 for IBM i Reference Manual
390
Stop MySQL daemon Stops the MySQL service.
Note: If MySQL is not installed, selecting the MySQL Management menu option will prompt you to
install MySQL. See the MySQL Installation section under the 'interactive installation' topic in the
Zend Server for IBM i Installation Guide for more on installing MySQL.
Zend Server for IBM i Installation Guide
391
5250 Bridge Management Menu The 5250 bridge Management menu displays System Information.
Access this menu by selecting Option 7 from the Main menu:
The 5250 Bridge Management menu includes the following options: 1. Restart 5250 Bridge server
2. Reset 5250 Bridge environment
ZSM5250 Zend 5250 Bridge Management Menu
System: I5ITS5V4
Select one of the following:
1. Restart 5250 Bridge server
2. Reset 5250 Bridge environment
90. Signoff
Selection or command
===>
F3=Exit F4=Prompt F9=Retrieve F12=Cancel F23=WRKUSRJOB
Copyright Zend Technologies LTD (2009)
Restart 5250 Bridge Server The 5250 Bridge server is restarted
Reset 5250 Bridge Environment The 5250 Bridge environment is reset
392
Zend Server Best Practices Introduction Welcome to the Zend Server for IBM i Best Practices Guide.
The following content is a collection of knowledge and information based on the experience of
Zend's Development and Product Management team and the PHP community.
In this document, you will find reference information on the following development issues.
The Performance section describes how to increase performance using Zend Server for
IBM i .
The Security section lists several additional security precautions you can take to secure
your Zend Server for IBM i installation and Web application.
The Development section includes instructions and tips for developers.
The Troubleshoot section includes solutions to known issues, possible problems and an
error message reference.
If you have a tip or best practice that you would like to see here, please feel free to send it to
Zend Server Best Practices
393
Performance
What's in the Performance Section In the Performance section, you will find information on how to configure and optimize Zend
Server for IBM i and components to increase performance.
This document includes information on the following performance issues:
Optimizing Zend Server for IBM i Performance - This section provides a description of
each performance component and includes recommendations on when the component
should be installed and for which conditions it should be disabled or removed.
Fine Tuning Optimizer+ - This section provides advanced settings to further enhance the
performance gains achieved when Optimizer+ run out-of-the-box.
Configuring PHP for Performance - This section explores the optimal php.ini
configurations and settings to get the best PHP performance optimization.
IIS Configuration Optimization - Tuning adjustment to optimize the FastCGI configuration
for IIS6 and IIS7.
Zend Server 5 for IBM i Reference Manual
394
Optimizing Zend Server Performance The Zend Server for IBM i components are designed to encompass several different
requirements. However, there is no point in adding or using certain components when they are
not needed. This primarily happens when you install a component that you do not use. For
example, if you do not need to call Java objects from your PHP code, there is no need to have
the Java Bridge running. In addition, it would be better not to install this optional component at all,
especially as you will be prompted to install a Java Runtime Environment that is not required if
you are only running PHP.
In this section, we describe each performance component, including when you should install the
component, when to disable the component and when applicable, when to remove the
component.
Component Description Turn Off Comment
Debugger A remote
debugging tool
for developers
working with
Zend Studio.
Not recommended to turn off as it
is great for development
environments.
In production when not debugging
code
If you are not
going to debug
your code with
the Debugger,
for example in a
production
environment,
disabling this
component may
provide a slight
performance
gain
Optimizer+ Speeds up PHP
execution
through opcode
caching and
optimization.
Disabling has a negative impact on
performance.
Guard Loader Loads and runs
encoded PHP
scripts
(Encoded with
Zend Guard)
Required only if you are running
PHP code that was encoded with
Zend Guard.
If you are not a
Zend Guard
user either
remove this
component or
do not install it
Zend Server Best Practices
395
(it is an optional
component).
Data Cache Cache data
items or output
If you are not using the Data Cache
API in your code for partial content
caching.
Java Bridge Calls Java
classes and
code from PHP
Required only If you call Java code
or objects from your PHP.
If you are not a
Java user either
remove this
component or
do not install it
(it is an optional
component).
Monitor Identifies
performance
issues
Turn off temporarily, only for
performance testing reasons. Not
recommended to remove this
component however it is best to
configure accordingly see "
Working with Monitoring"
Page Cache A URL based
HTML output
cache for PHP
scripts
Always
If you are not using URL based
Caching.
If you decide
not to use this
component.
Zend Server 5 for IBM i Reference Manual
396
Fine Tuning Optimizer+ The performance improvement gained by letting the Optimizer+ run out-of-the-box can be further
enhanced with fine tuning. These are advanced settings that need to be evaluated based on your
environments usage specifications and performance requirements.
Note: These are only recommendations, in most cases such fine tuning should not be necessary.
Disabling Code Change Auto-Detection In the Administration Interface, to view the specific directives for Optimizer+, go to Server Setup | Components and click on the Directives link next to the Optimizer+.
Look for "zend_optimizerplus.validate_timestamps" and set the value to Off.
This speeds up the server, but also requires that you restart the server (
) if you deploy new versions of existing files.
When to change: If your PHP code is rarely updated/changed or if you are capable of manually
restarting your PHP on every code update.
When not to change: If you are in development and you are frequently changing code, or if you
do not have control over the code update process.
Decreasing Code Validation Frequency In the Administration Interface, to view the specific directives for Optimizer+, go to Server Setup | Components and click the Directives link next to the Optimizer+.
Look for "zend_optimizerplus.revalidate_freq" and set the value to 30 (seconds).Zend Server
for IBM i is now set to check PHP file changes every 30 seconds.
When to change: If you do not change PHP files often and some delay between file update and
site update is acceptable, you may set it even higher.
When not to change: If you have frequently changing files and you need the changes to take
effect immediately.
Zend Server Best Practices
397
Configuring PHP for Performance You may be able to add an additional performance boost to your PHP applications by properly
configuring your PHP runtime environment settings. You can edit the directives below from the
Administration Interface via Server Setup | Directives.
Warning: Changing some of these settings may cause certain PHP applications to stop functioning.
Therefore, use discretion when you disable them and test your environment: It is important that
you fully understand the purpose of each directive before you modify it.
Optimal php.ini configurations and settings for maximum performance optimization:
Name Recommended Value
Zend Server for IBM i Default
Description
realpath_cache_size 256K 256K Determines the size of the
realpath cache to be used by
PHP. This value should be
increased on systems where
PHP opens many files, to
reflect the quantity of the file
operations performed.
realpath_cache_ttl 120 120 Duration (in seconds) for
which to cache realpath
information for a given file or
directory. For systems with
rarely changing files,
consider increasing the
value.
error_reporting E_ALL &
~E_NOTICE
E_ALL The error_reporting()
function sets the
error_reporting directive at
runtime. PHP has many
levels of errors: Using this
function sets the error level
for the duration (runtime) of
your script.
register_long_arrays Off Off Tells PHP whether or not to
register the deprecated long
Zend Server 5 for IBM i Reference Manual
398
$HTTP_*_VARS type
predefined variables. When
On (default), long predefined
PHP variables (like
$HTTP_GET_VARS) are
defined. If you're not using
them, it's recommended to
turn them off for performance
reasons. Instead, use the
superglobal arrays (like
$_GET). This directive
became available in PHP
5.0.0 and was dropped in
PHP 6.0.0.
register_argc_argv Off Off Tells PHP whether to declare
the argv and argc variables
(that contain the GET
information).
magic_quotes_gpc The default is: Off
This feature is deprecated as of PHP
6.0.0.
Sets the magic_quotes state
for GPC (Get/Post/Cookie)
operations. When
magic_quotes are On, all '
(single-quote), " (double
quote), \ (backslash) and
NULLs are escaped with a
backslash automatically.
include_path As short as
possible,
depending on
the application's
needs
".;/path/to/php/pear" Specifies a list of directories
where the require(),
include(), fopen(), file(),
readfile() and
file_get_contents() functions
look for files. The format is
like the system's PATH
environment variable: A list
of directories separated with
a colon in Unix .
max_execution_time 30 30 This sets the maximum time
Zend Server Best Practices
399
(in seconds) that a script is
allowed to run before it is
terminated by PHP. This
helps prevent poorly written
scripts from tying up the
server. The default setting is
30 s. When running PHP
from the command line, the
default setting is 0 s.
The maximum execution
time is not affected by
system calls, stream
operations, etc. See the
set_time_limit() function for
more details.
You cannot change this
setting with ini_set() when
running in safe mode. The
only workaround is to turn off
safe mode or to change the
time limit in the php.ini.
Your Web server may have
other timeout configurations
that can also interrupt PHP
execution. Apache has a
Timeout directive and IIS has
a CGI timeout function. Both
default to 300 seconds. See
your Web server
documentation for specific
details.
memory_limit 128M 128M Sets the maximum amount
of memory (in bytes) that a
script can allocate. This
helps prevent poorly written
scripts from consuming all
the available memory on a
Zend Server 5 for IBM i Reference Manual
400
server. This setting can also
be fine tuned during
development to reach an
optimal setting.
When an integer is used, the
value is measured in bytes.
Note: To have no memory
limit, set this directive to -1.
output_buffering 4096 4096 Allows you to buffer the PHP
output instead of having it
sent directly as soon as it is
generated.
Zend Server Best Practices
401
IIS Configuration Optimization
Tuning FastCGI Configuration for IIS6
Note: These performance enhancements are defined by default when you install Zend Server for IBM i .
By default, Zend Server for IBM i runs with a maximum of ten concurrent PHP instances. For high
load Web servers, it is recommended to increase this value, based on your performance
requirements and other hardware/software limitations (such as memory, CPU, etc.).
To control the maximum amount of concurrent PHP instances:
1. Go to C:\WINDOWS\system32\inetsrv\fcgiext.ini.
2. Locate the entry for "php" under Types.
3. Locate the section corresponding to this entry (usually under "[PHP]").
4. Append the following line at the end of this section:
MaxInstances=10
This will enable Zend Server for IBM i to run ten PHP instances, for high loads. If you have lots of
memory and high loads, you can increase this value even more.
To control the amount of requests handled by a single PHP instance before recycling:
1. Go to C:\WINDOWS\system32\inetsrv\fcgiext.ini.
2. Locate the entry for "php" under Types.
3. Locate the section corresponding to this entry (usually under "[PHP]").
4. Append the following line at the end of this section:
InstanceMaxRequests=10000
This will allow a single PHP instance to handle 10,000 requests, instead of the default 1,000.
If you set this number higher, make sure you increase the value of
PHP_FCGI_MAX_REQUESTS located in the same file accordingly.
Zend Server 5 for IBM i Reference Manual
402
Tuning FastCGI Configuration for IIS7
Note: These performance enhancements are defined by default when installing Zend Server for IBM i .
By default, Zend Server for IBM i runs with a maximum of ten concurrent PHP instances. For high
load Web servers, it is recommended to increase this value, based on your performance
requirements and other hardware/software limitations (such as memory, CPU, etc.).
Requirements: IIS7 Resource Kit -
(x86) http://www.iis.net/downloads/default.aspx?tabid=34&i=1682&g=6
(x64) http://www.iis.net/downloads/default.aspx?tabid=34&i=1683&g=6
Once installed, you can administer your FastCGi settings from the Internet Information Services
(IIS) Manager.
From here, you can configure your MaxInstances and InstanceMaxRequests.
Zend Server Best Practices
403
Security
What's in the Security Section In the Security section, you will find information on how to configure and optimize the Zend Server
for IBM i and components to function more securely.
This document includes information on the following security issues:
Allowed Hosts - This section describes the Allowed Hosts lists and offers
recommendations on which hosts to add to the Allowed Hosts list for development and
production environments.
Securing the Administration Interface - This section provides information on how to set an
IP address-based access control list on the Web server running the Administration
Interface .
Configuring PHP for Security - This section explores how you can add an additional
security boost to your PHP applications by properly configuring your PHP runtime
environment settings.
Zend Server 5 for IBM i Reference Manual
404
Configuring Debugger Access Control The allowed hosts list is a list of IP addresses that are permitted to initiate a Debugger session on
the Web server on which Zend Server for IBM i is installed.
The default value for zend_debugger.allow_hosts intentionally covers a wide range of IP
addresses. This is to make the initial installation of Zend Server for IBM i compatible for a large
selection of environments.
However, this also can be a security risk, as you are permitting a wide range of IP addresses
to access your Web server. Therefore, we recommend that you limit accessibility and create a
secure environment by only using specific hosts (full IP address) recognized by you that you are
sure you want to permit to connect.
To change this value in the Administration Interface, go to Server Setup | Debugger, remove all
the IP range settings and set the specific IP's that you permit to connect to Zend Server for IBM i .
Depending on if you are working on a development or production environment, you may want to
consider different defaults.
In development environments, all the machines that require access to debug should be allowed.
In production environments, it is safer to limit access or even allocate a single machine to allow
access. Not only will this make your environment more secure, it may also help limit and prevent
unnecessary traffic on your production server
Zend Server Best Practices
405
Securing the Administration Interface Purpose: To provide an additional security layer to the existing password protection – especially
crucial to production environments.
Note: This solution does not replace the appropriate firewall precautions you should take to deny
access to the Administration Interface from certain IP addresses.
By default, access to the Administration Interface is password protected. If you want to secure
access to the Administration Interface, you can do so by setting an IP address-based access
control list on the Web server running the Administration Interface.
After following this procedure, users that try to access the Administration Interface from not-
allowed (unauthorized) IP addresses are not able to access the Administration Interface.
IBM i: To limit IP access:
Refer to the Apache documentation http://httpd.apache.org/docs/2.2/howto/access.html
Zend Server 5 for IBM i Reference Manual
406
Configuring PHP for Security You may be able to add an additional security boost to your PHP applications by properly
configuring your PHP runtime environment settings. You can edit the directives below from the
Administration Interface by going to Server Setup | Directives.
Warning: Changing some of these settings may cause certain PHP Applications to stop functioning.
Therefore, use discretion while disabling them and test you environment - it is important that you
fully understand the purpose of each directive before modifying it.
Optimal php.ini configurations and settings for maximum security protection from external threats:
Name Default Optimal Value
Description
disable_functions This directive allows you to disable certain
functions for security reasons. It takes on a
comma-delimited list of function names.
disable_functions is not affected by Safe Mode.
This directive must be set in the php.ini file: For
example, you cannot set this in httpd.conf.
disable_classes This directive allows you to disable certain
classes for security reasons. It takes on a
comma-delimited list of class names. The
disable_classes directive is not affected by Safe
Mode. This directive must be set in php.ini: For
example, you cannot set this in httpd.conf.
magic_qotes_gpc 0 0 Sets the magic_quotes state for GPC
(Get/Post/Cookie) operations. When
magic_quotes are on, all ' (single-quotes), "
(double quotes), \ (backslash) and NULLs are
escaped with a backslash, automatically.
allow_url_include 0 0 This option allows the use of URL-aware fopen
wrappers with the following functions: include(),
include_once(), require(), require_once().
Note: This setting requires that allow_url_fopen
be set to On.
expose_php 1 0 Decides whether PHP may expose the fact that it
Zend Server Best Practices
407
is installed on the server (e.g., by adding its
signature to the Web server header). It is no
security threat in any way, but it makes it
possible to determine whether you use PHP on
your server or not.
display_errors 1 0 This determines whether errors should be printed
to the screen as part of the output or if they
should be hidden from the user.
Value "stderr" sends the errors to stderr instead
of stdout. The value is available as of PHP 5.2.4.
In earlier versions, this directive was of type
boolean.
Note: This is a feature to support your
development and should never be used on
production systems (e.g., systems connected to
the Internet).
Note: Although display_errors may be set at
runtime (with ini_set()), it won't have any affect if
the script has fatal errors. This is because the
desired runtime action does not get executed.
register_globals 0 0 Whether or not to register the EGPCS
(Environment, GET, POST, Cookie, Server)
variables as global variables.
Relying on this feature is highly discouraged.
Please read the security chapter in the PHP
manual on Using register_globals for related
information.
Note: register_globals is affected by the
variables_order directive.
Zend Server 5 for IBM i Reference Manual
408
Development
What's in Development In the Development section, you will find information on how to use Zend Server for IBM i and
components in development for efficient detection and diagnosis of issues.
This document includes information on the following development issues:
Working with Zend Framework - This section explores the benefits of the Zend
Framework pre-configured stack that includes all the system components for developing
Web applications with PHP and how to load Zend Framework's classes in your scripts.
Configuring Zend Framework - This section presents the advantages of port-based
virtual hosts and describes how to configure Zend Server for IBM i to run Zend
Framework projects in a development environment, using port-based virtual hosts.
Advanced Diagnostics with Zend Server for IBM i - This section presents suggestions to
help diagnose problems by event rules.
Zend Server Best Practices
409
Working with Zend Framework Zend Framework users who deploy Zend Server for IBM i will benefit from a pre-configured stack
that includes all the system components for developing Web applications with PHP.
The Zend Framework files are placed in:
<install_path>/share/ZendFramework
Loading Zend Framework Classes There are two ways to load Zend Framework's classes in your script:
1. Using the Zend Loader:
The Zend Loader utility class checks whether the class already exists within the script. If it does, it
will create the relevant file from the class name using Zend Framework's naming convention (See
http://framework.zend.com/manual/en/coding-standard.naming-conventions.html for more
information on Zend Framework's naming conventions). If the class already exists, this will speed
up performance.
Using the Zend Loader also has the added advantage of loading classes outside of Zend
Framework.
To use the Zend Loader: 1. Load the Zend Loader utility class once in your script:
Require_once 'Zend/Loader.php';
2. From now, load each class using the class name: Zend_Loader::loadClass('Zend_Class_Name');
3. For example, in order to load the Zend Http Client: Zend_Loader::loadClass('Zend_Http_Client);
Zend Server 5 for IBM i Reference Manual
410
2. Using require / include calls
Classes can also be called using the conventional require or include calls:
To use 'require class': 1. Enter a 'require' command for the relevant file into your script:
Require 'File.php';
2. For example, to require the Zend Http Client Class: require 'Zend/Http/client.php';
In order to see a full list of Zend Framework's components, including more information on the
functionality and use of the various components, see http://framework.zend.com/manual
Zend Server Best Practices
411
Configuring Zend Framework
Configuring Zend Server for IBM i to Run a Zend Framework Application The following procedure describes how to configure Zend Server for IBM i to run Zend
Framework projects in a development environment, using port-based virtual hosts. The
advantage of port-based virtual hosts is in the ease of running several isolated applications on the
same Web server. This overall solution allows developers working on a Zend Framework project
in Zend Studio to immediately test any code changes locally.
The following procedure uses instructions suitable for Zend Studio for Eclipse and the
Apache bundled with Zend Server. A similar procedure with some modifications can apply for
other IDEs and web servers.
To configure Zend Server for IBM i to run a Zend Framework application:
1. Create a new Zend Framework project.
If you have not already done so, create a new Zend Framework project using the
New Zend Framework Wizard in Zend Studio for Eclipse.
2. Define a virtual host on Zend Server for IBM i that will point to the new project's
public directory:
a. Find the full path to your project's public directory.
In Zend Studio for Eclipse, go to the project browser and right-click on
the public directory from the menu choose Properties. The full path is
listed in the Resource Tab's location field.
b. Open your Apache configuration file (in most cases it will be httpd.conf
and located in your Apache installation directory).
Where is my Apache configuration file?
c. Go to the end of the file and add the following section: Listen 10089 < VirtualHost *:10089> DocumentRoot " DOCUMENT_ROOT" <Directory "DOCUMENT_ROOT"> Order allow,deny Allow from all AllowOverride all </Directory> </VirtualHost>
3. Replace "DOCUMENT_ROOT" with the full path to the public directory, enclosed
in double quotes ("DOCUMENT_ROOT")
Replace the port number with a unique port number dedicated to this Virtual
Host. The port number (10089) has to be the same value for "Listen" and
"VirtualHost".
Zend Server 5 for IBM i Reference Manual
412
4. Zend Framework's MVC implementation makes use of the Front Controller
pattern. You must therefore rewrite all incoming requests (except those for static
resources, which your application need not handle) to a single script that will
initialize the FrontController and route the request. If you're using mod_rewrite for
the Apache web server, create the file <Project_Name>/public/.htaccess with the
following contents: # public/.htaccess RewriteEngine On RewriteCond %{REQUEST_FILENAME} -s [OR] RewriteCond %{REQUEST_FILENAME} -l [OR] RewriteCond %{REQUEST_FILENAME} -d RewriteRule ^.*$ - [NC,L] RewriteRule ^.*$ /index.php [NC,L]
Note: Some web servers may ignore .htaccess files unless otherwise configured. Make sure
that your web server is configured to read the .htaccess file in your public directory.
5. Restart your Web server from the command line .
Your Zend Framework projects will now be accessible from a browser through:
http://localhost:10089/ (the port number 10089 should be replaced with the unique port you
dedicated to this virtual host).
Where is My Apache Configuration File? Apache uses a main configuration file for all its settings, typically this file is called httpd.conf or
apache2.conf. The location of this file varies depending on your installation:
/usr/local/ /apache2/conf/httpd.conf.
IBM i: /usr/local/zendzvr/apache2/conf/httpd.conf
Zend Server Best Practices
413
Advanced Diagnostics with Zend Server
Advanced Diagnostics with Zend Server The information contained in an Issue (Monitor | Events) is geared towards analyzing and
resolving all sorts of problems that are common to running Web Applications in PHP.
Based on the type of rule on which triggered an issue you can immediately begin to start solving
the issue.
The first step is to make sure that the issue was genuinely generated. To do this consider one of the following:
1. Is this a real error or should the Monitor Rule parameters be modified (thresholds,
functions list, etc.)?
2. Can I use the monitor API to solve this problem (i.e. identify the problem as a known
issue to be ignored, so that no additional events will be added to the issue)?
3. Is the detected behavior accepted behavior for the specific situation (time, script, load
etc.) that should be ignored.
4. Use the Administration Interface to manage issues by changing the Status to Ignored. All
events that happen and are aggregated to that issue will still be monitored but the issue
will stay ignored.
Once you have established that the issue represents a real problem, you can start to handle the
issue. Use the links below to drill down by type of rule for suggestions that can help diagnose
problems.
Rule names in this page are in their basic form without the severity or reference to absolute and
relative.
Click on a Rule name (Link) to view diagnostics information by rule.
Custom Event | Slow Function Execution | Function Error | Slow Request Execution | High
Memory Usage | Inconsistent Output Size | PHP Error | Java Exception | Database Error.
Zend Server 5 for IBM i Reference Manual
414
Custom Event Description: When the API function 'zend_monitor_custom_event' is called from inside PHP
code, it generates an event. When enabled an event will be generated and displayed in the
Monitor | Events.
Information Collected:
The most important details are:
• Function Name - As displayed in the Issue’s General Details
• Function Arguments - The arguments of the function that triggered the event are listed in
the Function Data tab.
• user_data - if specified in the function call that triggered the event it will display additional
user defined data.
In most cases, these details alone should be enough to indicate what happened to trigger an
event.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action. Tools are listed in order of relevance to helping
solve the event:
1. Run the Debugger
Possible Causes and Solutions:
Custom Events are defined by users according to specific requirements. These events can only
be triggered by specific code in a specific application and therefore it is only possible to say that
the application's logic triggered the event.
There are certain circumstances where applying a Custom Event can be useful:
1. When handling logging routines and exceptions by adding a call to
'zend_monitor_custom_event' with the data that has been logged or held in the
exception.
2. In logical closure situations. For example when handling 4inputs that require monitoring
the value of the input (for different actions) to prevent inputting values that are not
acceptable for the business logic. Adding the function 'zend_monitor_custom_event' will
Zend Server Best Practices
415
give you the ability to trigger an event when an unacceptable value is passed and also
provide the necessary backtrace information to understand how the value got there.
3. More...
Zend Server 5 for IBM i Reference Manual
416
Slow Function Execution Description: When a specific function in your code runs slowly, Zend Monitor identifies it as an
event worth reporting. The “Slow Function Execution” Rule contains the following monitoring
definitions, runtime duration and a list of functions that should be monitored.
Information Collected:
The most important details are:
Function Name - As displayed in the Issue’s General Details
Function Arguments - The arguments of the function that triggered the event are listed in
the Function Data tab.
In most cases, these details alone should be enough to indicate what happened to trigger an
event.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Run the Profiler
Open code in editor
Run the Debugger
Possible Causes and Solutions:
Queries to a DB (database) - long, elaborate and complicated DB queries may take a long time
and make the function appear to take a long time to execute.
There are many ways to speed up DB queries such as:
Revise the SQL query itself - make it simpler
Improve the structure of your DB tables
Use RDBMS features that can improve speed such as indexes, prepared statements,
stored procedures etc…
All these are only suggested possible causes and each event. Developers have to
analyze each occurrence to understand the specific reasons behind the slow execution
time.
Zend Server Best Practices
417
Long running actions - Some actions triggered by a function can, by definition take a long time.
Examples of long running actions can be using a function to run code from the command line or
remote access queries with Web services or searching for files in a directory. In most cases,
these uses of a function cannot be refined and the best action is to ignore these issues when they
occur.
False Positives - Sometimes functions run slowly. Not all functions that run slowly are indicative
of a problem in your code or environment and they may be no indication of unacceptable
behavior. If this is the case, remove the function from the Rule’s “Watched Functions” list or set
issues triggered by this function to ignored.
Zend Server 5 for IBM i Reference Manual
418
Function Error Description: When a specific function in your code returns FALSE, it generates an event. The
“Function Error” Rule contains a list of monitored functions (i.e. functions that when returning
FALSE will trigger an event).
Information Collected:
The most important details are:
Function Name - As displayed in the Issue’s General Details
Function Arguments - The arguments of the function that triggered the event are listed in
the Function Data tab.
Backtrace – identify what happened before the error happened that may have caused a
problem such as incorrect data or problematic input data.
In most cases, these details alone should be enough to indicate what triggered the event.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Run the Debugger
Open code in editor
Redefine database queries
View information in the Logs
Run the Profiler
Possible Causes and Solutions:
Generally, logic errors trigger Function Error events such as queries that you expect to return
something and they do not and not PHP errors.
If you have a function that you need to return FALSE as an acceptable value, remove the function
from the monitored functions list.
Internal PHP functions – If you are using internal PHP functions, the best reference for
investigating the problem is use the PHP manual< http://php.net/> (The Zend Controller’s
Search option provides quick access to searching the PHP Manual.
Zend Server Best Practices
419
You can also check your logs to see if they show PHP error information logged the same
time the function error occurred.
User define functions – If it is a user defined function, running the debugger will help find
out if the function is running complicated actions that are causing the function to fail.
Using Breakpoints while debugging, will further pinpoint the problematic area in the code.
False Positives - Sometimes functions are supposed to return FALSE. Not all functions
that return FALSE are indicative of a problem in your code or environment and they may
be no indication of unacceptable behavior. If this is the case, remove the function from
the Rule’s “Event Condition” list or set the status of issues triggered by this function to
ignored.
Note: Removing a function from the rule, affects all instances of the function. Before removing the
function from the list, make sure the function does not require monitoring wherever it is used.
Zend Server 5 for IBM i Reference Manual
420
Slow Request Execution Description: When a specific request runs longer then a specified duration it generates an event.
The “Slow Request Execution” Rules contains the durations that trigger events either severe or
normal and either relative to a specific value (absolute) or to a percentage (relative measurement
per URL).
Information Collected:
The most important details are:
URL - As displayed in the Issue’s General Details
Request data - Listed in the Request.
In most cases, these details alone should be enough to indicate what happened to trigger an
event.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Run the Profiler
Open code in editor
Run the Debugger
View information in the Logs
Run general diagnostics on the machine's performance in terms of memory and CPU
usage.
Possible Causes and Solutions:
Slow requests in general indicate that there is a performance problem and they generally appear
when there is a heavy load, which in turn causes Web applications to perform poorly.
Check the following:
Bottlenecks caused by un-optimized queries or multiple queries, such as un-joined queries, slow
queries and multiple short queries. Use the Profiler to see how many queries are running at the
same time or set thresholds to find queries that take a long time to run.
Check to see if a different CPU intensive process was running in the background taking up the
CPU and making everything run slowly.
Look at the amount of calls to the function - are there too many? add breakpoints and run again
to manually trace per query what happened. Possible Solution: cache the information using a
Data Cache API as a PHP array or use the Page Cache to cache the presentation layer.
Zend Server Best Practices
421
Profiler results - analyze the profiler results and isolate functions/areas that consume the majority
of the time and analyze each function/area code separately to isolate the possible cause of the
problem.
Zend Server 5 for IBM i Reference Manual
422
High Memory Usage Description: When a specific PHP request consumes more than the specified amount of memory
it generates an event. The “High Memory Usage” Rules contain the memory consumption setting
(i.e. the amount of memory the request has to consume to trigger an event).
Information Collected:
The number of occurrences is the best indicator. A single occurrence can be disregarded (change
the Status of the Issue to Closed) only if it occurs multiple times it is worth investigating. Closed
events that continue to receive new activity open automatically.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Open code in editor to see if the script can be improved
View information in the Logs
Possible Causes and Solutions:
Database Functions - Some queries may return large record sets and should be refined.
Iterative functions – functions that include many ‘foreach’ loops may cause excessive
memory usage and should be reviewed to see if less memory can be consumed.
False Positives - Sometimes requests consume large amounts of memory. Not all
requests that consume lots of memory are indicative of a problem in your code or
environment and they may be no indication of unacceptable behavior. If this is the case,
set issues triggered by this function to ignored.
Zend Server Best Practices
423
Inconsistent Output Size Description: When a specific PHP request’s output size deviates from the average by the
percentage specified (measured per URL) it generates an event. The “Inconsistent Output Size”
Rule contains the output size’s deviation percentage (i.e. the amount of output the request has to
generate in order to trigger an event).
Information Collected:
The output size in the Group Details helps to analyze the nature of the event. For example if the
output size is 0 you can determine that nothing was outputted and try to understand why.
Generally, PHP errors and Function errors are generated at the same time as the Inconsistent
Output Size error, which can provide further information.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Run the Debugger
View information in the Logs
Open code in editor
Run the Profiler
Possible Causes and Solutions:
Small Output Sizes - It is important to look at the results that show a smaller output size to help
identify why this output was so large. This usually indicates that the requested output was not
fully generated. Possible Solution - Look for related PHP errors and Function Errors and then
view the PHP and Web server logs for further details.
Zend Server 5 for IBM i Reference Manual
424
PHP Error Description: When a specific PHP error is reported, it generates an event. The “PHP Error” Rule
contains a list of monitored PHP error types. This event type complements the error_reporting
settings in your php.ini by reporting specific errors even if they are set to disabled in your php.ini..
Information Collected:
The most important details are:
Function Name - As displayed in the Issue’s General Details
Error Data - Listed in the Error Data tab.
Backtrace – to investigate what function calls were executed just before the error was
reported.
In most cases, these details alone should be enough to indicate what happened to trigger
an event.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Run the Debugger
Open code in editor
Redefine database queries
View information in the Logs
Possible Causes and Solutions:
Syntax/Parse Errors - missing or incorrect syntax in code that is found during PHP compilation
Fatal Runtime Errors - such as E_WARNING and E_ERROR - indicate that there was a call to
an undefined function or that you did not load a specific extension or when classes and
Functions are defined twice. Possible Solution: Open code and view Line and function that
triggered the error.
Uncaught Exceptions - generate fatal errors, with a complete backtrace to trace the reason why
the PHP error was reported.
Runtime Warnings - The code did not run as expected. Normally a notice is displayed and the
code continues to run in an unexpected manner or the code will crash. Possible solutions: check
your code for the following wrong DB QUERIES missing FILES, STREAMS functions that are
performing DIV BY ZERO
Zend Server Best Practices
425
Zend Server 5 for IBM i Reference Manual
426
Java Exception Description: When Java code called through the Java Bridge fails due to an uncaught Java
exception, it generates an error. The “Uncaught Java exception” Rule determines if Uncaught
Java Exceptions are reported or not.
Information Collected:
The most important details are:
Function Name - As displayed in the Issue’s General Details
Error Data - Listed in the Error Data tab including the Java Stack and Java error string.
In most cases, these details alone should be enough to indicate what happened to trigger an
event.
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Open code in editor
Run the Debugger
Run the Profiler
Redefine database queries
View information in the Logs
Possible Causes and Solutions:
Based on the exception type, investigate the Java code and fix to stop generating the event – all
relevant information should be collected in the issue.
False Positives - Sometimes developers write code to intentionally trigger an Uncaught Java
Exception. Not all triggered exceptions are indicative of a problem in your code or environment
and they may be no indication of unacceptable behavior. If this is the case, set issues triggered
by this function to ignored.
Zend Server Best Practices
427
Database Error Description: When a specific watched database function returns FALSE, it generates an event.
The “Database Error” Rule contains a list of monitored functions (i.e. functions that when
returning FALSE will trigger an event).
Information Collected:
The most important details are:
Function Data - Listed in the Function Data tab.
Function Name - As displayed in the Issue’s General Details
The error type will show if it is an SQL query error , shell code error, java code error
Applicable Diagnostic Actions:
Click on a link to see how to perform each action tools are listed in order of relevance to helping
solve the event:
Open code in editor
Run the Debugger
View information in the Logs
Possible Causes and Solutions:
Possible causes:
Check that the connection to the DB is working. Possible Solution: verify the connection data is
correct (address, user name, passwords etc.)and manually re-establish the connection.
External code problems such as malformed non-PHP code (code that can trigger a PHP error).
Solution: Fix SQL code.
Function errors should to help understand the problem according to the content of the error.
Use the debugger to find the code/query that failed.
Incorrect database queries can trigger the event. Solution: redefine database queries and verify
that the correct query syntax is used.
