Reference Manual - Zend Technologies

\n\n"; print "OS=".$system->getProperty("os.name")." ". $system->getProperty("os.version")." on ". $system->getProperty("os.arch")."
\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. 91 Zend Server 5 for IBM i Reference Manual 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. 92 Zend Server for IBM i 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". 93 Zend Server 5 for IBM i Reference Manual 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. 94 Zend Server for IBM i 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. 95 Zend Server 5 for IBM i Reference Manual 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: 96 Zend Server for IBM i 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. 97 Zend Server 5 for IBM i Reference Manual 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. 98 Zend Server for IBM i 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. 99 Zend Server 5 for IBM i Reference Manual 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. 100 Zend Server for IBM i 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. 101 Zend Server 5 for IBM i Reference Manual 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. 102 Zend Server for IBM i 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). 103 Zend Server 5 for IBM i Reference Manual 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 104 Zend Server for IBM i 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 105 Zend Server 5 for IBM i Reference Manual 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: 106 Zend Server for IBM i 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. 107 Zend Server 5 for IBM i Reference Manual 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 108 Zend Server for IBM i 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 109 Zend Server 5 for IBM i Reference Manual 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. 110 Zend Server for IBM i ƒ 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. 111 Zend Server 5 for IBM i Reference Manual 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 112 Flexible architecture No configuration files necessary to get going Zend Server for IBM i 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. 113 Zend Server 5 for IBM i Reference Manual 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. 114 Zend Server for IBM i 115 Zend Server 5 for IBM i Reference Manual 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 116 Zend Server for IBM i 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 117 Zend Server 5 for IBM i Reference Manual 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. 118 Zend Server for IBM i 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 userdefined 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 indepth 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 119 Zend Server 5 for IBM i Reference Manual 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 120 Zend Server for IBM i 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 121 Zend Server 5 for IBM i Reference Manual 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. 122 Zend Server for IBM i ƒ 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. 123 Zend Server 5 for IBM i Reference Manual 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. 124 Zend Server for IBM i 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. 125 Zend Server 5 for IBM i Reference Manual 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. 126 Zend Server for IBM i 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. 127 Zend Server 5 for IBM i Reference Manual ƒ 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. 128 Zend Server for IBM i 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. 129 Zend Server 5 for IBM i Reference Manual 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. 130 Zend Server for IBM i 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, -orBrowse to: :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. 131 Zend Server 5 for IBM i Reference Manual 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 132 Zend Server for IBM i 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). 133 Zend Server 5 for IBM i Reference Manual 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. 134 ƒ Print ƒ Zoom - Adjusts the screen's zoom level. - Opens the print dialog for printing the current screen. Zend Server for IBM i 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. 135 Zend Server 5 for IBM i Reference Manual 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. 136 Zend Server for IBM i 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. 137 Zend Server 5 for IBM i Reference Manual 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. 138 Zend Server for IBM i 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. 139 Zend Server 5 for IBM i Reference Manual 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. 140 Zend Server for IBM i 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. 141 Zend Server 5 for IBM i Reference Manual Examples To see examples of how the 5250 Bridge API can be used to web-enable your 5250 application, see the Applications. 142 Zend Server for IBM i 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. 143 Zend Server 5 for IBM i Reference Manual 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. 144 Zend Server for IBM i 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. "; print_r($outputFields); echo "

"; // 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] => [color] => 3 ) [1] => Array ( [id] => 1 [row] => 2 [column] => 48 [length] => 19 [value] => System [color] => 1 ) [2] => Array (

Sign On

. . . . . :

145

 Zend Server 5 for IBM i Reference Manual

[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

146

:

:

. . . . . . . .

. . . . . . . .

. . . . . . . .

 Zend Server for IBM i

( [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: "; print_r($outputFields); echo "
"; // Print the input fields information

147

 Zend Server 5 for IBM i Reference Manual

echo "
"; print_r($inputFields); echo "
"; // 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

148

 Zend Server for IBM i

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.

149

 Zend Server 5 for IBM i Reference Manual

Troubleshooting the Zend 5250 Bridge Problem

Solution

The Zend 5250 Bridge environment is

1. In the Zend 5250 Management Menu

occasionally 'overloaded'.

(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.

150

 Zend Server for IBM i

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

The 5250 Bridge does not generate HTML.

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

The 5520 Bridge API is an integrated part of Zend

order to get the 5250 Bridge API?

Server for IBM i

What IBM i Version does the 5250

The 5250 Bridge runs on V5R4, or later and utilizes

Bridge Support?

5250 CPW interactive processes.

How does the 5250 Bridge API

The basic process is as follows:

work from the PHP script?

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)

The 5250 Bridge can handle an unlimited amount of

sessions does the 5250 Bridge

concurrent 5250 sessions. Only when using an

allow to open?

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.

151

 Zend Server 5 for IBM i Reference Manual

Are 5250 sessions opened by the

The 5250 Bridge uses the IBM WebFace server which

5250 Bridge using IBM i interactive

allows the running of interactive (5250) programs in

feature?

batch mode.

Does the 5250 Bridge support

The 5250 Bridge utilizes the IBM WebFace server

Workstation IDs?

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

The 5250 Bridge installation includes two Javascript

keys such as F3, F12, etc?

files, which allow the catching of function key clicks.

(Bridge API)

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

The demo applications run on default settings. There

slow?

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

The 5250 Bridge API has two types of interfaces:

programming?

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

You can use the demo application code as a base to

demo program screens and turn

create Web applications utilizing the 5250 Bridge API.

fields into selection lists or radio

You can enrich your browser applications with Web

buttons?

features such as Rich-text, sound and images, AJAX and Mashups.

152

 Zend Server for IBM i

153

 Zend Server 5 for IBM i Reference Manual

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:

154

ƒ

Java Bridge Use Cases

ƒ

Adding Extensions

ƒ

Compiling PHP Extensions

ƒ

Info Messages

 Zend Server for IBM i

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.

155

 Zend Server 5 for IBM i Reference Manual

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: get_news($_GET['ticker']); // display results foreach($news as $news_item) { print "$news_item
\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.

156

 Zend Server for IBM i

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:  "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.
Current shopping cart: 
"; // get shopping cart data from the bean $cart = $store->get_cart($_GET['client_id']); foreach($cart as $item) {

157

 Zend Server 5 for IBM i Reference Manual

print "$item['name']: $item['count'] at $item['price']
\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.

158

 Zend Server for IBM i

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

159

 Zend Server 5 for IBM i Reference Manual

Zend Server Extension List - PHP 5.2 Common Extensions Common extensions are installed and enabled by default in typical installations

Extension Status

Description Arbitrary precision mathematics functions based on the bcmatch (Binary

Bcmath

Enabled

bz2

Enabled

calendar

Enabled

ctype

Enabled

curl

Enabled

date

Built-in

dom

Built-in

exif

Enabled Enables access to image EXIF (Exchangeable Image File Format) meta data

filter

Built-in

ftp

Enabled Provides low-level client access to FTP (File Transfer Protocol) servers

gd

Enabled

gettext

Enabled

hash

Built-in

i5comm

Enabled

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

160

Calculator) library The bzip2 functions are used to transparently read and write bzip2 (.bz2) compressed files and streams The calendar extension provides functions that simplify conversion between different calendar formats Character Classifications - Checks whether a character or string falls into a certain character class according to the current locale Enables you to connect to and communicate with different types of servers using various protocols - for example HTTP and FTP Enables various date and time related functions that can handle retrieving the time, date formatting and more Enables operating on an XML document using the Document Object Model (DOM) API

Provides a set of functions for validating and filtering data coming from insecure sources, such as user inputs

Enables creation, manipulation and streaming of images and graphics in various formats Provides a set of functions that allow internationalization of PHP applications through the GNU gettext API Enables direct or incremental processing of arbitrary length messages using a variety of hashing algorithms Provides access to all IBM i system resources such as RPG/COBOL/CL programs, database files / tables, spooled files, data queue and more

Provides Unicode and global localization support to PHP applications using the ICU library

 Zend Server for IBM i

Extension Status

Description

json

Enabled Implements the JavaScript Object Notation (JSON) data-interchange format

ldap

Enabled

libxml

Built-in Provides basic API and infrastructure for other XML processing extensions

mbstring

Enabled

mcrypt

Enabled Provides support for multiple encryption algorithms using the mcrypt library

Provides access to LDAP (Lightweight Directory Access Protocol) based directory servers; Based on the OpenLDAP library

Enables manipulation of strings encoded in multi-byte character encoding schemes

Provides support for multiple hashing algorithms using the mhash library. Can be mhash

Enabled 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 Provides legacy access to MySQL database servers. For new applications it is

mysql

Enabled

mysqli

Enabled

openssl

Built-in

pcre

Built-in

pdo

Built-in

pdo_mysql

Enabled

pdo_oci

Enabled

pdo_pgsql

Enabled

pdo_sqlite

Built-in

pgsql

Enabled Provides access to PostgreSQL database servers

posix

Enabled

reflection

Built-in

session

Built-in Enables data persistence between consecutive requests of the same user session

recommended to use the 'mysqli' extension MySQL Improved - Provides access to MySQL database servers. Enables the functionality provided by MySQL 4.1 and above This module utilizes the OpenSSL library for generation and verification of signatures and for encrypting and decrypting data and streams Provides a set of functions for string matching and manipulation based on Perl Compatible Regular Expressions syntax Base PDO (PHP Data Objects) Driver - Defines a lightweight, consistent interface for accessing databases in PHP PDO (PHP Data Objects) driver that enable access from PHP to MySQL database servers PDO (PHP Data Objects) driver that enable access from PHP to Oracle database servers using the OCI library PDO (PHP Data Objects) driver that enable access from PHP to PostgreSQL database servers PDO (PHP Data Objects) driver that enable access from PHP to SQLite database files

Contains an interface to functions defined in the IEEE 1003.1 (POSIX.1) standards document which are not accessible through other means Adds the ability to reverse-engineer classes, interfaces, functions and methods as well as extensions

161

 Zend Server 5 for IBM i Reference Manual

Extension Status

Description The SimpleXML extension provides a very simple and easily usable toolset to

simplexml

Built-in 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

spl

Built-in

sqlite

Enabled

standard

Built-in Standard PHP functions

tidy

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 is a collection of interfaces and classes that can be used to solve standard problems Enables usage of the SQLite Embeddable SQL Database Engine. Can be used for SQL database access without running a separate RDBMS process

Tidy HTML Clean and Repair - enables you to not only clean and otherwise manipulate HTML documents, but also traverse the document tree The tokenizer functions provide an interface to the PHP tokenizer embedded in

tokenizer

Enabled

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

xmlreader

Enabled

xmlwriter

Enabled

xsl

Enabled

zip

Enabled

Enables the creation of event-based XML document parsers using the SAX XML interface 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. Provides a non-cached, forward-only writer for generating streams or files containing XML data in an efficient manner The XSL extension implements the XSL standard, performing XSLT transformations using the libxslt library ZIP Archives - Enables you to transparently read ZIP compressed archives and the files inside them Enables you to transparently read and write gzip (.gz) compressed files, through

zlib

Built-in versions of most of the filesystem functions which work with gzip-compressed files

162

 Zend Server for IBM i

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 Allows retrieval of information regarding many different file types. This

fileinfo

Disabled information includes file type and encoding, as well as more specific information such as dimensions, quality or length These functions allow you to work with arbitrary-length integers using the GNU

gmp

Disabled

imagick

Enabled Enables image creation and manipulation using the ImageMagick API

memcache

Disabled

ming

Disabled

mssql

Disabled

odbc

Disabled Provides access to several database servers through the Unified ODBC interface

MP library

Provides access to memcached - a highly efficient memory based caching daemon Provides a set of functions that can be used to create SWF ("Flash") format animations; Based on the open-source Ming library Provides access to MS SQL Server database; Based on the open-source FreeTDS library

Process Control Functions - Process Control support in PHP implements the Unix pcntl

Disabled style of process creation, program execution, signal handling and process termination PDO (PHP Data Objects) driver that enable access from PHP to MSSQL and other

pdo_dblib

Disabled

pdo_odbc

Disabled databases through ODBC drivers or through the IBM DB2 Call Level Interface

databases accessible through the FreeDTS interface PDO (PHP Data Objects) driver that enable access from PHP to different (DB2 CLI) library

pspell

Enabled

shmop

Disabled

Provides spell checking and dictionary management functionality based on the pspell library Shared Memory - Shmop is an easy-to-use set of functions that allows PHP to read, write, create and delete Unix shared memory segments Enables System V messages support - The messaging functions may be used to

sysvmsg

Disabled

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 Enables System V semaphore support - Semaphores may be used to provide

sysvsem

Disabled exclusive access to resources on the current machine, or to limit the number of processes that may simultaneously use a resource

163

 Zend Server 5 for IBM i Reference Manual

Extension Status

Description Enables System V shared memory support - Shared memory may be used to

sysvshm

Disabled

wddx

Disabled

xmlrpc

Disabled Provides a set of functions that can be used to write XML-RPC servers and clients

provide access to global variables WDDX (Web Distributed Data Exchange) - These functions are intended for work with the WDDX data exchange format

Standalone Extensions Standalone extensions are provided by Zend but are not included in any of the meta-packages / categories above.

Extension Status

Description Provides functions that enable you to access the IBM DB2 Universal Database,

ibm_db2

Enabled

pdo_ibm

Enabled PDO (PHP Data Objects) driver that enable access from PHP to IBM databases

164

IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface

 Zend Server for IBM i

Zend Server Extension List - PHP 5.3 Common Extensions Common extensions are installed and enabled by default in typical installations

Extension Status

Description Arbitrary precision mathematics functions based on the bcmatch (Binary

bcmath

Enabled

bz2

Enabled

calendar

Enabled

Core

Built-in Core PHP functionality

Ctype

Enabled

Curl

Enabled

Date

Built-in

Dom

Built-in

Ereg

Built-in

Exif

Enabled Enables access to image EXIF (Exchangeable Image File Format) meta data

Calculator) library The bzip2 functions are used to transparently read and write bzip2 (.bz2) compressed files and streams The calendar extension provides functions that simplify conversion between different calendar formats

Character Classifications - Checks whether a character or string falls into a certain character class according to the current locale Enables you to connect to and communicate with different types of servers using various protocols - for example HTTP and FTP Enables various date and time related functions that can handle retrieving the time, date formatting and more Enables operating on an XML document using the Document Object Model (DOM) API Provides a set of string pattern matching functions using POSIX extended regular expressions.

Allows retrieval of information regarding many different file types. This fileinfo

Enabled information includes file type and encoding, as well as more specific information such as dimensions, quality or length Provides a set of functions for validating and filtering data coming from insecure

Filter

Built-in

ftp

Enabled Provides low-level client access to FTP (File Transfer Protocol) servers

Gd

Enabled

gettext

Enabled

Hash

Built-in

sources, such as user inputs

Enables creation, manipulation and streaming of images and graphics in various formats Provides a set of functions that allow internationalization of PHP applications through the GNU gettext API Enables direct or incremental processing of arbitrary length messages using a variety of hashing algorithms

165

 Zend Server 5 for IBM i Reference Manual

Extension Status

Description Provides access to all IBM i system resources such as RPG/COBOL/CL programs,

i5comm

Enabled

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

Json

Enabled Implements the JavaScript Object Notation (JSON) data-interchange format

Ldap

Enabled

libxml

Built-in Provides basic API and infrastructure for other XML processing extensions

mbstring

Enabled

mcrypt

Enabled Provides support for multiple encryption algorithms using the mcrypt library

mysql

Enabled

mysqli

Enabled

openssl

Built-in

Pcre

Built-in

Pdo

Built-in

pdo_mysql

Enabled

pdo_oci

Enabled

pdo_pgsql

Enabled

pdo_sqlite

Built-in

Pgsql

Enabled Provides access to PostgreSQL database servers

Phar

Enabled Allows running of complete PHP applications out of .phar package files

Posix

Enabled

166

database files / tables, spooled files, data queue and more

Provides Unicode and global localization support to PHP applications using the ICU library

Provides access to LDAP (Lightweight Directory Access Protocol) based directory servers; Based on the OpenLDAP library

Enables manipulation of strings encoded in multi-byte character encoding schemes

Provides legacy access to MySQL database servers. For new applications it is recommended to use the 'mysqli' extension MySQL Improved - Provides access to MySQL database servers. Enables the functionality provided by MySQL 4.1 and above This module utilizes the OpenSSL library for generation and verification of signatures and for encrypting and decrypting data and streams Provides a set of functions for string matching and manipulation based on Perl Compatible Regular Expressions syntax Base PDO (PHP Data Objects) Driver - Defines a lightweight, consistent interface for accessing databases in PHP PDO (PHP Data Objects) driver that enable access from PHP to MySQL database servers PDO (PHP Data Objects) driver that enable access from PHP to Oracle database servers using the OCI library PDO (PHP Data Objects) driver that enable access from PHP to PostgreSQL database servers PDO (PHP Data Objects) driver that enable access from PHP to SQLite database files

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

Extension Status

Description Adds the ability to reverse-engineer classes, interfaces, functions and methods as

reflection

Built-in

session

Built-in Enables data persistence between consecutive requests of the same user session

well as extensions

The SimpleXML extension provides a very simple and easily usable toolset to simplexml

Built-in 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

Spl

Built-in

Sqlite

Enabled

standard

Built-in Standard PHP functions

Tidy

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 is a collection of interfaces and classes that can be used to solve standard problems Enables usage of the SQLite Embeddable SQL Database Engine. Can be used for SQL database access without running a separate RDBMS process

Tidy HTML Clean and Repair - enables you to not only clean and otherwise manipulate HTML documents, but also traverse the document tree The tokenizer functions provide an interface to the PHP tokenizer embedded in

tokenizer

Enabled

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 Enables the creation of event-based XML document parsers using the SAX XML

Xml

Built-in

xmlreader

Enabled

xmlwriter

Enabled

Xsl

Enabled

Zip

Enabled

Zlib

Built-in versions of most of the filesystem functions which work with gzip-compressed

interface 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. Provides a non-cached, forward-only writer for generating streams or files containing XML data in an efficient manner The XSL extension implements the XSL standard, performing XSLT transformations using the libxslt library ZIP Archives - Enables you to transparently read ZIP compressed archives and the files inside them Enables you to transparently read and write gzip (.gz) compressed files, through files

167

 Zend Server 5 for IBM i Reference Manual

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 These functions allow you to work with arbitrary-length integers using the GNU

gmp

Disabled

imagick

Enabled Enables image creation and manipulation using the ImageMagick API

memcache

Disabled

mssql

Disabled

odbc

Disabled Provides access to several database servers through the Unified ODBC interface

pcntl

Disabled style of process creation, program execution, signal handling and process

MP library

Provides access to memcached - a highly efficient memory based caching daemon Provides access to MS SQL Server database; Based on the open-source FreeTDS library

Process Control Functions - Process Control support in PHP implements the Unix 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 (PHP Data Objects) driver that enable access from PHP to different

pdo_odbc

Disabled databases through ODBC drivers or through the IBM DB2 Call Level Interface (DB2 CLI) library

pspell

Enabled

shmop

Disabled

Provides spell checking and dictionary management functionality based on the pspell library Shared Memory - Shmop is an easy-to-use set of functions that allows PHP to read, write, create and delete Unix shared memory segments Enables System V messages support - The messaging functions may be used to

sysvmsg

Disabled

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 Enables System V semaphore support - Semaphores may be used to provide

sysvsem

Disabled exclusive access to resources on the current machine, or to limit the number of processes that may simultaneously use a resource Enables System V shared memory support - Shared memory may be used to

sysvshm

Disabled

wddx

Disabled

xmlrpc

Disabled Provides a set of functions that can be used to write XML-RPC servers and clients

168

provide access to global variables WDDX (Web Distributed Data Exchange) - These functions are intended for work with the WDDX data exchange format

 Zend Server for IBM i

Standalone Extensions Standalone extensions are provided by Zend but are not included in any of the meta-packages / categories above.

Extension Status

Description Provides functions that enable you to access the IBM DB2 Universal Database,

ibm_db2

Enabled

pdo_ibm

Enabled PDO (PHP Data Objects) driver that enable access from PHP to IBM databases

IBM Cloudscape, and Apache Derby databases using the DB2 Call Level Interface

169

 Zend Server 5 for IBM i Reference Manual

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: /zend/lib/php_extensions 3. Add the following line to your php.ini: zend_extension= 4. Restart your server. 5. To restart your server: Click Restart Server

170

in the Administration Interface.

 Zend Server for IBM i

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: " 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: /lib/php_extensions 3. Add the following line to your php.ini: extension=.so Ensure that you replace  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.

171

 Zend Server 5 for IBM i Reference Manual

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.

172

 Zend Server for IBM i

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.2source-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.

173

 Zend Server 5 for IBM i Reference Manual

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/newt1.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/newt1.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-buildroot/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

174

 Zend Server for IBM i

/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/newt1.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-buildroot/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-buildroot/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=.so and replace  with your extension's binary name such as "extension=newt.so".

175

 Zend Server 5 for IBM i Reference Manual

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

176

 Zend Server for IBM i

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.

177

 Zend Server 5 for IBM i Reference Manual

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).

178

 Zend Server for IBM i

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

179

 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

180

 API Reference

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

181

 Zend Server 5 for IBM i Reference Manual

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

182

 API Reference

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

183

 Zend Server 5 for IBM i Reference Manual

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

184

 API Reference

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

185

 Zend Server 5 for IBM i Reference Manual

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

186

 API Reference

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

187

 Zend Server 5 for IBM i Reference Manual

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

188

 API Reference

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

189

 Zend Server 5 for IBM i Reference Manual

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

190

 API Reference

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

191

 Zend Server 5 for IBM i Reference Manual

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

192

 API Reference

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

193

 Zend Server 5 for IBM i Reference Manual

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

194

 API Reference

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

195

 Zend Server 5 for IBM i Reference Manual

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

196

 API Reference

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

197

 Zend Server 5 for IBM i Reference Manual

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

198

 API Reference

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

199

 Zend Server 5 for IBM i Reference Manual

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

200

 API Reference

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

201

 Zend Server 5 for IBM i Reference Manual

202

 API Reference

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

203

 Zend Server 5 for IBM i Reference Manual

204

 API Reference

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

205

 Zend Server 5 for IBM i Reference Manual

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

206

 API Reference

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

207

 Zend Server 5 for IBM i Reference Manual

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

208

 API Reference

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

209

 Zend Server 5 for IBM i Reference Manual

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

210

 API Reference

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

211

 Zend Server 5 for IBM i Reference Manual

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

212

 API Reference

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

213

 Zend Server 5 for IBM i Reference Manual

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

214

 API Reference

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

215

 Zend Server 5 for IBM i Reference Manual

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

216

 API Reference

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

217

 Zend Server 5 for IBM i Reference Manual

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

218

 API Reference

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

219

 Zend Server 5 for IBM i Reference Manual

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: freebsdx86_64 ZenithPE , for: aix-ppc ZenithPE , Type: int Measurement units: Available since: 4.0

220

 API Reference

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: freebsdx86_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:

221

 Zend Server 5 for IBM i Reference Manual

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:  Default value(s): PRGCVF: Type: string Measurement units: Available since: 3.6

222

 API Reference

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: 

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

223

 Zend Server 5 for IBM i Reference Manual

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

224

 API Reference

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

225

 Zend Server 5 for IBM i Reference Manual

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

226

 API Reference

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.



'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. 

'Zend_5250_Response' Class This Class contains information about the page: input and output fields, focused field and application error. 

'Zend_FieldData_Output' Class This Class contains information about the output field data: id, row, column, length, color and value. 

'Zend_FieldData_Input' Class This Class contains information about the input field data: id, row, column, length, color, value, font, type and format. 

231

 Zend Server 5 for IBM i Reference Manual

'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. 

232

 API Reference

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

233

 Zend Server 5 for IBM i Reference Manual

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:

234

ƒ

@param Zend_5250_Resource_Connection $connection

ƒ

@param array $field

 API Reference

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

235

 Zend Server 5 for IBM i Reference Manual

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

236

 API Reference

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 

Object Oriented 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 

Object Oriented 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 

Object Oriented 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();

238

 API Reference

$bridge1->disconnect(); $bridge2->disconnect(); ?>

239

 Zend Server 5 for IBM i Reference Manual

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

240

 API Reference

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

241

 Zend Server 5 for IBM i Reference Manual

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

242

 API Reference

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

243

 Zend Server 5 for IBM i Reference Manual

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

244

 API Reference

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

245

 Zend Server 5 for IBM i Reference Manual

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

246

 API Reference

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

247

 Zend Server 5 for IBM i Reference Manual

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

248

 API Reference

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

249

 Zend Server 5 for IBM i Reference Manual

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

250

 API Reference

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

251

 Zend Server 5 for IBM i Reference Manual

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

252

 API Reference

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

253

 Zend Server 5 for IBM i Reference Manual

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

254

 API Reference

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

255

 Zend Server 5 for IBM i Reference Manual

256

 API Reference

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

257

 Zend Server 5 for IBM i Reference Manual

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

258

 API Reference

259

 Zend Server 5 for IBM i Reference Manual

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

260

 API Reference

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

261

 Zend Server 5 for IBM i Reference Manual

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

262

 API Reference

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

263

 Zend Server 5 for IBM i Reference Manual

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

264

 API Reference

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

265

 Zend Server 5 for IBM i Reference Manual

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

266

 API Reference

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

267

 Zend Server 5 for IBM i Reference Manual

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

268

 API Reference

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

269

 Zend Server 5 for IBM i Reference Manual

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

270

 API Reference

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

271

 Zend Server 5 for IBM i Reference Manual

PHP Toolkit for IBM i Introduction to the PHP Toolkit for IBM i This section includes the following topics:

272

ƒ

PHP Toolkit for IBM i

ƒ

PHP Toolkit Functions

ƒ

PHP Toolkit Data Description

ƒ

Program Samples

ƒ

I5 Toolkit Templates

 API Reference

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

273

 Zend Server 5 for IBM i Reference Manual

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.

274

 API Reference

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

275

 Zend Server 5 for IBM i Reference Manual

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 
";

/* 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 "
 Error number: ".$error["num"]; echo "
 Error category: ".$error["cat"]; echo "
 Error message: ".$ error ["msg"]; echo "
 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. */

276

 API Reference

/* Make it available for another script. */ $ret = i5_close($conn); if($ret){ echo " I5 disconnected"; } else { $ret = i5_errormsg($conn); }

Example - Private Connection "; } else { echo "No connection ID stored.
"; } // 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
"; $_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).

277

 Zend Server 5 for IBM i Reference Manual

ƒ

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 
"; [treatments...] $closing = i5_pclose($conn); if ($closing) { echo "Disconnection succeeds"; } }

278

 API Reference

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

279

 Zend Server 5 for IBM i Reference Manual

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]).

280

ƒ

Description: Gets error message for last executed action.

ƒ

Return Values: Error message string.

ƒ

Arguments: connection - Connection - result of i5_connect.

 API Reference

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
" ;. print "User library : $userlib
" ;. print "System libs list : $syslib
" ;. print "Current library : $curl
" ;.

281

 Zend Server 5 for IBM i Reference Manual

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 = "   

282

 API Reference

                        ";

PCML Example 2: ($description = file_get_contents("/www/zendSvr/htdocs/teststruc.pcml")) or trigger_error("Error while opening PCML file", E_USER_ERROR);

283

 Zend Server 5 for IBM i Reference Manual

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']
";. } else {. print "Program call failed.
";. }.

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).

284

ƒ

Description: Frees program resource handle.

ƒ

Return Values: Boolean success value.

ƒ

Arguments: program - Program resource opened by program_open.

 API Reference

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).

285

 Zend Server 5 for IBM i Reference Manual

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 ).

286

ƒ

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

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.

287

 Zend Server 5 for IBM i Reference Manual

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.

288

ƒ

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

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 ).

289

 Zend Server 5 for IBM i Reference Manual

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.

•

290

values - Values for the key fields - array of key=>value pairs.

 API Reference

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.

291

 Zend Server 5 for IBM i Reference Manual

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).

292

ƒ

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

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'));.

293

 Zend Server 5 for IBM i Reference Manual

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: •

294

file - Opened i5 file resource.

 API Reference

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 ""; $i = 0; while ($values = i5_fetch_row($query, I5_READ_NEXT) AND ($i < 10)) { $i++; echo ""; echo ""; echo ""; echo ""; echo ""; echo ""; echo ""; echo ""; } echo "
" .$values[0]. "
" .$values[1]. "
" .$values[2]. "
" .$values[3]. "
" .$values[4]. "
" .$values[5]. "
"; } i5_free_query($query);

295

 Zend Server 5 for IBM i Reference Manual

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 ...] ) -Orbool 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().

296

ƒ

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

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);

297

 Zend Server 5 for IBM i Reference Manual

i5_getblob string i5_getblob( resource result, int position ) -Orstring 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: •

298

result - Parameterized file ID

 API Reference

•

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 ) } }

299

 Zend Server 5 for IBM i Reference Manual

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.
"; } i5_setparam($req, 2, "Hercule"); i5_setparam($req, 3, 3.8); $result = i5_execute($req); if ($result) { print "Hercule adding successful.
"; }

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

300

 API Reference

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. "; 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()."
"; //echo $err; } else { "
executed"; } echo "
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)

301

 Zend Server 5 for IBM i Reference Manual

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.

302

ƒ

Return Values: TRUE on success or FALSE on failure

ƒ

Arguments: query - query resource

 API Reference

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: 

305

 Zend Server 5 for IBM i Reference Manual

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.

ƒ

306

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

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: "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: "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); ?>

307

 Zend Server 5 for IBM i Reference Manual

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");.

308

 API Reference

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

309

 Zend Server 5 for IBM i Reference Manual

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

310

 API Reference

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()

311

 Zend Server 5 for IBM i Reference Manual

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: •

312

handle - Job list handle as returned by 15_job_list()

 API Reference

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.

313

 Zend Server 5 for IBM i Reference Manual

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]).

314

ƒ

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

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

315

 Zend Server 5 for IBM i Reference Manual

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

316

 API Reference

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 ()

317

 Zend Server 5 for IBM i Reference Manual

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:  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.

318

 API Reference

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: "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); ?>

319

 Zend Server 5 for IBM i Reference Manual

Data Types I5_TYPE_CHAR

I5_TYPE_INT

I5_TYPE_PACKED

I5_TYPE_ZONED

I5_TYPE_FLOAT

I5_TYPE_BYTE

I5_TYPE_STRUCT (long format uses DSName to define structure)

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_PHP_COMMAND_E

I5_ERR_PHP_HDLBAD

I5_ERR_TOOMUCHOPEN

RROR

I5_ERR_PHP_OPTIONSNUM

FILE

I5_ERR_PHP_GET_SYSVAL

BER

I5_ERR_INVALIDPTR

I5_ERR_PHP_BAD_DEF

I5_ERR_PHP_TYPEPARAM

I5_ERR_INVALIDFIELDNB

I5_ERR_PHP_NO_DS_VALU

I5_ERR_PHP_TYPEGET

R

E

I5_ERR_PHP_BOOKMARK

I5_ERR_INVALIDKEYNBR

I5_ERR_ENDOFOCC

I5_ERR_PHP_CALL_BINDPA

I5_ERR_INVALIDOPENMO

I5_ERR_DESC_UNEXP

RAM

DE

I5_ERR_DESC_WRONG_DA

I5_ERR_PHP_BINDPARAM

I5_ERR_RECORDLOCKED

TAOP

I5_ERR_PHP_BLOBSIZE

I5_ERR_FILELIMITS

I5_ERR_PHP_BAD_PROG_

I5_ERR_PHP_INTERNAL

I5_ERR_INVALIDSEQ

NAME

I5_ERR_PHP_NO_COMMAND

I5_ERR_NOLINKDEFINED

I5_ERR_PHP_NOT_DTAQ_K

I5_ERR_PHP_NO_KEYNAME

I5_ERR_NULLNOTALLOW

EY

I5_ERR_PHP_NO_ZVALUE

ED

I5_ERR_PHP_DESC_EMPTY

I5_ERR_PHP_DATAREA_REA

I5_ERR_WRONGLOGIN

I5_ERR_PHP_LIST_PROP

D

I5_ERR_FIELDNULL

I5_ERR_PHP_API_LENGTH

I5_ERR_PHP_ELEMENT_MIS

I5_ERR_INVALIDINFO

I5_ERR_ERROR

SING

320

 API Reference

I5_ERR_RECORDCHANG

I5_ERR_MEMALLOC

I5_ERR_PHP_BAD_KEYNAM

ED

I5_ERR_FIELDNOTFOUND

E

I5_ERR_NOTINTRAN

I5_ERR_INVALIDKEYLEN

I5_ERR_PARAMNOTFOUND

I5_ERR_PHP_HDLCONN

I5_ERR_NOTENABLETOUP

I5_ERR_PHP_BAD_DS_INPU

I5_ERR_PHP_OPTIONSTY

DATE

T

PE

I5_ERR_RECORDNOTFOUN

I5_ERR_DQDESC_UNSUPP

I5_ERR_PHP_RESOURCE

D

I5_ERR_INCORRECTVALUE

_BAD

I5_ERR_BEOF

I5_ERR_PHP_AS400_MESSA

I5_ERR_PHP_NBPARAM_

I5_ERR_NOTCONNECTED

GE

BAD

I5_ERR_NORANGESET

I5_ERR_PHP_DTAQ_BADKE

I5_ERR_PHP_OPERATOR

I5_ERR_NOCURRENTRECO

Y

_BAD

RD

I5_ERR_PHP_BAD_LEN_PRO

I5_ERR_PHP_NOT_BOOK

I5_ERR_BADSESSION

P

MARK

I5_ERR_NOTENOUGHRIGH

I5_ERR_PHP_SPOOL_FILE_F

I5_ERR_PHP_GETPARAM

TS

OPEN

I5_ERR_PHP_PARAM_DE

I5_ERR_INVALIDTYPE

SC

I5_ERR_NOTTYPEPROPER

I5_ERR_PHP_VARIABLE

TY

I5_ERR_PHP_EXECUTE

I5_ERR_ALLREADYINTRAN

I5_ERR_PHP_EMPTY_AR

I5_ERR_PHP_HDLDFT

RAY I5_ERR_PHP_NO_PARMN AME

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

321

 Zend Server 5 for IBM i Reference Manual

ƒ

•

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

•

I5_IN

•

I5_OUT

•

default is input, these values can be OR'ed together to get input-output value

IO

ƒ

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: "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); ?>

322

 API Reference

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_ALW_MULTI_THRE

I5_JOB_ACT_ENDJOB_ST

I5_JOB_BRKMSG

ADS

S

I5_JOB_CNTRYID

I5_JOB_CANCEL_KEY

I5_JOB_CCSID

I5_JOB_POOL_ID

I5_JOB_USRPRF

I5_JOB_COMPLETION_ST

I5_JOB_PROCESS_UNIT_TIM

I5_JOB_CHAR_ID_CTRL

S

E_DB

I5_JOB_DATETIME_ACTIVE

I5_JOB_PROCESS_UNIT_

I5_JOB_DATETIME_SCHED

I5_JOB_DATETIME_JOBQ

TIME

I5_JOB_DATSEP

I5_JOB_DBCS_CAP

I5_JOB_DATETIME_IN

I5_JOB_DFTWAIT

I5_JOB_DEVRCYACN

I5_JOB_DATFMT

I5_JOB_DFTCCSID

I5_JOB_DECFMT

I5_JOB_DDM_HANDLE

I5_JOB_ENDSEV

I5_JOB_ENDSTS

I5_JOB_DEVNAME

I5_JOB_FUNC_NAME

I5_JOB_FUNC_TYPE

I5_JOB_DATETIME_END

I5_JOB_GRPPRFNAME

I5_JOB_GRPPRFNAME_SU

I5_JOB_EXITKEY

I5_JOB_ACCOUNT_CODE

P

I5_JOB_SIGNED_JOB

I5_JOB_QUEUE_NAME

I5_JOB_DATE

I5_JOB_INQMSGRPLY

I5_JOB_JOBMSGQFL

I5_JOB_QUEUE_PTY

I5_JOB_DESC_NAME

I5_JOB_USRID_SETTING

I5_JOB_JOBMSGQ_SIZE

I5_JOB_SWITCHES

I5_JOB_TYPE_ENHANCED

I5_JOB_END_REASON

I5_JOB_USRID

I5_JOB_LOGCLPGM

I5_JOB_LANGID

I5_JOB_LOG_PENDING

I5_JOB_MODE_NAME

I5_JOB_LOGSEV

I5_JOB_LOGLVL

I5_JOB_MAX_THREADS

I5_JOB_MAX_PROC_UNIT_

I5_JOB_LOGTEXT

I5_JOB_MSGRPL

TIME

I5_JOB_MAX_TMP_STG_K

I5_JOB_ MCH_LCKW

I5_JOB_MAX_TMP_STG_M

I5_JOB_MEM_POOL_NAM

I5_JOB_OUTQ_NAME

I5_JOB_INTERACTIVE_TRS

E

I5_JOB_PRTDEVNAME

I5_JOB_NONDB_LCKW

I5_JOB_DB_LCKWAIT

I5_JOB_PROG_RETCODE

I5_JOB_OUTQ_PTY

I5_JOB_AUX_IOREQ

I5_JOB_RESPONSE_TIME

I5_JOB_PURGE

I5_JOB_PRTTEXT

323

 Zend Server 5 for IBM i Reference Manual

I5_JOB_STRSEQ

I5_JOB_PENDING_SGNSET

I5_JOB_PRD_RETCODE

I5_JOB_SBMJOB

I5_JOB_RUNPTY

I5_JOB_PROCESS_ID

I5_JOB_SYSPOOLID

I5_JOB_STS_MSGHDL

I5_JOB_ROUTING_DATA

I5_JOB_SGNSTS

I5_JOB_SBMMSGQ

I5_JOB_STS_JOBQ

I5_JOB_TIMSEP

I5_JOB_SPCLENV

I5_JOB_SBSD

I5_JOB_TMPSTGK

I5_JOB_SVRTYPE

I5_JOB_SGNBLK_MASK

I5_JOB_TIME_NONDB_LCKW

I5_JOB_TIMESLICE

I5_JOB_SPLFILE_ACTION

I5_JOB_TIME_DB_LCKW

I5_JOB_TIMESLICE_END

I5_JOB_THREADCNT

I5_JOB_TIME_MCH_LCKW

Job Log Constants (i5_jobLog_list) array elements constants I5_LOBJ_MESSAGE_SEVERITY

I5_LOBJ_MESSAGE_TY

I5_LOBJ_MESSAGE_FILENA

I5_LOBJ_MESSAGE_IDENTIFIE

PE

ME

R

I5_LOBJ_DATASENT

I5_LOBJ_TIMESENT

I5_LOBJ_ALERTOPT

I5_LOBJ_RPLDATA1

I5_LOBJ_MSG

I5_LOBJ_MSGDTA

I5_LOBJ_MSGHLP

I5_LOBJ_MSGHLPDTA

I5_LOBJ_MSGHLPDTAFMT

I5_LOBJ_DFTRPLY

I5_LOBJ_SNDNAME

I5_LOBJ_SNDTYPE

I5_LOBJ_SNDPGM

I5_LOBJ_SNDMOD

I5_LOBJ_SNDPROC

I5_LOBJ_RCVTYPE

I5_LOBJ_RCVPROG

I5_LOBJ_RCVMOD

I5_LOBJ_RCVPROC

I5_LOBJ_MSGFILE

I5_LOBJ_PROBLEMID

I5_LOBJ_RPLYSTS

I5_LOBJ_RQSSTS

I5_LOBJ_RQSLVL

I5_LOBJ_TXTCCSID

I5_LOBJ_DATACCSID

I5_LOBJ_MESSAGE_FILELIBRA RY I5_LOBJ_TIMESENT_MICRO

Errors I5_TYPE_CHAR I5_ERR_OK I5_ERR_ERROR I5_ERR_TOOMUCHOPENFILE I5_ERR_MEMALLOC

324

 API Reference

Data Retrieval Errors I5_ERR_INVALIDPTR

I5_ERR_NOLINKDEFINED

I5_ERR_FIELDNOTFOUND

I5_ERR_NOCURRENTRECORD

I5_ERR_INVALIDFIELDNBR

I5_ERR_NULLNOTALLOWED

I5_ERR_INVALIDKEYLEN

I5_ERR_BADSESSION

I5_ERR_INVALIDKEYNBR

I5_ERR_WRONGLOGIN

I5_ERR_NOTENABLETOUPDATE

I5_ERR_NOTENOUGHRIGHTS

I5_ERR_INVALIDOPENMODE

I5_ERR_FIELDNULL

I5_ERR_RECORDNOTFOUND

I5_ERR_INVALIDTYPE

I5_ERR_RECORDLOCKED

I5_ERR_INVALIDINFO

I5_ERR_BEOF

I5_ERR_NOTTYPEPROPERTY

I5_ERR_FILELIMITS

I5_ERR_RECORDCHANGED

I5_ERR_NOTCONNECTED

I5_ERR_ALLREADYINTRAN

I5_ERR_INVALIDSEQ

I5_ERR_NOTINTRAN

I5_ERR_NORANGESET

Function Errors I5_ERR_PHP_HDLDFT

I5_ERR_PHP_NO_ZVALUE

I5_ERR_PHP_HDLCONN

I5_ERR_PHP_COMMAND_ERROR

I5_ERR_PHP_HDLBAD

I5_ERR_PHP_DATAREA_READ

I5_ERR_PHP_OPTIONSTYPE

I5_ERR_PHP_GET_SYSVAL

I5_ERR_PHP_OPTIONSNUMBER

I5_ERR_PHP_ELEMENT_MISSING

I5_ERR_PHP_RESOURCE_BAD

I5_ERR_PHP_BAD_DEF

I5_ERR_PHP_TYPEPARAM

I5_ERR_PHP_BAD_KEYNAME

I5_ERR_PHP_NBPARAM_BAD

I5_ERR_PHP_NO_DS_VALUE

I5_ERR_PHP_TYPEGET

I5_ERR_PARAMNOTFOUND

I5_ERR_PHP_OPERATOR_BAD

I5_ERR_ENDOFOCC

I5_ERR_PHP_BOOKMARK

I5_ERR_PHP_BAD_DS_INPUT

I5_ERR_PHP_NOT_BOOKMARK

I5_ERR_DESC_UNEXP

I5_ERR_PHP_CALL_BINDPARAM

I5_ERR_DQDESC_UNSUPP

I5_ERR_PHP_GETPARAM

I5_ERR_DESC_WRONG_DATAOP

I5_ERR_PHP_BINDPARAM

I5_ERR_INCORRECTVALUE

I5_ERR_PHP_PARAM_DESC

I5_ERR_PHP_BAD_PROG_NAME

I5_ERR_PHP_BLOBSIZE

I5_ERR_PHP_AS400_MESSAGE

I5_ERR_PHP_VARIABLE

I5_ERR_PHP_NOT_DTAQ_KEY

325

 Zend Server 5 for IBM i Reference Manual

I5_ERR_PHP_INTERNAL

I5_ERR_PHP_DTAQ_BADKEY

I5_ERR_PHP_EXECUTE

I5_ERR_PHP_DESC_EMPTY

I5_ERR_PHP_NO_COMMAND

I5_ERR_PHP_BAD_LEN_PROP

I5_ERR_PHP_EMPTY_ARRAY

I5_ERR_PHP_LIST_PROP

I5_ERR_PHP_NO_KEYNAME

I5_ERR_PHP_SPOOL_FILE_FOPEN

I5_ERR_PHP_NO_PARMNAME

I5_ERR_PHP_API_LENGTH

326

 API Reference

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: \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 
\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: 
", "Name: ", $name, "
 Code: ", $code, "
"; if ($ret === FALSE) { $errorTab = i5_error(); echo "FAIL : i5_program_call failure code 
"; 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.
\n"); $errorTab = i5_error(); var_dump($errorTab); } i5_close($conn) || print ("FAIL : Failed to disconnect from server :$i5_server_ip"); ?>

327

 Zend Server 5 for IBM i Reference Manual

Service Program  "PHPAIX")); if (is_bool($Hdlcon) && $Hdlcon == FALSE) die(i5_errormsg()); echo "Connected!
"; $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! 
"; } $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! 
"; } echo "code : $code
 name : $name
"; ?>

Data Retrieval \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"
\n 
\n"; print_r($fetch_assoc); echo"
\n 
\n"; print_r($fetch_object); echo"
\n 
\n"; print_r($fetch_row); echo"
\n 
\n"; $info = i5_info($HdlFile,1); print_r($info); echo"
\n 
\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} 
\n Field Lenght: {$field_length} 
\n Field Type: {$field_type} 
\n Field Scale: {$field_scale}
\n"; $list_fields = i5_list_fields($HdlFile); print_r($list_fields); $num_fields = i5_num_fields($HdlFile); echo "
\n {$num_fields}"; $result = i5_result($HdlFile,2);

328

 API Reference

echo "
\n {$result}"; i5_close($Hdlcon); ?>

Native File Access sample "; $fetch = i5_fetch_row($file, I5_READ_NEXT); echo $fetch[0], " ",$fetch[1], " ", $fetch[2], "
"; i5_range_clear($file); $fetch = i5_fetch_row($file, I5_READ_FIRST); echo $fetch[0], " ",$fetch[1], " ", $fetch[2], "

"; i5_data_seek($file, 2); $rowTab = i5_fetch_row($file); echo $rowTab[0], " ",$rowTab[1], " ", $rowTab[2], "
"; $tab=array(1510); $seek = i5_seek($file, "=", $tab); $rowTab = i5_fetch_row($file); echo $rowTab[0], " ",$rowTab[1], " ", $rowTab[2], "
"; $id = i5_bookmark($file); echo $id, "
"; 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); ?>

329

 Zend Server 5 for IBM i Reference Manual

Data Queues Data Queue Without Key "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 "
\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 "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 "
\n"; $parameter = array("PS1"=>"test1", "PS2"=>13.1415, "PS3"=>"test2"); $key = "abcd"; $ret = i5_dtaq_send($dtaqHdl_KEY, $key, $parameter); var_dump($ret); echo "
\n"; $ret = i5_dtaq_receive($dtaqHdl_KEY, "EQ", $key); var_dump($ret); i5_dtaq_close($dtaqHdl_KEY); i5_close($conn); ?>

System Values 

User Spaces 10,

330

 API Reference

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! 
\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! 
\n"; $ret = i5_userspace_put($UspcHdlBad, $parameter); if ($ret) echo "3. It works! 
\n"; $ret = i5_userspace_get($UspcHdl, $parmOut); if (!$ret) echo "4. It works! 
\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  "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!
"; $listHdl = $ret; echo 'i5_job_list_read: '; $ret = i5_job_list_read($listHdl); if (!$ret) die(i5_errormsg()); else echo "It works! 
"; echo 'i5_job_list_close: '; $ret = i5_job_list_close($listHdl); if (!$ret) { die(i5_errormsg()); } else { echo "It works! 
";

331

 Zend Server 5 for IBM i Reference Manual

} $listHdl = i5_job_list(array(I5_JOBNAME=>"*ALL", I5_JOBTYPE=>"S")); if (is_bool($listHdl)) die(i5_errormsg()); else echo "List 
";

$a= 0; $ret = true; while($ret && $a < 3){ echo "
Message $a
"; $ret = i5_job_list_read($listHdl); $a ++; if (is_bool($ret)) die(i5_errormsg()); else { print_r($ret);echo "
"; echo "Job queue Name : " . $ret[I5_JOB_QUEUE_NAME] . ", Response Id : " . $ret[I5_JOB_PROCESS_ID] . "
"; echo "I5_JOB_JOBMSGQFL : " . $ret[I5_JOB_JOBMSGQFL] . "
"; } } $ret = i5_job_list_close($listHdl); ?>

Job Log List  "PHPAIX")); if (is_bool($Hdlcon) && $Hdlcon == FALSE){ die(i5_errormsg());} $listHdl = i5_jobLog_list(); if (is_bool($listHdl)) die(i5_errormsg()); else echo "List
"; $a= 0; $ret = true; while($ret && $a < 2){ echo "Message $a
"; $ret = i5_jobLog_list_read($listHdl); $a ++; if (is_bool($ret)) die(i5_errormsg()); else { print_r($ret);echo "
"; echo "Message : " . $ret[I5_LOBJ_MSG]. ",
 data : ". $ret[I5_LOBJ_MSGDTA] . "
"; } } $ret = i5_jobLog_list_close($listHdl); if (is_bool($ret)) die(i5_errormsg()); else { print_r($ret);echo "
"; echo "Message : " . $ret[I5_LOBJ_MSG]. ",
 data : ". $ret[I5_LOBJ_MSGDTA] . "
"; ?>

332

 API Reference

Data Areas "; $ret = i5_data_area_write("eacdemo/MYDTA", "'coucou'"); if ($ret) echo "3.It works! 
"; $ret = i5_data_area_read("eacdemo/MYDTA", 2, 4); if ($ret) echo "4.It works!: ", $ret, "
"; $ret = i5_data_area_read("eacdemo/MYDTA"); if ($ret) echo "5.It works!: ", $ret, "
"; $ret = i5_data_area_write("eacdemo/MYDTA", "'lina'", 5, 45); if ($ret) echo "6.It works! 
"; $ret = i5_data_area_read("eacdemo/MYDTA", 1, 5); if ($ret) echo "7.It works!: ", $ret, "
"; $ret = i5_data_area_read("eacdemo/MYDTA"); if ($ret) echo "8.It works!: ", $ret, "
"; $ret = i5_data_area_delete("eacdemo/MYDTA"); if ($ret) echo "9.It works! 
"; ?>

Spooled Files Connect fail"); echo "
================
"; echo "
connected."; $spool = i5_spool_list(array("username"=>"lina"),$conn); if ($spool) { $count = 0; while (($a = i5_spool_list_read($spool)) && ($count <= 2)) { echo "
================
"; var_dump($a); echo "
data {$count}:
"; $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("
Connect fail"); echo "
================
"; echo "
connected. 
"; $objects = i5_objects_list("EACDEMO", "*ALL", "*PGM"); if ($objects) echo "1.It works! 
"; $HdlObj = $objects; $objects = i5_objects_list_read($HdlObj); if (!is_bool($objects)) { echo "2.It works! 
"; print_r($objects); echo "
"; } $continue = true;

333

 Zend Server 5 for IBM i Reference Manual

$count = 0; while($continue) { $objects = i5_objects_list_read($HdlObj); if (is_bool($objects) && $objects == FALSE ) $continue = false; else { echo "3.It works! 
"; print_r($objects); echo "
"; } $count ++; if ($count == 2) break; } $objects = i5_objects_list_close($HdlObj); if (is_bool($objects) && $objects == FALSE) $continue = false; else echo "4.It works! 
"; ?>

334

 API Reference

PCML Program Call - PCML Description Used in the PHP Program          "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 = "                            "; // define some input values $pack3value=7789777.44;

335

 Zend Server 5 for IBM i Reference Manual

$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 "
S1:"; var_dump($S1_Value); echo "
S2:"; var_dump($S2_Value); echo "
CH10:"; var_dump($CH10_Value); echo "
CH11:"; var_dump($CH11_Value); echo "
CH12:"; var_dump($CH12_Value); echo "
CH13:"; var_dump($CH13_Value); echo "
Code:"; var_dump($Code_Value); echo "
Pack:"; var_dump($Pack); ?>  

336

 API Reference

PCML Program Call 2 - PCML File External to PHP Program          "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 "
S1:"; var_dump($S1_Value); echo "
S2:"; var_dump($S2_Value); echo "
CH10:"; var_dump($CH10_Value); echo "
CH11:"; var_dump($CH11_Value); echo "
CH12:"; var_dump($CH12_Value); echo "
CH13:"; var_dump($CH13_Value); echo "
Code:"; var_dump($Code_Value); echo "
Pack:"; var_dump($Pack); ?>  

337

 Zend Server 5 for IBM i Reference Manual

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

338

 API Reference

Web Services 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();

339

 Zend Server 5 for IBM i Reference Manual

?>

Web Services - Client Side service_for_i5_program('111', ' ')); } catch (SoapFault $exception) { echo $exception; } ?

340

 API Reference

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:

341

 Zend Server 5 for IBM i Reference Manual

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

342

 API Reference

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

343

 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

344

 Zend Server for IBM i Installation Guide

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

345

 Zend Server 5 for IBM i Reference Manual

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)

346

 Zend Server for IBM i Installation Guide

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.

347

 Zend Server 5 for IBM i Reference Manual

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.

348

 Zend Server for IBM i Installation Guide

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 Save file . . . . . . . . . . . zsvrsavf Library . . . . . . . . . . .

QGPL

Character value, *ONLY, *NO Name 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

349

 Zend Server 5 for IBM i Reference Manual

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

350

 Zend Server for IBM i Installation Guide

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

351

 Zend Server 5 for IBM i Reference Manual

7. The program will be installed.

352

 Zend Server for IBM i Installation Guide

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:

353

 Zend Server 5 for IBM i Reference Manual

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.

354

 Zend Server for IBM i Installation Guide

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:

355

 Zend Server 5 for IBM i Reference Manual

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.

356

 Zend Server for IBM i Installation Guide

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'.

357

 Zend Server 5 for IBM i Reference Manual

ƒ

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.

358

 Zend Server for IBM i Installation Guide

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.

359

 Zend Server 5 for IBM i Reference Manual

Post Installation This section includes the following Post Installation instructions:

360

ƒ

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

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://: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

361

 Zend Server 5 for IBM i Reference Manual

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://:2001.

362

 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 PHP

Loaded +

Description

Installation Path

The Zend certified version of

IBM i : /lib/php/libphp5.so

Comments

PHP 5.2.x that includes commonly used and Zend extensions.

Zend

+

Zend’s extension for using

IBM i : /lib/optimizerplus

opcode caching and

Optimizer+

optimizations for PHP.

Zend Guard

+

The Zend Guard Loader for

IBM i : /lib/loader

running PHP, encoded with

Loader

Zend Guard.

Zend Debugger

+

Zend’s extension for server

IBM i : /lib/debugger

side debugging, profiling and code coverage.

363

 Zend Server 5 for IBM i Reference Manual

Component

Loaded

Zend Cache

+

Description

Installation Path

A Zend extension for PHP

IBM i : /lib/datacache

Comments

data caching and partial PHP output caching.

Java Server

-

The Java PHP extension,

IBM i :

Java daemon and setup files.

PHP Extensions /lib/jbridge/php.5.2.x/zendbridge.so Java Daemon /lib/jbridge/jawamw.jar

Java Bridge

+

Enables integration of Java

IBM i : /lib/jbridge Note: Requires SUN’s JRE 1.4 or

libraries and classes within PHP applications.

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

364

IBM i: /lib/monitor

 Zend Server for IBM i Installation Guide

Component

Loaded

Description

Installation Path

Comments

application.

Page Cache

+

A URL based HTML output

IBM i: /lib/pagecache

cache for PHP scripts.

Zend

+

Framework

Installs Zend's open-source

IBM i : /share/ZendFramework

This installs libraries

framework for developing

containing the Zend

Web Applications and Web

framework components.

Services in PHP.

phpMyAdmin

-

A popular open-source

Available in GA

management tool for handling

Only relevant for MySql Database user.

MySql Database over a Web interface.

MySQL

-

Installs a complete MySql

IBM i: /usr/local/MySQL

database on the Web Server.

Downloaded during installation. (Usually the

MySQL server's user name and password

password is "root" for

IBM i : Default - "root" and no password

administrators). For more

365

 Zend Server 5 for IBM i Reference Manual

Component

Loaded

Description

Installation Path

Comments information see: Working with phpMyAdmin to Manage MySQL

366

 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

Zend

Configuration

Type

Server for

Information

Comments

IBM i IBM i

+

A separate backup of :

The RSTLICPGM automatically

-

/usr/local zendsvr+Date

identifies if it is a new installation

Stamp/etc/ and

or an upgrade.

/www/zendsvr+Date Stamp are created.

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.

367

 Zend Server 5 for IBM i Reference Manual

368

 Zend Server for IBM i Installation Guide

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

369

 Zend Server 5 for IBM i Reference Manual

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

370

 Zend Server for IBM i Installation Guide

Accessing PHP Open Source Applications A list of PHP applications which have been successfully run on IBM i.

371

 Zend Server 5 for IBM i Reference Manual

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.

372

 Zend Server for IBM i Installation Guide

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.

373

 Zend Server 5 for IBM i Reference Manual

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.

374

 Zend Server for IBM i Installation Guide

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

375

 Zend Server 5 for IBM i Reference Manual

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.

376

 Zend Server for IBM i Installation Guide

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)

377

 Zend Server 5 for IBM i Reference Manual

(C) COPYRIGHT IBM CORP. 1980, 2005.

378

 Zend Server for IBM i Installation Guide

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

379

 Zend Server 5 for IBM i Reference Manual

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

380

 Zend Server for IBM i Installation Guide

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

381

 Zend Server 5 for IBM i Reference Manual

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.

382

 Zend Server for IBM i Installation Guide

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

i5_COMD Service Port number . . 6079 Enable Prestart Jobs . . . . . . Restart i5_COMD if running . . .

*OFF *NO

Product library ZENDSVR Character value, *DFT, *JOBD *ON, *OFF, *AUTO *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.

383

 Zend Server 5 for IBM i Reference Manual

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

384

 Zend Server for IBM i Installation Guide

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

385

 Zend Server 5 for IBM i Reference Manual

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.

386

 Zend Server for IBM i Installation Guide

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-----Opt Job

Status Date

Time

Recovery Submit 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 ===>

387

 Zend Server 5 for IBM i Reference Manual

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.

388

 Zend Server for IBM i Installation Guide

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.

389

 Zend Server 5 for IBM i Reference Manual

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.

390

 Zend Server for IBM i Installation Guide

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

391

 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 [email protected].

392

 Zend Server Best Practices

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.

393

 Zend Server 5 for IBM i Reference Manual

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

Not recommended to turn off as it

If you are not

debugging tool

is great for development

going to debug

for developers

environments.

your code with

working with

In production when not debugging

the Debugger,

Zend Studio.

code

for example in a production environment, disabling this component may provide a slight performance gain

Optimizer+

Speeds up PHP

Disabling has a negative impact on

execution

performance.

through opcode caching and optimization. Guard Loader

Loads and runs

Required only if you are running

If you are not a

encoded PHP

PHP code that was encoded with

Zend Guard

scripts

Zend Guard.

user either

(Encoded with

remove this

Zend Guard)

component or do not install it

394

 Zend Server Best Practices

(it is an optional component). Data Cache

Cache data

If you are not using the Data Cache

items or output

API in your code for partial content caching.

Java Bridge

Calls Java

Required only If you call Java code

If you are not a

classes and

or objects from your PHP.

Java user either

code from PHP

remove this component or do not install it (it is an optional component).

Monitor

Identifies

Turn off temporarily, only for

performance

performance testing reasons. Not

issues

recommended to remove this component however it is best to configure accordingly see " Working with Monitoring"

Page Cache

A URL based

Always

If you decide

HTML output

If you are not using URL based

not to use this

cache for PHP

Caching.

component.

scripts

395

 Zend Server 5 for IBM i Reference Manual

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.

396

 Zend Server Best Practices

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

realpath_cache_size

Recommended

Zend Server for

Value

IBM i Default

256K

256K

Description

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_ALL

~E_NOTICE

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

397

 Zend Server 5 for IBM i Reference Manual

$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

Sets the magic_quotes state

This feature is deprecated as of PHP

for GPC (Get/Post/Cookie)

6.0.0.

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

".;/path/to/php/pear"

Specifies a list of directories

possible,

where the require(),

depending on

include(), fopen(), file(),

the application's

readfile() and

needs

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

398

30

30

This sets the maximum time

 Zend Server Best Practices

(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

399

 Zend Server 5 for IBM i Reference Manual

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.

400

 Zend Server Best Practices

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.

401

 Zend Server 5 for IBM i Reference Manual

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.

402

 Zend Server Best Practices

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.

403

 Zend Server 5 for IBM i Reference Manual

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

404

 Zend Server Best Practices

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 notallowed (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

405

 Zend Server 5 for IBM i Reference Manual

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

Description

Value 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

406

1

0

Decides whether PHP may expose the fact that it

 Zend Server Best Practices

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.

407

 Zend Server 5 for IBM i Reference Manual

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.

408

 Zend Server Best Practices

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: ƒ

/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);

409

 Zend Server 5 for IBM i Reference Manual

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

410

 Zend Server Best Practices

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"  Order allow,deny Allow from all AllowOverride all  

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".

411

 Zend Server 5 for IBM i Reference Manual

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 /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

412

 Zend Server Best Practices

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.

413

 Zend Server 5 for IBM i Reference Manual

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

414

 Zend Server Best Practices

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...

415

 Zend Server 5 for IBM i Reference Manual

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.

416

 Zend Server Best Practices

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.

417

 Zend Server 5 for IBM i Reference Manual

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.

418

 Zend Server Best Practices

ƒ

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.

419

 Zend Server 5 for IBM i Reference Manual

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.

420

 Zend Server Best Practices

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.

421

 Zend Server 5 for IBM i Reference Manual

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.

422

 Zend Server Best Practices

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.

423

 Zend Server 5 for IBM i Reference Manual

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

424

 Zend Server Best Practices

425

 Zend Server 5 for IBM i Reference Manual

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.

426

 Zend Server Best Practices

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.

427