Server Administration for Unix, Windows, OpenVMS, i5/os, and z/os

Transcription

1 Server Administration for Unix, Windows, OpenVMS, i5/os, and z/os Version 7 Release 6.1 DN

2 EDA, EDA/SQL, FIDEL, FOCCALC, FOCUS, FOCUS Fusion, FOCUS Vision, Hospital-Trac, Information Builders, the Information Builders logo, Parlay, PC/FOCUS, SmartMart, SmartMode, SNAPpack, TableTalk, WALDO, Web390, WebFOCUS and WorldMART are registered trademarks, and iway and iway Software are trademarks of Information Builders, Inc. Due to the nature of this material, this document refers to numerous hardware and software products by their trademarks. In most, if not all cases, these designations are claimed as trademarks or registered trademarks by their respective companies. It is not this publisher s intent to use any of these names generically. The reader is therefore cautioned to investigate all claimed trademark rights before using any of these names other than to refer to the product described. Copyright 2007, by Information Builders, Inc and iway Software. All rights reserved. Patent Pending. This manual, or parts thereof, may not be reproduced in any form without the written permission of Information Builders, Inc.

3 Preface This documentation describes how to use the Web Console to configure, operate, monitor, tune, and troubleshoot the iway Server. It is intended for server administrators, database administrators, and application developers. How This Manual Is Organized This manual includes the following chapters: Chapter Contents 1 Introduction Describes how to use the console and provides an overview of server configuration. 2 Server Security Describes security modes and their authentication process. 3 Configuring Adapters Provides general information on configuring adapters and outlines configuration options. 4 Configuring a Remote Server 5 Creating and Working With Applications Contains an item-by-item description of the Web Console Remote Servers page, with reference topics that provide information on server parameters. Describes how to work with Application Files, how to control the APP environment, and how to use APP methods to simplify the process of moving a user application from one platform to another. 6 Managing Metadata Discusses how to create a synonym using the Web Console. 7 Unicode Support Introduces the unicode standard and describes the WebFOCUS Reporting Server implementation. 8 Creating and Working With Procedures Explains how using procedures enables application logic to be written once and executed many times, and how the Procedures page enables the creation and testing of stored procedures. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os iii

4 Preface Chapter 9 Resource Analyzer and Resource Governor Overview 10 Configuring and Administering Resource Management From the Web Console 11 Resource Analyzer Reports 12 Setting Up DataMigrator 13 Running and Monitoring Your Server 14 Managing Listeners and Special Services Contents Describes two add-on tools Resource Analyzer and Resource Governor for monitoring and controlling data usage activity. This chapter applies only to users who have installed Resource Analyzer and Resource Governor. Describes how to set up the server to use Resource Analyzer and Resource Governor. This chapter applies only to users who have installed Resource Analyzer and Resource Governor. Describes the various reports you can run and view with Resource Analyzer. This chapter applies only to users who have installed Resource Analyzer and Resource Governor. Describes how to set up the DataMigrator Server. This chapter applies only to users who have installed a DataMigrator Server. Describes how to run, monitor, and tune your server. Describes how to manage listeners and special services. 15 Troubleshooting Explains how to perform problem analysis tasks. iv iway Software

5 Preface Documentation Conventions The following conventions apply throughout this manual: Convention THIS TYPEFACE or this typeface this typeface underscore this typeface this typeface Key + Key Description Denotes syntax that you must enter exactly as shown. Represents a placeholder (or variable) in syntax for a value that you or the system must supply. Indicates a default setting. Represents a placeholder (or variable), a cross-reference, or an important term. It may also indicate a button, menu item, or dialog box option you can click or select. Highlights a file name or command. Indicates keys that you must press simultaneously. { } Indicates two or three choices; type one of them, not the braces. [ ] Indicates a group of optional parameters. None are required, but you may select one of them. Type only the parameter in the brackets, not the brackets. Separates mutually exclusive choices in syntax. Type one of them, not the symbol.... Indicates that you can enter a parameter multiple times. Type only the parameter, not the ellipsis points ( ).... Indicates that there are (or could be) intervening or additional commands. Related Publications To view a current listing of our publications and to place an order, visit our World Wide Web site, You can also contact the Publications Order Department at (800) Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os v

6 Preface Customer Support Do you have questions about WebFOCUS? Call Information Builders Customer Support Service (CSS) at (800) or (212) Customer Support Consultants are available Monday through Friday between 8:00 a.m. and 8:00 p.m. EST to address all your WebFOCUS questions. Information Builders consultants can also give you general guidance regarding product capabilities and documentation. Please be ready to provide your six-digit site code (xxxx.xx) when you call. You can also access support services electronically, 24 hours a day, with InfoResponse Online. InfoResponse Online is accessible through our World Wide Web site, It connects you to the tracking system and known-problem database at the Information Builders support center. Registered users can open, update, and view the status of cases in the tracking system and read descriptions of reported software issues. New users can register immediately for this service. The technical support section of also provides usage techniques, diagnostic tips, and answers to frequently asked questions. To learn about the full range of available support services, ask your Information Builders representative about InfoResponse Online, or call (800) 969-INFO. Information You Should Have To help our consultants answer your questions most effectively, be ready to provide the following information when you call: Your six-digit site code (xxxx.xx). Your iway Software configuration: The iway Software version and release. The communications protocol (for example, TCP/IP or LU6.2), including vendor and release. The stored procedure (preferably with line numbers) or SQL statements being used in server access. The database server release level. The database name and release level. The Master File and Access File. vi iway Software

7 Preface The exact nature of the problem: Are the results or the format incorrect? Are the text or calculations missing or misplaced? The error message and return code, if applicable. Is this related to any other problem? Has the procedure or query ever worked in its present form? Has it been changed recently? How often does the problem occur? What release of the operating system are you using? Has it, your security system, communications protocol, or front-end software changed? Is this problem reproducible? If so, how? Have you tried to reproduce your problem in the simplest form possible? For example, if you are having problems joining two data sources, have you tried executing a query containing just the code to access one data source? Do you have a trace file? How is the problem affecting your business? Is it halting development or production? Do you just have questions about functionality or documentation? User Feedback In an effort to produce effective documentation, the Documentation Services staff welcomes your opinions regarding this manual. Please use the Reader Comments form at the end of this manual to relay suggestions for improving the publication or to alert us to corrections. You can also use the Documentation Feedback form on our Web site, Thank you, in advance, for your comments. iway Software Training and Professional Services Interested in training? Our Education Department offers a wide variety of training courses for iway Software and other Information Builders products. For information on course descriptions, locations, and dates, or to register for classes, visit our World Wide Web site ( or call (800) 969-INFO to speak to an Education Representative. Interested in technical assistance for your implementation? Our Professional Services department provides expert design, systems architecture, implementation, and project management services for all your business integration projects. For information, visit our World Wide Web site ( Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os vii

8 Preface viii iway Software

9 Contents 1. Introduction Using the Web Console Configuration Overview Preparing for Communications Configuration Communications Configuration Worksheets Running and Configuring the FOCUS Database Server (z/os Only) Server Profiles Profile Level Profile Commands Profile Command Formats Profile Commands Reference Server Security Security Modes Security OPSYS File Access Control Web Console Access Control With Security OPSYS Restricting Access to the Web Console in OPSYS Security Mode Security PTH Web Console Access Control With Security PTH Restricting Access to the Web Console in PTH Security Mode Security DBMS Web Console Access Control With Security DBMS Restricting Access to the Web Console in DBMS Security Mode Security LDAP Web Console Access Control With Security LDAP Restricting Access to the Web Console in LDAP Security Mode Security OFF Web Console Access Control With Security OFF Assigning Administration Levels Sending Customizable Login Messages Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os ix

10 Contents Working With User IDs and Passwords Setting an Anonymous User ID Viewing or Changing the Password Separator Character Login Password Expiration Warning Encrypting Passwords Stored in Configuration Files Logon Ticket Authorization on the Web Configuring Adapters Configuring an Adapter Changing the Adapter Configuration Configuring a Remote Server Creating and Working With Applications What is an Application? Managing Applications and Paths in the Web Console Working in the Application Configuration Pane Filtering Synonyms and Procedures Managing Application Files on the Web Console Managing Applications and Paths in the Data Management Console Application Commands Overview Search Path Management Commands APP PATH APP PREPENDPATH APP APPENDPATH APP MAP APP SHOWPATH Application and File Management Commands APP CREATE APP COPY APP COPYF APP MOVEF APP DELETE APP DELETEF APP RENAME APP RENAMEF Designating File Types for APP Commands Output Redirection Commands APP HOLD APP HOLDDATA APP HOLDMETA APP FI[LEDEF] x iway Software

11 Contents Reports and Help APP LIST APP QUERY APP HELP Restricting the Use of APP Commands Accessing Metadata and Procedures Search Rules Creation Rules for Procedure Files Locating Master Files and Procedures Accessing Existing Data Files Creation Rules for Data Files Data Set Names Allocating Temporary Files Temporary Space Allocation for UNIX and z/os UNIX System Services Temporary File Directory Structure for Non-PDS Deployment Managing Metadata Creating Synonyms Testing Synonyms Managing Synonyms Unicode Support Unicode and the WebFOCUS Reporting Server Accessing Unicode Data Selecting, Reformatting, and Manipulating Characters Sort Order Under Unicode Unicode PDF Output Creating and Working With Procedures Creating a Stored Procedure Editing a Stored Procedure Running a Stored Procedure Running a Stored Procedure Running a Procedure With Different Variables Prompting for Amper Variables in Live and Deferred Procedures Scheduling Requests for Deferred Execution Stress Testing a Procedure Running Impact Analysis Reports Running Standard Impact Analysis Reports Resource Analyzer and Resource Governor Overview Resource Analyzer and Resource Governor Add-on Tools Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os xi

12 Contents 10. Configuring and Administering Resource Management From the Web Console Configuring Resource Management Administering Resource Management From the Web Console Migrating the Resource Management Repository Requirements for Migrating the Resource Management Repository Migrating a Resource Management Repository on UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os After Completing the Migration Resource Analyzer Reports Reports Overview Resource Analyzer Reporting Resource Analyzer Report Options Selection Criteria Online Help Drilling Down With Reports Monitor Preference and Reports Alternate Reporting Output Finding the Report With the Information You Want General Reports Monitored Data Summary Monitored Procedure Summary Procedures Never Used Usage Analysis Reports Users Reports Procedures Reports Data Sources Reports Impact Analysis Report Change Impact for Column Report Performance Analysis Reports Procedure Benchmarks Report CPU Bound, I/O Bound, Large Answer Set Procedures Report Long-running Requests Report Large Volume Request Report Dormant Data Report Excessive Joins Report Repeated Aggregations Report Candidates for Column Index Report xii iway Software

13 Contents Network Analysis Reports Bandwidth by Database Report Resources by Connection Graph Reports Peak Transaction/Resource Periods and Cumulative Hourly Use Reports Query Volume vs. Resource Utilization Reports Custom Reports Setting Up DataMigrator DataMigrator Setup At a Glance Remote Server Setup At a Glance DataMigrator Setup Initiating Server Administration Tasks Authorizing DataMigrator Server Usage and Administration Managing Application Directories and Configuring the Application Path Configuring Data Adapters Creating Metadata Testing Sample Data and Process Flows Performing Server Administration Tasks From the Web Console Configuring DataMigrator Server Operations Upgrading DataMigrator From Version 4.3 or Running and Monitoring Your Server Configuring Workspace Manager Workspace Manager Configuration Privileges Configuring an Agent Service Configuring Deployment Modes Configuring for Deferred Management General Workspace Configuration Settings Editing Configuration Files Viewing and Editing Your License Number Fine-Tuning the Server Using JVM Tuning Options to Improve Memory Usage Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os xiii

14 Contents Monitoring Server Activity Monitoring Service Statistics Monitoring Data Services (Agents) Monitoring Sessions Monitoring Connections Monitoring Java Services Monitoring Special Services Monitoring Deferred Requests Monitoring Listeners Monitoring Web Sessions Migrating Your Server Managing Listeners and Special Services Using the Listeners and Special Services Configuration Panes Troubleshooting Viewing Version Information Analyzing Server Activity Analyzing FOCUS Database Server Activity Controlling the HLIPRINT Transaction Log Controlling HLIPRINT Output Tracing Server Activity Filtering and Configuring Traces Customizing Trace Filters for Data Services Enabling and Viewing DBMS Traces z/os-specific Troubleshooting for the Unified Server Server Traces and Saved Diagnostics on the Unified Server U4039 Abends on the Unified Server System Dumps on the Unified Server Freeing Data Sets Allocated to the Server on the Unified Server z/os-specific Troubleshooting for USS/HFS Deployment Correcting Orphaned Shared Memory Segments on z/os INSUFFICIENT AUTHORITY TO GETPSENT Messages on z/os Retrieving IBISNAP Output Recording and Reproducing User Actions Configuring Your Browser to Use a Proxy Server Troubleshooting the Console Workspace Manager Safe Mode xiv iway Software

15 Contents Server Processes Server Work Space Manager Daemon Deferred Requests Special Services Daemon Server Log Daemon Server Check Up Daemon HTTP Listener Daemon TCP Listener Daemon FDS Special Services Daemon Java Services Daemon Agent Daemons Gathering Diagnostic Information for Customer Support Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os xv

16 Contents xvi iway Software

17 1 Introduction The iway Web Console enables you to configure, operate, monitor, tune, and troubleshoot the server environment from a single, easy-to-use interface. Topics: Using the Web Console Configuration Overview Preparing for Communications Configuration Running and Configuring the FOCUS Database Server (z/os Only) Server Profiles Profile Commands

18 Using the Web Console Using the Web Console The Web Console enables you to remotely view and manage the server environment. From a single, easy-to-use interface, you can: Select, add, and configure data adapters. Create and manage adapter metadata. Configure remote servers. Configure, edit, and run applications and deferred query processing. Configure communications and special services. Operate, monitor, tune, and troubleshoot your server. Edit configuration files. Migrate from a previous server release. Procedure: How to Open the Web Console To open the Web Console: 1. Start the server. 2. Type the following URL in the address space of the Web browser where: ip_address Is the IP address of the machine on which the server is running. http_service Is the value for HTTP Service entered during the server configuration procedure. If you have trouble contacting the server, see Troubleshooting the ConsoleTroubleshooting the Console in Chapter 15, Troubleshooting. 3. If you are running your server with security on, type the user name and password used to access the operating system. Logging on with the server administrator ID activates the management features and diagnostic pages. Non-administrator IDs can view only status and statistics, and run the test tools. The non-administrator pages are similar to the administrator pages, but they hide the features required to manage the server. The administrator versions of the pages appear in this documentation. 1-2 iway Software

19 Introduction The Web Console Home Page opens. The menu bar on the left provides access to the different features of the Web Console. 4. Select an option from the menu bar to access the corresponding console page. For tasks that display information or require no additional navigation, the console displays corresponding information in the right pane. For tasks that require additional, task-centered navigation, the console opens a new menu bar or window. Use the new window's navigation pane on the left to access the corresponding information in the right pane. The console offers online help with two kinds of links to appropriate sections of this documentation: Click Help on the menu bar and choose Contents and Search to display the full Web Console help system. Click the? icon, when available, to display contextual help specific to the associated item. Configuration Overview The characteristics of an individual server are determined by a set of configuration files. These configuration files define the protocols, services, and data sources supported by the server. In the UNIX, z/os USS, Windows, OpenVMS, and i5/os environments, these files are maintained in directories designated by the environment variable EDACONF. The initial installation procedure creates an installation instance, represented in manuals as the logical name EDAHOME, and one default configuration instance, known as EDACONF. After you successfully install the server, you can configure a default configuration instance to create an operational instance, or create an additional one at your site. An operational instance of the server is one that is configured to support specific protocols, services, and access to data sources. You must run the Installation/Configuration Utility for each new instance of the server that you want to configure, and then use the Web Console to configure all necessary functionality. To configure a server instance, use the Web Console to: 1. Select and configure data adapters. 2. Optionally, configure remote servers. 3. Configure communications nodes and protocols. 4. Optionally, set parameters for deferred query processing. If necessary, you may edit configuration files. Some configuration errors can make the server start in a limited mode called safe mode, in which the Web Console is still operational to enable you to correct the errors. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-3

20 Preparing for Communications Configuration Preparing for Communications Configuration In this section: Communications Configuration Worksheets How to: Prepare to Configure TCP/IP or HTTP Prepare to Configure SNA (LU6.2) Configure PIPE Communications Depending on your environment and network configuration, inter-node communications may consist of TCP/IP, HTTP, SNA (LU6.2), or PIPE communications protocols. Inter-node communications are configured through menu bar Workspace options: Workspace, Remote Servers and Workspace, Configuration, followed by Listeners on the navigation pane. Procedure: How to Prepare to Configure TCP/IP or HTTP To prepare to configure for TCP/IP or HTTP: 1. Verify that TCP/IP is installed, configured, and running on both the server and client platforms. 2. List any TCP service names/port numbers and IP addresses you are using for inbound server and outbound client or subserver access. This list is used during server configuration. Procedure: How to Prepare to Configure SNA (LU6.2) To prepare to configure for SNA (LU6.2): 1. Verify that SNA (System Network Architecture) is installed, configured, and running on both the server and client platforms. 2. Ensure that all installation prerequisites are met. SNA (LU6.2) is not supported on all platforms. For more information, see the Server Installation manual. 3. List all SNA profiles and parameters you are using for inbound server and outbound subserver access. This list is used during server configuration. 1-4 iway Software

21 Introduction 4. Create an SNA configuration for intra-node communications. Depending on your platform, you create some or all of the following SNA (LU6.2) definitions for the server: Local LU Name. Partner LU and Partner LU Alias. Partner LU and Partner LU Alias for local loop back. Mode Name. The default is PARALLEL. Do not change this parameter unless you are instructed to do so by the site administrator. TP Name. The default for a z/os subserver is MVSSRVR. Do not change this parameter unless you are instructed to do so by the site administrator. Procedure: How to Configure PIPE Communications No preparation is required for PIPE communications. The client and the server must reside on the same physical machine. Communications Configuration Worksheets Complete one or several of the worksheets, depending on the: Example: Configuring for Inbound Communications Using TCP/IP Configuring for Inbound Communications Using SNA (LU6.2) Configuring for Outbound Communications Using TCP/IP Configuring for Outbound Communications Using SNA (LU6.2) Communications protocol. Inbound or outbound communications. MVS Remote Server (subserver) access. In the examples, the terms inbound and outbound are used relative to the server; inbound refers to communications from the client, and outbound refers to communications to remote subservers. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-5

22 Preparing for Communications Configuration Example: Configuring for Inbound Communications Using TCP/IP To configure for inbound communications using TCP/IP, complete this worksheet. The port should be the first of up to five consecutive ports that the server uses. Prompt Default Supply Your Value Here Inbound TCP/IP Port Number. Depends on server type. The Full-Function Server default value is Example: Configuring for Inbound Communications Using SNA (LU6.2) To configure for inbound communications using SNA (LU6.2), complete this worksheet. Prompt Default Supply Your Value Here TP NAME for server. LOCAL LU NAME for local test client test tool (RDAAPP). PARTNER LU NAME for local client test tool (RDAAPP). MODE NAME for local test client test tool (RDAAPP). EDATP None None None Example: Configuring for Outbound Communications Using TCP/IP To configure for outbound communications using TCP/IP (Hub Server and Full-Function Server with Hub Services only), complete this worksheet. Supply Your Subserver Values Here Prompt Default Sub1 Sub2 Sub3 Outbound host name or IP address. Outbound TCP/IP service name or port number. Local host name iway Software

23 Introduction Supply Your Subserver Values Here Prompt Default Sub1 Sub2 Sub3 User ID and password for connecting to the server on this port. Is server located on MVS? If Yes, type the MVS service name. Leave blank for trusted node access No Example: Configuring for Outbound Communications Using SNA (LU6.2) To configure for outbound communications using SNA (LU6.2) (Hub Server and Full-Function Server with Hub Services only), complete this worksheet. Prompt Default Supply Your Value Here LOCAL LU NAME used by the server. PARTNER LU NAME for the Remote Server. TP NAME for the Remote Server. PARTNER MODE NAME used by the client test tool (RDAAPP). User ID and password for connecting to the server on this port. Located on MVS (Yes or No)? If Yes, type the MVS service name. None None None Leave blank for trusted node access. No Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-7

24 Running and Configuring the FOCUS Database Server (z/os Only) Running and Configuring the FOCUS Database Server (z/os Only) Example: Using the Integrated FOCUS Database Server With a DYNAM Command Using the Integrated FOCUS Database Server With a JCL Statement Using the Integrated FOCUS Database Server With NOALIAS Using the Legacy FOCUS Database Server (Separated Batch Job) The iway Server for z/os comes with its own FOCUS Database Server, also called a Sink Machine. You can either use this integrated FOCUS Database Server or keep FOCUS files on the legacy FOCUS Database Server, which runs as a separate batch job. If you choose to use the integrated FOCUS Database Server, the implementation of the USE command is unchanged. The FOCSBS value is a node name in the server's communications configuration file, odin.cfg. Node FOCSU01 identifies the integrated FOCUS Database Server, and cannot be used for any other purpose. Important: A single file cannot be on both a legacy and an integrated FOCUS Database Server. You must select one or the other to manage access, or you will encounter queue conflicts. Example: Using the Integrated FOCUS Database Server With a DYNAM Command Using the Web Console, edit the suprof.prf profile ALLOC allocations for each file to be managed. For example, add following sample command to suprof.prf: DYNAM ALLOC FI CAR DA <dsname> SHR REU The following sample USE command enables the FOCUS Database Server to control access to the CAR data source: USE CAR ON FOCSU01 END 1-8 iway Software

25 Introduction Example: Example: Example: Using the Integrated FOCUS Database Server With a JCL Statement ISTART JCL allocation Add JCL statements for the FOCUS files to be managed, for example: //CAR DD DISP=SHR,DSN=<dsname> The following sample USE command enables the FOCUS Database Server to control access to the CAR data source: USE CAR ON FOCSU01 END Using the Integrated FOCUS Database Server With NOALIAS The DYNAM ALLOC command with the option NOALIAS is equivalent to a JCL allocation on ISTART JCL. It makes a global server allocation available to the FOCUS Database Server. For example, use the following DYNAM ALLOC command in edasprof.prf or a user procedure (focexec): DYNAM ALLOC FI CAR DA <dsname> SHR REU NOALIAS The following sample USE command enables the FOCUS Database Server to control access to the CAR data source: USE CAR ON FOCSU01 END Using the Legacy FOCUS Database Server (Separated Batch Job) The following sample code identifies a legacy FOCUS Database Server via the odin.cfg node block FOCSBS: USE CAR ON FOCSBS END This sample node block resides in odin.cfg and can be constructed using the Web Console: NODE=FOCSBS <===== USS server (odin.cfg file) BEGIN PROTOCOL=SBS CLASS=SUCLIENT PORT=X.Y.Z <====== communications dataset END Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-9

26 Server Profiles Server Profiles iway creates a standard global profile, edasprof.prf, during installation. You can customize the global profile for all users, and, optionally, create additional profiles to customize the server environment for a group of users or an individual user.***this section reflects some 7.1 edits*** A profile can include almost any command that a client application can send to the server, however, profiles are used most frequently for application set up commands such as SETs, search path set up, and DBMS connection information, which may vary by adapter. For information about the syntax for commands typically used in profiles, see Profile Commands on page For a description of the profile commands that are available for a particular adapter, go to Configuring a Data Adapter, then choose an adapter from the list in the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual for the particular adapter. In the adapter chapter, look for topics on customization and optimization. Two key aspects of profile customization are level and associated search order. The server processes all profiles found in the search order. If it finds duplicate settings or commands, the last setting or command processed will be active for the connection. When you create a profile, take into account that the more processing performed by the profile, the more time it takes for an application to connect to the server. An exception is the case of pooled deployment, in which only one profile is processed upon server agent initial startup or refresh iway Software

27 Profile Level Introduction The server supports various levels of profiles to provide flexibility in designing and running production applications. The order in which the following profiles are listed correlates with the search order in which they are processed by the server when multiple profiles exist. Global profile The first level of profile, the global profile, is a startup file automatically created during installation and configuration of the server. It contains default environment settings required for the correct operation of the server. The global profile remains in effect throughout a user session. You can modify the global profile default settings. You can also add any commands or code that all connected users require before application processing begins. Characteristic Name Location Override Sequence in search order Scope Description edasprof.prf UNIX: $EDACONF/etc directory Windows: $EDACONF\etc directory i5/os: IFS $EDACONF/etc directory OpenVMS: EDACONF [.ETC] directory***expecting changes from Terry*** Set the environment variable EDASPROF to point to an alternate location of edasprof.prf (you cannot rename edasprof.prf). First Applies to all connected users. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-11

28 Server Profiles Service profile A service profile specifies settings for the server environment, but the settings in this level of profile apply only to users associated with a specific service. When a user connects to the server, the service profile settings are applied and remain in effect throughout the user session. A service profile may contain settings that are the same as those in a global profile. You can specify a service profile in the Web Console by choosing Workspace, Configuration from the menu bar, and Service from the navigation pane. You can create a service profile using the Web Console Workspace, Configuration option. Expand Configuration Files in the navigation pane and choosing Server Profiles. You can also use any standard system editor. If you use an editor, create the service profile in the correct location. Characteristic Name Location Override Sequence in search order Scope Description name.fex Follows the normal search path for procedures (focexecs). None Second Applies to all users of the same service iway Software

29 Introduction Group profile A group profile specifies settings for the server environment, but the settings in this level of profile apply only to users associated with a specific security group. When a user connects to the server, the group profile settings are applied and remain in effect throughout the user session. This level of profile applies only if security is ON. A group profile may contain settings that are the same as those in a global profile. You can manually create a group profile at any time using any operating system editor. On z/os UNIX System Services, a user can be a member of many security groups but iway uses only one group for profile processing. For the group profile, iway uses the group ID placed in the security control block (ACEE) by the security package established upon successful user ID validation. For the Resource Access Control Facility (RACF), iway uses the default group that is returned. You can create a group profile using any standard system editor. Create the group profile in the correct location. Characteristic Name Location Override Sequence in search order Scope Description group_name.prf UNIX: base_directory_name/ibi/profiles Windows: base_directory_name\ibi\profiles i5/os: IFS base_directory_name/ibi/profiles directory OpenVMS: base_directory_name [.IBI.PROFILES] directory***reflects revisions from Terry.*** Set the edaserve.cfg keyword edaprfu to point to an alternate location of group_name.prf. Third Applies to all users of the same security group. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-13

30 Server Profiles User profile A user profile specifies settings for the server environment, but the settings in this level of profile apply only to a specific user ID. When a user connects to the server, the user profile settings are applied and remain in effect throughout the user session. A user profile may contain settings that are the same as those in a global profile. You can create a user profile at any time using the following options: Choose Workspace, then Configuration on the Web Console menu bar, then expand Configuration Files in the navigation pane and choose User Profiles. You can also use any standard system editor. If you use an editor, create the user profile in the correct location. Characteristic Name Location Override Sequence in search order Scope Description user_id.prf UNIX: base_directory_name/ibi/profiles Windows: base_directory_name\ibi\profiles i5/os: IFS base_directory_name/ibi/profiles directory OpenVMS: base_directory_name [.IBI.PROFILES] directory***reflects revisions from Terry.*** Set the edaserve.cfg keyword edaprfu to point to an alternate location of user_id.prf. Fourth Applies to a specific user iway Software

31 Introduction Profile Commands In this section: Profile Command Formats Profile Commands Reference The following topics describe commands that you can include in any of the supported server profiles. These commands affect the behavior of the server for the duration of the connected session. You can code additional commands, such as data access commands, in any of the supported server profiles. For more information, see specific data adapter topics in the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual. For FOCUS Table Services, the server profiles play the same role as the FOCUS profile. Profile Command Formats How to: Use a Direct SET Command Use an SQL Engine SET Command Use an SQL Translator Command Example: Using a Direct SET Command Using an SQL Engine SET Command Using an SQL Translator Command Each server command takes one of three possible formats. The syntax and an example of these formats follow. Ensure that you use the correct format for any server command you use. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-15

32 Profile Commands Syntax: How to Use a Direct SET Command To use a direct SET command SET command=value where: command Is the server command. value Is the value selected from the available choices. Example: Using a Direct SET Command SET SQLENGINE=DB2 Syntax: How to Use an SQL Engine SET Command To use the SQL Engine SET command ENGINE [sqlengine] SET command value where: sqlengine Is the data source. You can omit this parameter value if you previously issued the SET SQLENGINE command. command value Is the server command. Is the value selected from the available choices. Example: Using an SQL Engine SET Command ENGINE SQLORA SET OWNERID EDAUSER 1-16 iway Software

33 Introduction Syntax: How to Use an SQL Translator Command To use an SQL Translator command SQL SET command=value END where: command Is the SQL Translator command. value Is the value selected from the available choices. Example: Using an SQL Translator Command SQL SET APT=OFF END Profile Commands Reference The Server Profile Commands document provides the syntax for the profile commands. Individual data adapter topics include a description of the applicable profile commands for that data adapter. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 1-17

34 Profile Commands 1-18 iway Software

35 2 Server Security This section describes the security modes in which a server can run and the authentication process for each mode. It also describes how an administrator enables a particular security mode. Topics: Security Modes Security OPSYS Security PTH Security DBMS Security LDAP Security OFF Assigning Administration Levels Sending Customizable Login Messages Working With User IDs and Passwords Logon Ticket Authorization on the Web

36 Security Modes Security Modes Reference: Platform-Specific Methods for Setting EDAEXTSEC The available security modes are: Security OPSYS: Each connecting user ID must be defined in the operating system on which the server is running. The server uses operating system services to authenticate connecting users, impersonate them, and ensure access control to resources such as system files and DBMS objects. Access to the Web Console's administrative functions is protected by user authentication at the operating system level. Control of data resources can be accomplished by creating different profiles. OPSYS security supports user profiles on all platforms; profiles for groups are supported on all platforms except Windows. The server detects whether the conditions for operating system authentication are in effect and, if they are, it automatically runs with this security mode. If the conditions are not met and no other security mode has been configured, the server automatically runs with security off. Security PTH: Access to the Web Console is controlled by authentication against the user list defined in the server configuration file, admin.cfg. No authentication occurs for non-web Console access to the server. Control of data resources can be accomplished by creating different profiles. PTH security mode supports profiles for users and groups on all platforms. Security DBMS: Access to the Web Console and data resources is controlled by authentication against a database s list of user IDs. Control of data resources can be accomplished by creating different profiles. DBMS security supports profiles for users on all platforms; profiles for groups are not supported. Security LDAP (Lightweight Directory Access Protocol): Access to the Web Console and data resources is controlled by authentication through the established directory. This mode applies to a server running under Windows, UNIX, or USS. Control of the data resources can be accomplished by creating different profiles. LDAP security supports profiles for users and groups on all platforms. Security OFF: User IDs and passwords are not required since the connection is not validated when security is OFF. (User IDs and passwords may, however, be used in profiles for other purposes.) Access to the Web Console is not protected. 2-2 iway Software

37 Server Security After the server is initially installed, it will start in one of two default security modes---off or OPSYS---as described in the Server Installation manual. To change this default behavior, you can use the Web Console to select another security mode. The EDAEXTSEC variable is then used to permanently maintain the selected security mode. See Platform-Specific Methods for Setting EDAEXTSEC on page 2-3 for details on how to set the EDAEXTSEC variable on each platform. Reference: Platform-Specific Methods for Setting EDAEXTSEC Platform Start Method Actions Windows Start Menu Under the main software folder for the server, select Start with Alternate Security Modes, Start Security, then choose a security_mode. The options are OPSYS, PTH, DBMS, LDAP, or OFF. As a Service under a local system account Set the system environment variable EDAEXTSEC, under My Computer, Properties, Advanced tab, to one of the following values: OPSYS, PTH, DBMS, LDAP, or OFF. Restart Windows to initialize. As a Service under the current account Set the system environment variable EDAEXTSEC, under My Computer, Properties, Advanced tab, to one of the following values: OPSYS, PTH, DBMS, LDAP, or OFF. UNIX Command prompt or Script that calls edastart Restart Windows to initialize. Export the variable setting in the edastart shell script, or before any calls to the shell script, as follows export EDAEXTSEC=security_mode where: security_mode Is one of the following: OPSYS, PTH, DBMS, LDAP, or OFF. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-3

38 Security Modes Platform Start Method Actions z/os Unified Server i5/os OpenVMS JCL QSH command prompt or QSH script that calls edastart CALL {lib}/tscom300 or CL that calls TSCOM300 or CL that calls QSH, which, in turn, calls the edastart shell script Command prompt or DCL script that calls edastart Place the variable in the EDAENV allocation of the IRUNJCL member of the configuration library EDAEXTSEC=security_mode where: security_mode Is one of the following: OPSYS, PTH, DBMS, LDAP, or OFF. Export the variable in the edastart shell script, or before any calls to the shell script, as follows export EDAEXTSEC=security_mode where: security_mode Is one of the following: OPSYS, PTH, DBMS, LDAP, or OFF. Before the call to TSCOM300, add the following ADDENVVAR ENVVAR(EDAEXTSEC) VALUE(security_mode) where: security_mode Is one of the following: OPSYS, PTH, DBMS, LDAP, or OFF. Before calling edastart.com or in edastart.com, add the following DEFINE EDAEXTSEC security_mode where: security_mode Is one of the following: OPSYS, PTH, DBMS, LDAP, or OFF. You can also define the logical EDAEXTSEC in the EDAENV.COM file. 2-4 iway Software

39 Server Security Security OPSYS In this section: File Access Control Web Console Access Control With Security OPSYS Restricting Access to the Web Console in OPSYS Security Mode How to: Configure OPSYS Security Mode Reference: Consequences for Files Under the EDAHOME/EDACONF Hierarchy Consequences for Files Under the APPROOT Hierarchy Consequences for Files Under the EDATEMP Hierarchy When security is set to OPSYS, the user credentials from the client connection are authenticated by the native security system of the operating system. The server then allocates a data access agent that impersonates the user so that access to files or other objects is controlled by the native system. Profiles for operating system users are supported on all platforms; profiles for groups are supported on all platforms except Windows. The server will automatically run in security OPSYS mode if no other security mode has been configured and the server process has been granted sufficient privileges. If the server process does not have sufficient privileges for operating system authentication, and no other security mode has been configured, the server runs with security OFF. Details about OPSYS security requirements are provided in the Server Installation manual, where specific sections are provided for each platform. Refer to this manual for installation instructions and platform-specific setup steps. The following is a summary of the OPSYS requirements: On UNIX, the startup tscom300 executable must have root setuid authority. On Windows, the server must be started as a service under SYSTEM account (Administrators Group authority) or as a user ID with Windows Administrator authority. On Windows, the Server Administrator password is required for this security mode. If the password is not provided in the configuration, the server starts in safe mode and displays a message to that effect. Multiple administrators are allowed. For information on creating server administrators, see Assigning Administration Levels on page Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-5

40 Security OPSYS On z/os, the MVS load library must be APF-authorized and, for HFS deployment, certain HFS executables must be given +a authorization. On i5/os, the ownership of certain library files must be changed to have QSECOFR ownership, and, therefore, authority. On OpenVMS, the account starting the server must have a specific set of privileges to have proper authorities. Note that some system specific settings in the edaserve.cfg file are provided to allow further adjustments of the authentication mechanism. Those relevant for some UNIX systems are: require_logon_privilege (AIX only---to allow no login IDs to access the server); security_sia (True64 only---use SIA security subsystem); and update_security_db (AIX and HP-UX only---to register failed login attempts). For Windows systems, the logon_method setting (for interactive, network, or batch) is relevant to explicit connections. Procedure: How to Configure OPSYS Security Mode This procedure assumes that the server is already running in non-opdys security mode. 1. Access the Web Console with a server administrator user ID. 2. From the Web Console menu bar, select Workspace, Access Control. The Access Control pane opens. The security mode to which the server is currently set is displayed in the Security Mode drop-down list. 3. Select OPSYS from the Security Mode drop-down list. Supply the Server Administrator user ID and password. Alternatively, you can enter a new user ID and password; it will be added to the admin.cfg file as a Server Administrator. 4. Click the Apply and Stop button. 5. Set the EDAEXTSEC variable according to the instructions in Platform-Specific Methods for Setting EDAEXTSEC on page If the server is not running, start it using the instructions for your platform. The server will start in OPSYS security mode. 7. Examine the edaprint.log file. If it indicates errors, stop the server, correct the errors, then start it with security OPSYS. 8. Restart your browser and connect to the Web Console. When prompted, enter a valid operating system user ID and password. 2-6 iway Software

41 Server Security If you wish to add other users as Server Administrators, Server Operators, Application Administrators, or Basic Users, first connect as a Server Administrator. Then follow the instructions in Assigning Administration Levels on page File Access Control Impersonation of a user means that access to files is controlled by the operating system security features in the native file systems. Files are protected according to the permissions and access control lists set for the impersonated user. The main file areas within a configuration are organized into four locations: EDAHOME (the software installation structure). EDACONF (the specific software configuration structure). APPROOT (the file structure for holding application-related programming files). EDATEMP (the runtime user area for server processes, which is normally located under the EDACONF area). Permissions for new files depend on how the server is installed and started. Reference: Consequences for Files Under the EDAHOME/EDACONF Hierarchy Consequences for Files Under the APPROOT Hierarchy Consequences for Files Under the EDATEMP Hierarchy On UNIX, z/os (HFS deployment), and i5/os, the permission mask setting of the process (umask) that started the server is inherited down to the creation of each subdirectory or file, and thus defines the permissions used for object creation. On z/os (PDS deployment), the rules (permissions) are set but the security package (RACF, ACD/2, or Top Secret). On OpenVMS, the permission mask of the process (SET PROTECTION= /DEFAULT) that started the server is inherited down to the creation of each subdirectory or file, and thus defines the permissions used for object creation. On Windows, the permissions are inherited down from directory to subdirectory, and the permissions for any object created are taken from its parent directory. So unless specific permissions are applied at any level, default permissions will depend on where the server was installed. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-7

42 Security OPSYS Reference: Consequences for Files Under the EDAHOME/EDACONF Hierarchy When defining the permissions under a specific security policy, care must be taken to ensure that all users who are expected to use the server have Read/Execute access to files under the hierarchies. Effectively, group writeable permissions should be used for server administrators that share common resources, while non- shared resources should have specific permissions. Reference: Consequences for Files Under the APPROOT Hierarchy Care must be taken when defining default permissions for application administrators who will create files under the Web Console that need to be accessed by regular users. When application files are written under the Web Console, they are created according to the rules of ownership and default permissions applicable to the user who logged on to the Web Console. Thus, application developers must share a common default group if they are to work on a shared project. Reference: Consequences for Files Under the EDATEMP Hierarchy In a server that runs with security OPSYS, special conditions apply to the edatemp subdirectory and its contents. The basic principle is that agent subdirectories under edatemp are owned at any given moment by the user that the agent is impersonating. In private mode, this means that once a user connects to an agent, he is explicitly given ownership of his agent subdirectory, regardless of which user the agent impersonated during previous connections. This ownership and the inherited permissions thus define how other users can access the connected user's temporary files, if at all. On UNIX, z/os (HFS deployment), and i5/os, the edatemp subdirectory itself is an exception because it is set up similarly to the /tmp directory: while it allows any user to add files and directories underneath, only the creator of a file can later rename or delete it. Files directly under edatemp (for example, traces) and listener subdirectories are owned by the super user (root, QSECOFR). On z/os (PDF deployment), all temporary files created by a user are based on the rules in the Security package. On Windows, the permissions of the parent directory of edatemp (usually EDACONF), which were applied when the server was installed, are inherited when edatemp and then the agent subdirectories are created, defining the kind of access other users have to an agent subdirectory and its contents. 2-8 iway Software

43 Web Console Access Control With Security OPSYS Server Security Access to the Web Console is protected by user authentication at the operating system level. Authenticated users that also match a user name listed in admin.cfg are permitted to perform certain control operations on the Web Console, depending on their definitions in admin.cfg as server operator, application administrator, or basic user. Within a given user class definition, additional restrictions may be applied. As a result, available Web Console features may vary from site to site or between server configurations at a site. Alternatively, if a server administrator has established an Anonymous ID, it can be used to access the Web Console as a basic user, without an explicitly entered ID. For details, see Setting an Anonymous User ID on page Restricting Access to the Web Console in OPSYS Security Mode How to: Restrict Access to the Web Console in OPSYS Security Mode By default, a user who starts the Web Console and is not identified in the admin.cfg file as belonging to one the three administration levels (Server Administrator, Application Administrator, Server Operator) is given access to Web Console functions based on the default_admin_level setting. Procedure: How to Restrict Access to the Web Console in OPSYS Security Mode 1. Login to the server that is running in OPSYS security mode. 2. From the Web Console menu bar, select Workspace, then Access Control. 3. Click Others in the navigation pane. The Access Control pane opens. 4. The default_admin_level setting defines the administration level given to a Web Console user if no entry is found in the admin.cfg file for that user. The options are: Server Administrator Application Administrator Basic User None. (No access allowed.) Select the value you want to apply. If only users defined in the admin.cfg are to be allowed access, select None. 5. Click Apply and Restart. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-9

44 Security PTH Security PTH Note: If a server administrator has established an Anonymous ID, it can be used to access the Web Console without an explicitly entered ID. For details, see Setting an Anonymous User ID on page 2-38 and Impact of Anonymous User IDs on page In this section: Web Console Access Control With Security PTH Restricting Access to the Web Console in PTH Security Mode How to: Configure PTH Security Mode PTH security mode only controls access to the Web Console. In this security mode, there is no impersonation by data agents or authentication of a non-web Console connected user. From the operating system point of view, all server processes run as a single user ID, and access to the Web Console is controlled by authenticating names against those defined in the admin.cfg file. You must configure the Server Administrator password before starting a server in this security mode, either by providing it at installation time or by configuring it in the Web Console. For details, see Assigning Administration Levels on page PTH security mode supports profiles for users and groups on all platforms. Procedure: How to Configure PTH Security Mode This procedure assumes that the server is already running. 1. Access the Web Console with a server administrator user ID. 2. From the Web Console menu bar, select Workspace, Access Control. The Access Control pane opens. The security mode to which the server is currently set is displayed in the Security Mode drop-down list. 3. Select PTH from the Security Mode drop-down list and supply a Server Administrator user ID and password. Alternatively, you can enter a new user ID and password; it will be added to the admin.cfg file as a Server Administrator iway Software

45 Server Security 4. If the server was started with security mode OPSYS, click the Apply and Stop button; otherwise, click the Apply and Restart button. If you click Apply and Stop, the server stops; proceed with Step 5. If you click Apply and Restart button, the server restarts in security mode PTH, but the next time the server is restarted (other than from the security mode pane), the security mode reverts to whatever it was at the start of this procedure. This is called a dynamic restart. A message to this affect is displayed on the screen. To preserve the security mode PTH, proceed with Step Set the EDAEXTSEC variable according to the instructions in Platform-Specific Methods for Setting EDAEXTSEC on page If the server is not running, start it using the instructions for your platform. The server will start in PTH security mode. 7. Examine the edaprint.log file. If it indicates errors, stop the server, then start it with security OFF to correct the errors. 8. Restart your browser and connect to the Web Console. When prompted, enter a valid PTH user ID and password. If you wish to add other PTH users, first connect as a PTH user defined as server administrator. Then follow the instructions in Assigning Administration Levels on page Note: A common problem when switching from OPSYS to PTH is the existence of files in EDATEMP that cannot be removed due to insufficient privileges. To handle this problem, use edastart -cleardir (or member ICLRDIR on the z/os platform) in EDAEXTSEC=OPSYS mode to clear the directory before switching. Web Console Access Control With Security PTH Access to the Web Console is protected by user authentication against the admin.cfg file. Authenticated users are permitted to perform certain control operations on the Web Console, depending on their definitions in admin.cfg as Server Administrators, Application Administrator, Server Operator, or Basic User. Within a given administration level, additional Administration privileges may be applied. As a result, available Web Console features may vary from site to site or between server configurations at a site. For details, see Administration Levels and Web Console Privileges on page Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-11

46 Security PTH Restricting Access to the Web Console in PTH Security Mode How to: Restrict Access to the Web Console in PTH Security Mode By default, a user who starts the Web Console and is not identified in the admin.cfg file as belonging to one the three administration levels (Server Administrator, Application Administrator, Server Operator) is given access to Web Console functions based on the combination of authenicate_all_pthuser and default_admin_level settings. Procedure: How to Restrict Access to the Web Console in PTH Security Mode b Console in PTH Security Mode 1. Login to the server that is running in PTH security mode. 2. From the Web Console menu bar, select Workspace, then Access Control. 3. Click Others in the navigation pane. The Access Control pane opens. 4. The authenticate_all_pthuser option defines whether the server will authenticate all connections to the Web Console. By default, this option is set to n. If you retain this setting, users who are not listed in the admin.cfg file are not authenticated and are given access to the Web Console with the administration level defined in the default_admin_level setting, where the options are: Server Administrator Application Administrator Basic User None. (No access allowed.) If you click the y radio button, all users are authenticated, and only those whose IDs are listed in the admin.cfg file are granted access to the Web Console. 5. Click Apply and Restart. Note: If a server administrator has established an Anonymous ID, it can be used to access the Web Console without an explicitly entered ID. For details, see Setting an Anonymous User ID on page 2-38 and Impact of Anonymous User IDs on page iway Software

47 Server Security Security DBMS In this section: Web Console Access Control With Security DBMS Restricting Access to the Web Console in DBMS Security Mode How to: Configure DBMS Security Mode Reference: Usage Notes for DBMS Security Password Passthru and Security DBMS In this security mode, there is no impersonation by data agents, but connection credentials are authenticated against a configured DBMS. This technique is called password passthru, as user IDs and passwords supplied by the client are passed to the DBMS for authentication. DBMS security mode supports profiles for users on all platforms; profiles for groups are not supported. Procedure: How to Configure DBMS Security Mode This procedure assumes that the server is already running. 1. Access the Web Console with a Server Administrator user ID. 2. From the Adapter pane, configure a DBMS adapter and connection that will authenticate the user ID and password. 3. Select the Password Passthru security option on the Adapter configuration pane. Note that the Test button, which appears next to the Configure button, will not work until your restart the server with Security DBMS in step 5. Do not restart the server at this point. 4. From the Web Console menu bar, select Workspace, Access Control. The Access Control pane opens. The security mode to which the server is currently set is displayed in the Security Mode drop-down list. 5. In the Security Mode drop-down list, select DBMS. 6. Select a security_dbms from the drop-down list. This option identifies the database engine used to authenticate incoming requests. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-13

48 Security DBMS 7. Select a security_connection from the drop-down list. This option identifies the database connection used to authenticate incoming requests. 8. Choose a Server Administrator from the drop-down list or provide a new user ID. If you enter a new user ID, it will be added to the admin.cfg file as a Server Administrator, with no password. 9. At this point, it is a good idea to click the Test button to make sure the DBMS connection is working. You will be prompted for a password for the selected user ID. Click Continue. The DBMS will authenticate this ID. If it is a valid DBMS ID, a message will be returned indicating that authentication was successful. If the ID is not a valid DBMS ID, the DBMS will return messages indicating that authentication was not successful. 10. If the server was started with security mode OPSYS, click the Apply and Stop button; otherwise, click the Apply and Restart button. If you click Apply and Stop, the server stops; proceed with Step 11. If you click Apply and Restart button, the server restarts in security mode DBMS, but the next time the server is restarted (other than from the security mode pane), the security mode reverts to whatever it was at the start of this procedure. This is called a dynamic restart. A message to this affect is displayed on the screen. To preserve the security mode DBMS, proceed with Step Set the EDAEXTSEC variable as described in Platform-Specific Methods for Setting EDAEXTSEC on page If the server is not running, start it using the instructions for your platform. The server will start in DBMS security mode. 13. Examine the edaprint.log file. If it indicates that there were any errors, stop the server and then start it with security OFF to correct the errors. 14. Restart your browser and connect to the Web Console. When prompted, enter a valid DBMS user ID and password. If you wish to add other DBMS users, first connect as a DBMS user defined as server administrator. Then follow the instructions in Assigning Administration Levels on page Note: A common problem when switching from OPSYS to DBMS is the existence of files in EDATEMP that cannot be removed due to insufficient privileges. To handle this problem, use edastart -cleardir (or member ICLRDIR on the z/os platform) in EDAEXTSEC=OPSYS mode to clear the directory before switching iway Software

49 Reference: Usage Notes for DBMS Security Server Security If an error is detected in the security_dbms definition, the DBMS is down, or your DBMS user ID is invalid, you will not be able to access the Web Console. In these situations, you must bring the server down using the line console and correct the problem. The server may have other DBMS connections defined, but only one DBMS connection can be used for User authentication. Reference: Password Passthru and Security DBMS Security DBMS (using password passthru) is supported for the following engines: DB2 Informix MS SQL Server MySQL Oracle Sybase Teradata (ODBC) SAP R/3 SAP BW Essbase Web Services Web Console Access Control With Security DBMS Access to the Web Console is protected by user authentication against the selected DBMS. Authenticated users are permitted to perform certain control operations on the Web Console, depending on their definitions in admin.cfg as Server Administrators, Application Administrator, Server Operator, or Basic User. Within a given administration level, additional Administration privileges may be applied. As a result, available Web Console features may vary from site to site or between server configurations at a site. For details, see Administration Levels and Web Console Privileges on page Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-15

50 Security DBMS Restricting Access to the Web Console in DBMS Security Mode How to: Restrict Access to the Web Console in DBMS Security Mode By default, a user who starts the Web Console and is not identified in the admin.cfg file as belonging to one the three administration levels (Server Administrator, Application Administrator, Server Operator) is given access to Web Console functions based on the default_admin_level setting. Procedure: How to Restrict Access to the Web Console in DBMS Security Mode 1. Login to the server that is running in DBMS security mode. 2. From the Web Console menu bar, select Workspace, then Access Control. 3. Click Others in the navigation pane. The Access Control pane opens. 4. The default_admin_level setting defines the administration level given to a Web Console user if no entry is found in the admin.cfg file for that user. The options are: Server Administrator Application Administrator Basic User None. (No access allowed.) Select the value you want to apply. If only users defined in the admin.cfg are to be allowed access, select None. 5. Click Apply and Restart. Note: If a server administrator has established an Anonymous ID, it can be used to access the Web Console without an explicitly entered ID. For details, see Setting an Anonymous User ID on page 2-38 and Impact of Anonymous User IDs on page iway Software

51 Server Security Security LDAP In this section: Web Console Access Control With Security LDAP Restricting Access to the Web Console in LDAP Security Mode How to: Configure LDAP Security Mode Reference: LDAP Vendor Library Prerequisites Example: Making Sun LDAP Library Files Available In LDAP (Lightweight Directory Access Protocol) security mode there is no impersonation by data agents, but connection credentials are authenticated against the established directory services. From the operating system point of view, all server processes run as a single user ID. LDAP security mode is presently supported on Windows, UNIX, i5/os, and the Unified Server (HFS and PDS deployments). LDAP security mode supports profiles for LDAP users and LDAP groups. Procedure: How to Configure LDAP Security Mode This procedure assumes that the server is already running. 1. Access the Web Console with a server administrator user ID. 2. From the Web Console menu bar, select Workspace, Access Control. The Access Control pane opens. The security mode to which the server is currently set is displayed in the Security Mode drop-down list. 3. Select LDAP from the Security Mode drop-down list. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-17

52 Security LDAP 4. Complete the LDAP security settings, which are organized on three tabs: Connection, User, and Group. Connection tab ldap_lib_vendor Select Sun, Novell, IBM, Microsoft, or OpenLDAP (on LINUX only) from the drop-down list to specify the type of LDAP vendor libraries that the server modules are linked to. The path to the libraries should be available to the server at run time. If you choose OpenLDAP on LINUX, you will see two additional fields, ldap_libldap and ldap_liblber. These parameters specify the names of the OpenLDAP libraries that the server module loads at run-time. The path to the libraries should be available to the server at run time. You are prompted to specify the library name at run time. If you do not supply a different name a default library name is used. ldap_host Enter the host name used to connect to the LDAP server. If you do not supply a value, Information Builders assumes the default LDAP server. ldap_port Enter the TCP port number used to connect to the LDAP server. 389 is the default value. 636 is the default value for an SSL connection. ldap_secure_connection LDAP (Lightweight Directory Access Protocol) security mode supports Secure Sockets Layer (SSL) API calls to establish an SSL/TLS connection. Using server authentication only, the iway Server initiates API calls to verify that the LDAP server being connected to is the same server that provided certification. You can set the LDAP secure connection from the Web Console: Select No, the default value, if you do not wish to enable SSL. Select Yes to enable an encrypted Secure Sockets Layer (SSL) session with the LDAP server iway Software

53 Server Security If you have selected IBM, Sun, or Novell as the your ldap_lib_vendor, when you select Yes in the ldap_secure_conection field, additional options are added to the Connection tab: For Sun and IBM, ldap_ssl_certificate is added. For Novell, ldap_ssl_certificate and ldap_ssl_certification_encoding are added. ldap_ssl_certificate - Enter the name of the LDAP attribute used by the API to establish the SSL/TLS connection. The server employs server authentication only, checking through API calls that the LDAP server you are connecting to is the one that provided the certificate. Values depend on the LDAP vendor, as follows: Novell API specifies the file name, including path, of the Trusted Root Certificate that the LDAP server provided for authentication. Sun/Netscape API specifies the path to "cert7.db" - Netscape certificate database, excluding the file name, that the LDAP server provided for authentication. IBM API specifies the file name, including the path, for ldapkey.kdb (IBM key database file that the LDAP server provided for authentication). The "ldapkey.sth" password stash file should be in the same directory. Note that in addition to IBM LDAP client libraries, Global Security Kit libraries are needed to make SSL to work. On Windows machines GSK must be installed. Microsoft API ignores the ldap_ssl_certificate configuration parameter since it is not used in an Active Directory. The server certificate should be installed in a certificate store. ldap_ssl_certificate_encoding - For Novell, select the standard used to encode the certificate from the drop-down list. Encryption and file format depend on API vendor specifications. The options are B64 and DER. ldap_ad_only When you choose Microsoft in the ldap_lib_vendor field, the ldap_ad_only field is added to the pane. Click Yes to turn on the ldap_ad_only configuration switch. This enables you to connect to the Active Directory (ad) using the Windows-specific API, without having to code ldap_principal and ldap_credentials. (In fact, these two fields are removed from the LDAP settings pane.) Click the User tab and, in the ldap_user_attribute field, enter the LDAP attribute to be used when searching for user entries. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-19

54 Security LDAP Note that uid is the default value for LDAP, and samaccountname is the suggested value for the Active Directory. Regardless of which vendor libraries you use, when you connect to a Microsoft Active Director you can set ldap_user_attribute to samaccountname or userprincipalname. One reason to change the default value is to allow users to log on with an address instead of a user ID. In this situation, you can change the ldap_user_attribute value to mail or userprincipalname (if this corresponds with the name of the appropriate attribute in your directory). ldap_principal Contains the distinguished name (dn) of a service account with sufficient access rights to locate user entries in the directory. You must use this attribute, along with ldap_credentials, when an anonymous bind is not supported by the LDAP Server. (A anonymous bind is one in which the user dn and password are not supplied when initiating a session). ldap_credentials Contains the password of the service account defined in ldap_principal. Note: Active Directory does not allow an anonymous search. User tab ldap_user_base Enter the distinguished name (dn) of a folder in the directory services structure, where user accounts are stored. This will be the root dn where the user search starts. ldap_user_scope Specifies the scope of the search for the user. Select one of the following from the drop-down list: subtree - indicates a search of everything under the base dn. This is the default value. onelevel - indicates a search of entries one level down from the base dn. base - indicates a search of the start node only iway Software

55 ldap_user_class Server Security Specifies the object class used when searching for user entries. Note: The following parameters form the search filter: ldap_user_class, ldap_user_attribute, ldap_group_class, ldap_group_attribute.the standard syntax is: (&(Property_Name=Property_Value)(Property_Name=Property_Value)) You can also use the simplified form (Property_Name=Property_Value) by specifying asterisks as values for the following parameters: ldap_user_class = * ldap_group_class = * ldap_user_attribute Specifies the LDAP attribute used when searching for user entries. uid is the default value for LDAP, and samaccountname is the suggested value for the Active Directory. One reason to change the default value would be to allow users to log on with an address instead of a user ID. In this case, you might change the value to mail or userprincipalname (if this corresponds with the name of the appropriate attribute in your directory). Note: The following parameters form the search filter: ldap_user_class, ldap_user_attribute, ldap_group_class, ldap_group_attribute. ldap_user_group attribute Specifies the LDAP attribute used to identify the group in a user object. Group tab ldap_group_class Specifies the object class used when searching for group entries. The default value is groupofuniquenames. Note: The following parameters form the search filter: ldap_user_class, ldap_user_attribute, ldap_group_class, ldap_group_attribute. ldap_group_attribute Specifies the LDAP attribute used to identify a group s name. The default value is cn. Note: The following parameters form the search filter: ldap_user_class, ldap_user_attribute, ldap_group_class, ldap_group_attribute. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-21

56 Security LDAP ldap_member_attribute Specifies the LDAP attribute used to identify users in a group. The default value is uniquemember. 5. Choose a Server Administrator from the drop-down list or provide a new user ID. If you enter a new ID, it will be added to the admin.cfg file as a Server Administrator, with no password. 6. At this point, it is a good idea to click the Test button to make sure the LDAP connection is working. You will be prompted for a password for the selected user ID. Click Continue. The LDAP server will authenticate this ID. If it is a valid LDAP ID, a message will be returned indicating that authentication was successful. If the ID is not a valid LDAP ID, the LDAP server will return a message indicating that authentication was not successful. 7. If the server was started with security mode OPSYS, click the Apply and Stop button; otherwise, click the Apply and Restart button. If you click Apply and Stop, the server stops; proceed with Step 8. If you click Apply and Restart button, the server restarts in LDAP security mode, but the next time the server is restarted (other than from the security mode pane), the security mode reverts to whatever it was at the start of this procedure. This is called a dynamic restart. A message to this affect is displayed on the screen. To preserve the LDAP security mode, proceed with Step Set the EDAEXTSEC variable according to the instructions in Platform-Specific Methods for Setting EDAEXTSEC on page If the server is not running, start it using the instructions for your platform. The server will start in LDAP security mode. 10. Examine the edaprint.log file. If it indicates errors, stop the server, then start it with security OFF to correct the errors. 11. Restart your browser and connect to the Web Console. When prompted, enter a valid LDAP user ID and password. If you wish to add other LDAP users, first connect as an LDAP user defined as server administrator. Then follow the instructions in Assigning Administration Levels on page Note: A common problem when switching from OPSYS to LDAP is the existence of files in EDATEMP that cannot be removed due to insufficient privileges. To handle this problem, use edastart -cleardir (or member ICLRDIR on the z/os platform) in EDAEXTSEC=OPSYS mode to clear the directory before switching iway Software

57 Reference: LDAP Vendor Library Prerequisites Server Security System Requirements. LDAP Security mode requires the appropriate LDAP vendor library files to be available to the server at run time: 1. If the LDAP vendor library files are not currently available on the server platform, download them from the appropriate vendor Web site, unzip them if necessary, and transfer them to the server platform. You can identify which files you need in LDAP Vendor Library Prerequisites. 2. Edit the library path or (on Windows) the system path to include the location of the library files. The LDAP vendor library files for Windows systems are: Sun IBM Novell Microsoft Windows libnspr4.dll libplc4.dll libplds4.dll nsldap32v50.dll nsldappr32v50.dll nsldapssl32v50.dll nss3.dll sasl32.dll ssl3.dll libidsldap.dll libibmldapdbg.dll ldapsdk.dll ldapssl.dll (64 bit NA) wldap32.dll advapi32.dll (64 bit NA) The LDAP vendor library files for z/os and i5/os systems are: IBM z/os i5/os statically linked statically linked Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-23

58 Security LDAP The LDAP vendor library files for UNIX systems are: OS Vendor Sun (Sun ONE Directory Server Resource Kit 5.2.1, except as noted) IBM Novell OpenLDAP AIX libldap50.so libnspr4.so libnss3.so libplc4.so libplds4.so libprldap50.so libsasl.so libssl3.so libssldap50.so statically linked libldapsdk.so libldapssl.so (64 bit NA) N/A (64 bit NA) HP libldap50.sl libnspr4.sl libnss3.sl libplc4.sl libplds4.sl libprldap50.sl libsasl.sl libssl3.sl libssldap50.sl statically linked (64 bit NA) libldapsdk.sl libldapssl.sl (64 bit NA) N/A (see notes following chart) Linux libldap50.so libnspr4.so libnss3.so libplc4.so libplds4.so libprldap50.so libsasl.so libssl3.so libssldap50.so libibmldap.so libldapiconv.so (64 bit NA) libldapsdk.so libldapssl.so (64 bit NA) libldap_r.so liblber.so (64 bit NA) 2-24 iway Software

59 Server Security OS Vendor Sun (Sun ONE Directory Server Resource Kit 5.2.1, except as noted) IBM Novell OpenLDAP SunOS 5.8 libldap50.so libnspr4.so libnss3.so libplc4.so libplds4.so libprldap50.so libsasl.so libssl3.so libssldap50.so libibmldap.so libldapsdk.so libldapssl.so (64 bit NA) N/A SunOS 5.9 and 5.10 libldap.so (Native SunOS library) libibmldap.so libldapsdk.so lilbldapssl.so (64 bit NA) N/A Note: NA = Not Available from vendor. Statically linked builds do not required external libraries. When configuring LDAP for HP, note that SSL mode currently has a problem that is under investigation; we advise you to use non-ssl mode libraries. When using third party libraries, complete products should be installed and the associated libraries must be on the library path of the server before start up. The library path is driven by different variables depending on platform (Windows: PATH, HP-UX: SHLIB_PATH, AIX: LIBPATH, USS: LIBPATH, i5/os: Library Path, Other UNIX s: LD_LIBRARY_PATH). Libraries shown in this table are the main libraries our module is linked with; they may, in turn, load a chain of system libraries, which also need to be present. Not all vendors provide 64 bit versions, but, when available, they are configurable. Before starting the iway configuration steps, independently verify your LDAP connection and any configuration ids being used. Testing may be done by downloading and installing an LDAP connection test tool such as Softerra s LDAP Browser, at Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-25

60 Security LDAP Example: Making Sun LDAP Library Files Available To make Sun s LDAP library files available to the server at run time: 1. Access the product download Web site for Sun ONE Directory Server Resource Kit 5.2.1: (Note that this URL is correct as of the date these Release Notes were published. Third-party URLs are subject to change.) 2. Click the Download link at the bottom right of the Web page. (Do not click the Downloads menu option at the top of the page.) The login page opens. You will be prompted for a registered user login or to register. 3. Either enter your Sun username and password, or if you do not have an account click Register Now and follow the prompts to create an account and then log in. This is free. 4. Accept the license agreement. 5. Download the appropriate platform package. Select the optimized package, not the debug version. 6. Once downloaded, unzip the file, and then unzip the second zip file contained within the first. 7. Navigate to the directory in which you unzipped the downloaded file, and then cd to the lib subdirectory. 8. FTP the files you need (as indicated in LDAP Vendor Library Prerequisites), in binary format, to their own directory on the server platform. 9. Edit the library path to include the location of the library files you just FTPed. Web Console Access Control With Security LDAP Access to the Web Console is protected by user authentication against the LDAP (or AD) server. Authenticated users are permitted to perform certain control operations on the Web Console, depending on their definitions in admin.cfg as Server Administrators, Application Administrator, Server Operator, or Basic User. Within a given administration level, additional Administration privileges may be applied. As a result, available Web Console features may vary from site to site or between server configurations at a site. For details, see Administration Levels and Web Console Privileges on page iway Software

61 Server Security Restricting Access to the Web Console in LDAP Security Mode How to: Restrict Access to the Web Console in LDAP Security Mode By default, a user who starts the Web Console and is not identified in the admin.cfg file as belonging to one the three administration levels (Server Administrator, Application Administrator, Server Operator) is given access to Web Console functions based on the default_admin_level setting. Procedure: How to Restrict Access to the Web Console in LDAP Security Mode 1. Login to the server that is running in LDAP security mode. 2. From the Web Console menu bar, select Workspace, then Access Control. 3. Click Others in the navigation pane. The Access Control pane opens. 4. The default_admin_level setting defines the administration level given to a Web Console user if no entry is found in the admin.cfg file for that user. The options are: Server Administrator Application Administrator Basic User None. (No access allowed.) Select the value you want to apply. If only users defined in the admin.cfg are to be allowed access, select None. 5. Click Apply and Restart. Note: If a server administrator has established an Anonymous ID, it can be used to access the Web Console without an explicitly entered ID. For details, see Setting an Anonymous User ID on page 2-38 and Impact of Anonymous User IDs on page Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-27

62 Security OFF Security OFF In this section: Web Console Access Control With Security OFF This mode is applicable when the installation does not need any security restrictions. The server will run unsecured (security OFF) if the desired security setting cannot be established for any reason. This setting allows anyone to change the configuration through the Web Console and restart the server or stop it. To run the server in this mode, omit the authorization steps during installation, or export the environment variable EDAEXTSEC=OFF before startup. Web Console Access Control With Security OFF With SECURITY OFF, anyone can access the Web Console, with full, unrestricted use of its features. Assigning Administration Levels How to: Assign an Administration Level to a User Assign an Administration Level to a Group View or Change a User or Group s Properties Delete a User or Group Set Customized Privileges for Administrator Levels Reference: Administration Levels and Web Console Privileges Before you start a server with security enabled you should configure Server Administrator passwords either by providing the passwords at installation time or using the Web Console. A server administrator can assign specific users the following administration levels: Server Administrator, Application Administrator, Server Operator, Basic User, or All Users. A server administrator can also select or deselect certain privileges for these users groups. for details, see Administration Levels and Web Console Privileges on page iway Software

63 Server Security A user who starts the Web Console with any security mode other than OFF, and is not identified as belonging to one of the administration levels, is classed as a general user and given the privileges that have been identified for a basic level user of Web Console features. If you are running your server with security modes OPSYS, LDAP, or PTH, you can also assign these administration levels to groups of users. The group name is defined in the native OS security for OPSYS, in the LDAP security environment, or by a Server Administrator for PTH security. Note: OPSYS security does not support groups on Windows. The user and group administration levels are stored in a release independent file called admin.cfg, which is located, by default, in /ibi/profiles. This location is defined with the server configuration parameter edaprfu, which is stored in the edaserve.cfg file. The admin.cfg file should not be shared between servers that run with different security modes. Procedure: How to Assign an Administration Level to a User This procedure assumes that the user is logged in to the Web Console as a server administrator. A server administrator can assign an administration level to a user by following these steps: 1. From the Web Console menu bar, select Workspace, Access Control. The Security Mode pane opens, and a tree of users and/or groups for the security mode is created in the left pane. 2. There are two way to create a new user: Click New, then User on the expanded menu bar. Click the Users folder and select New User from the pop-up menu. In either case, the security mode may precede the user option for example, PTH User. The Access Control pane opens. 3. Enter a User ID. 4. If you use domain names with the user IDs (Windows only), enter the domain name in the domain field, if shown (OPSYS only). 5. In the Password and Confirm Password fields, enter the password for the User ID. 6. Enter an address for the user. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-29

64 Assigning Administration Levels 7. For PTH security mode, the user s authorization level and group membership can be managed explicitly. For the Set credentials regarding option, select the Level or Group radio button: For Level, choose an Administration Level from the drop-down list: Server Administrator, Application Administrator, Server Operator, or Basic User. For Group, optionally select an existing group from the drop-down list. This option enables you to add the new user to an existing Administration Level group. For OPSYS, DBMS, and LDAP security modes, select an administrator level from the Select User drop-down list: the options are Server Administrator, Application Administrator, Server Operator, Basic User. 8. Click the Create button. Procedure: How to Assign an Administration Level to a Group This procedure assumes that the user is logged in to the Web Console as a server administrator. For the OPSYS, LDAP, or PTH security modes, a server administrator can assign an administration level to groups of users by following these steps: 1. From the Web Console menu bar, select Workspace, then Access Control.The Security Mode pane opens, and a tree of users and/or groups for the security mode is created in the left pane. 2. Click the Group folder and select New Group. 3. In the Access Control pane, enter a Group Name. 4. To assign the group to an administration level, choose one of the following options from the pull-down list: Server Administrator, Application Administrator, Server Operator, or Basic User. 5. Click the Create button. 6. Expand the Group folder in the navigation pane to verify that the new group has been added to the proper administration level folder iway Software

65 Server Security Procedure: How to View or Change a User or Group s Properties 1. From the Web Console menu bar, select Workspace, Access Control. The Access Control pane opens. 2. Expand the Users or Groups tree. 3. Click the user or group whose properties you want to view or change and select Properties from the pop-up menu. The properties display. 4. You can select a different administration level from the Administration Level drop-down box and, if the administration level is Server Administrator, you can change the password. Note: If only one user is defined as a Server Administrator, you cannot change that user s administration level. 5. Click the Apply button. The user or group is moved to the new administration level. Procedure: How to Delete a User or Group 1. From the Web Console menu bar, select Workspace, Access Control. The Access Control pane opens. 2. Expand the Users or Groups tree. 3. Click the user or group and select Remove from the pop-up window. You are prompted to confirm that you want to delete the user or group. 4. Click OK. Note: If only one user is defined as a Server Administrator, you cannot delete that user. The user or group is deleted. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-31

66 Assigning Administration Levels Procedure: How to Set Customized Privileges for Administrator Levels A server administrator can set selected privileges for basic users, application administrators, and server operators. Configurable options are tailored to each user group. 1. On the Web Console menu bar, select Workspace, then Access Control. 2. Click the Privilege folder in the navigation pane. The Privilege pane opens. 3. In the Administrative Level field, select a user type from the drop-down list. The options are: Application Administrator, Server Operator, and Basic User. 4. In the Administrative Privilege field, click the check boxes for the functions you want the designated class of users to be able to perform. Configurable options vary by user group. 5. Click Apply to confirm these setting. 6. Click Reset to Default Privileges if you wish to revert to the standard privileges assigned to that user group. 7. Click Show Current Privileges to display a chart entitled Web Console Functionality and Current Role Privileges Based on admin_level. For a list of user types and privileges, including those that are configurable for each type of user, see Administration Levels and Web Console Privileges on page iway Software

67 Reference: Administration Levels and Web Console Privileges Server Security The availability of some Web Console panes/features is based on type of user (Server Administrator, Application Administrator, Basic User, Server Operator). Yes = Privilege is granted to the role and cannot be disabled. No = Privilege is not enabled/granted to the role and cannot be enabled. Configurable = Privilege can be enable/disabled by selecting check boxes on the Privileges pane. By default, this privilege is enabled. Configurable [no] = Privilege can be enable/disabled by selecting check boxes on the Privileges pane. By default, this privilege is disabled. Area Web Console Tasks Server Administrator (SRV) Application Administrator (APP) Basic User (USR) Server Operator (OPR) Data Adapters Add/Remove Data Adapters; Add, Change, Delete DBMS connections (in server profile, own group profile, and other users profiles) Yes No No No Add, Change, Delete DBMS connections (in own user profile) Yes Configurable Configurable No Test DBMS connections (in server profile or in your group profile) Test DBMS connections (in own profile) Yes Yes Yes No Yes Yes Yes No Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-33

68 Assigning Administration Levels Area Web Console Tasks Server Administrator (SRV) Application Administrator (APP) Basic User (USR) Server Operator (OPR) Metadata Procedure Create/Manage Metadata from Adapters or Metadata pane Manage Data (Recreate, Insert, or Delete) Access to Metadata pane Save, Delete, Move, Copy procedures Yes Configurable No No Yes Configurable No No Yes Configurable No No Yes Configurable No No Create, Edit procedures without saving Yes Configurable Configurable No No Run Stress Yes Configurable [no] Run procedures Yes Configurable Configurable Configurable [no] No Run Procedures Deferred; Delete output Yes Configurable Configurable [no] No List, View Deferred Yes Configurable Configurable No Data Utilities Yes No No No Resource Management Resource Management Yes Configurable No No 2-34 iway Software

69 Server Security Area Web Console Tasks Server Administrator (SRV) Application Administrator (APP) Basic User (USR) Server Operator (OPR) Workspace Workspace tasks Access Control Yes No No No Server Configuration Yes No No No Migration Yes No No No Monitoring (allows killing agents) Yes No No Configurable Scalability Yes No No No Manage remote servers Test remote servers Yes No No No Yes Yes No No Diagnostics Yes No No No Stop, Restart server Quiesce, Enable connections Enable, Disable server traces Yes No No Configurable Yes No No Configurable Yes No No Configurable Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-35

70 Assigning Administration Levels Area Web Console Tasks Server Administrator (SRV) Application Administrator (APP) Basic User (USR) Server Operator (OPR) Workspace (continued) My Console tasks Access to My Console pane Yes Configurable Configurable Configurable Log off Yes Yes Yes Yes Login status Yes Yes Yes Yes Change own password Yes Configurable Configurable Configurable Stop My Console requests Yes Yes Yes Yes Kill own agents No (use Workspace monitor) Configurable Configurable No (use Workspace monitor) Change own application path Yes Configurable Configurable No Add DBMS traces to the Log Yes Yes Yes Yes Note: View Session Log Yes Yes Yes Yes Preferences Yes Yes Yes Yes Application Path: If Change Own Application is deselected, pathing is based on the path set by the server administrator for each user. In such an environment, the server administrator is responsible for the application path for the entire community. This can provide an effective mode of access ccntrol to application directories for security modes such as DBMS, LSAP, and PTH, where native system file security does not apply. Kill Own Agents: May be used for any type of job, however, queries from the current Web Console session can be more conveniently killed by using the My Console, Stop My Console Request option. (Note that if the Kill Own Agents privilege is deselected, a server administrator or a server operator must be contacted to kill the agent using the Monitor option.) 2-36 iway Software

71 Server Security Edit and Run Procedures: Disable is used to lock down applications for a production environment. Run Procedures: Disable is used for sites that want to disallow end-user Web Console procedure execution, but allow other Web Console functions. Sending Customizable Login Messages How to: Customize Messages That Users Will See at Login A server administrator can customize messages that users will see at login. Typical messages might be announcements of release upgrades, daily tasks, special tasks, and suggestions to clear the cache. Procedure: How to Customize Messages That Users Will See at Login 1. From the Web Console menu bar, select Workspace, Configuration. 2. Under the General folder in the navigation pane, click Login Message. The Login Message pane opens at the right. 3. In the Administration Level field, select one of the following: Server Administrator Application Administrator Server Operator Basic User All Users 4. In the Message input box, type a message. 5. In the Display box, indicate the number of times you want the message to be displayed. 6. Click Apply. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-37

72 Working With User IDs and Passwords Working With User IDs and Passwords In this section: Setting an Anonymous User ID Viewing or Changing the Password Separator Character Login Password Expiration Warning Encrypting Passwords Stored in Configuration Files The following options are available for all security modes. You can: Set an anonymous user ID that provides basic user rights to the Web Console. Change the delimiter character between the old and new passwords. Control the start time of warning messages on operating systems that support passwords expiration. Setting an Anonymous User ID How to: Set an Anonymous User ID Reference: Impact of Anonymous User IDs An authorized server administration can set an anonymous user ID that can access the Web Console when the user ID/password fields on the Web Console login screen are blank and the user clicks Log in. This anonymous user ID provides the ID and, in turn, the user rights for the Web Console (basic user, by default). Further configuration for the basic user can be achieved by creating a user profile for the anonymous user ID. If an anonymous ID matches a user in the admin.cfg list, the applicable administration level and privileges are applied. Note: On Windows, for security mode OPSYS only, you must turn IWA security off to use this feature. Select Workspace, Configuration from the Web Console menu bar, then click Listeners, HTTP, Properties in the navigation pane, and click the Security IWA check box to deselect it iway Software

73 Server Security Procedure: How to Set an Anonymous User ID 1. Log on to the Web Console using a user ID that has server administration rights. 2. From the Web Console menu bar, select the following options in succession: Workspace, Access Control. 3. Select Others in the left pane. 4. In the right pane, enter a user ID in the anonymous_id input box. 5. Enter a password in the anonymous_pass input box and repeat it in the Confirm Password box. 6. Click Apply and Restart. Reference: Impact of Anonymous User IDs If an Anonymous ID has been set up (as described in Setting an Anonymous User ID on page 2-38) and a user ID/password are not entered on the Web Console logon pane, the following rules apply. For this illustration, suppose that an Anonymous User is configured with a user ID and password. Note: If no password is set for an anonymous user ID, access is not allowed under any circumstance. Authenticate_all_pthuser Anonymous user ID match/no match variations in admin.cfg No match in admin.cfg Match variation 1: admin.cfg entry has a blank password Y No access allowed Access allowed; admin level is set based on fred entry in admin.cfg N Access depends on default_admin_level. When default_admin_level=none, no access is allowed; otherwise, access is allowed and admin_level is assigned based on setting. Access allowed; admin level is set based on fred entry in admin.cfg Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-39

74 Working With User IDs and Passwords Match variation 2: admin.cfg entry has the same password as anonymous Match variation 3: admin.cfg entry has a different password from anonymous Authenticate_all_pthuser Access allowed; admin level is set based on anonymous user ID matched entry in admin.cfg No access allowed Access allowed; admin level is set based on anonymous user ID matched entry in admin.cfg No access allowed Viewing or Changing the Password Separator Character How to: View or Change the Password Separator Character When an application has the option to change a user s password, the old and new passwords are sent to the server using a separator character (by default, a comma). For example: old_password,new_password The separator character is defined by the password_change_delimiter field. This feature is not supported when Security Mode is OFF. Procedure: How to View or Change the Password Separator Character 1. From the Web Console menu bar, select Workspace, then Access Control. 2. Click the Others folder in the navigation pane. The Access Control pane opens. 3. In the password_change_delimiter input box, enter a single character to use as the delimiter between an old and new password. (The default character is a comma.) Note that you cannot use the designated password_change_delimiter character in a password. 4. Click Apply and Restart iway Software

75 Server Security Login Password Expiration Warning How to: Initiate Notification of a Password s Imminent Expiration On Operating Systems that support password expiration, you can specify that a warning message be displayed a specified number of days prior to the expiration date. The message will appear after the initial login screen; you must then click the Continue button to open the Web Console. Users can employ standard tools to change their passwords before expiration occurs. Note: The password expiration warning is supported only on Operating Systems where IDs are configured to expire and this extended security feature is active for the user ID. Procedure: How to Initiate Notification of a Password s Imminent Expiration 1. From the Web Console menu bar, select Workspace, then Configuration. 2. In the Workspace Configuration navigation pane, expand the Listeners folder, then click HTTP and select Properties from the pop-up menu. The Listener Configuration pane opens. 3. In the PASS_EXPIRE_NOTIFICATION field, enter the number of days prior to expiration that you want the warning to begin to appear when a user whose password is about to expire logs in. 4. Click the Save and Restart button. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-41

76 Working With User IDs and Passwords Encrypting Passwords Stored in Configuration Files How to: Encrypt Passwords Stored in Configuration Files You can select an encryption algorithm for passwords stored in configuration files. Procedure: How to Encrypt Passwords Stored in Configuration Files 1. From the Web Console menu bar, choose Workspace, then Access Control. 2. Click the Others folder in the Access Control navigation pane. The Access Control pane opens. 3. To define the cipher used to encrypt passwords in configuration files, click the drop-down list for cfgfile_cipher and select: DES for Data Encryption Standard. 3DES for Triple Data Encryption Standard. AES for Advanced Encryption Standard (key size 128 bits). 4. Click the Apply and Restart button iway Software

77 Server Security Logon Ticket Authorization on the Web How to: Ensure Compliance With SSO Prerequisites Complete SSO Verification Single sign-on (SSO) enables users to login to the SAP portal with their credentials and then access WebFOCUS components, such as the Reporting Server with the SAP R3 and SAP BW adapters, the Web Console, and the WebFOCUS client (Managed Reporting) without a secondary logon. This is achieved in the following manner: The user logs on to the SAP portal with a user ID and password. The portal authenticates the user and places a cookie in the user s browser. When the user accesses the Web Console or the WebFOCUS servlet, the servlet will not do the authentication, but will, instead, trust the user ID and use it in the Managed Reporting environment and in the Web Console security scheme. For example, a user may be given server_admin or application_admin level privileges on the Reporting Server (via the admin.cfg file). When the user runs a backend SAP report, the cookie is processed and passed to the SAP RFC connection that provides access to the SAP data. Procedure: How to Ensure Compliance With SSO Prerequisites Complete the following steps to ensure that pre-requisites have been met: 1. Export the public key certificate from the SAP portal into $EDACONF/etc. 2. Set Server security to DBMS. 3. Configure the SAP/BW connection for Password-Passthru. 4. Ensure that Security DBMS with Password-passthru to SAP/BW is working. 5. Ensure that SAP RFCSDK 6.40, SAP SSOEXT, and SAP SECULIB 5.4 are in the path. (Check your Operating System or consult a system administrator for details.) Once prerequisites have been satisfied, complete the SSO verification procedure. Procedure: How to Complete SSO Verification 1. From the SAP portal ( execute a command that requires authentication (using a logon screen from the Portal). This generates an SSO cookie. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 2-43

78 Logon Ticket Authorization on the Web 2. Overwrite the SAP portal url with the one for the WebFOCUS Reporting Server, using the same domain (e.g. At this point, no logon screen should pop up since the user is logged in and SSO login has been successfully verified iway Software

79 3 Configuring Adapters Adapters must be configured to allow an iway Full Function Server, a WebFOCUS Reporting Server, or a DataMigrator Server to access data in different types of databases. You must add and configure an adapter for every database type you want to access. Topics: Configuring an Adapter Changing the Adapter Configuration This topic describes briefly how to declare connection attributes and authentication information, when required, using the Web Console or the Data Management Console. Detailed configuration information for each adapter is included in the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual.

80 Configuring an Adapter Configuring an Adapter You can configure any supported adapter for use with a Full-Function Server, WebFOCUS Reporting Server, or DataMigrator Server from the Web Console or the Data Management Console. To begin the process: From the Web Console, click Data Adapters on the menu bar. From the Data Management Console, click the Adapters tab at the bottom of the navigation pane. If adapters have already been configured, they are listed in the Adapters navigation pane. For general instructions about adding an adapter and declaring connection attributes, see How to Declare Connection Attributes From the Web Console on page 3-3 and How to Declare Connection Attributes From the Data Management Console on page 3-4. Although all database configuration panes have the same look and feel, the parameters are specific to each database. To obtain detailed configuration information for an adapter, see the Adapter Administration UNIX, Windows, OpenVMS, i5/os, and z/os manual. Most of the adapter configuration information is contained in two configuration files, EDASPROF.PRF and EDASERVE.CFG. How to: Declare Connection Attributes From the Web Console Declare Connection Attributes From the Data Management Console Test an Adapter Connection From the Web Console Test an Adapter Connection From the Data Management Console EDASPROF.PRF, or the global profile, contains data adapter connection information. EDASERVE.CFG contains database release and access method information. Your entries on the Web Console or the Data Management Console populate these files. An experienced Server Administrator can edit the global profile manually, but it is not recommended, as syntax may change from one release to another. 3-2 iway Software

81 Procedure: How to Declare Connection Attributes From the Web Console To configure the adapter from the Web Console: 1. Start the Web Console and select Data Adapters from the menu bar. 2. Click New Adapter. The Select Adapter to Add pane opens. 3. Expand an adapter group folder. Adapters are grouped as follows: SQL OLAP ERP Procedures Sequential and indexed DBMS Configuring Adapters 4. Expand a specific adapter folder and click a version (or, in some cases, simply the adapter name). The Add to Configuration pane opens. 5. If required, enter connection and authentication information values for the displayed parameters. (Some adapters do not require any input for configuration.) 6. Click Configure. The configured adapter is added to the Adapters list in the navigation pane. 7. Once the adapter is configured, you can click the adapter name or connection to perform a variety of other tasks, including creating synonyms, testing or deleting the connection, and changing or viewing the connection s properties. Specific options vary by adapter. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 3-3

82 Configuring an Adapter Procedure: How to Declare Connection Attributes From the Data Management Console Note: If the Adapters tab is not visible in the DMC, select the General page from the Tools, Options menu. Select Enable Adapters management and click OK. You must then close and reopen the DMC. 1. Select the Adapters tab at the bottom of the navigation pane. The Adapters tab opens. Expand the Server node, if it is not already expanded. 2. Right-click the Adapters folder and select Add. The Add Adapter Configuration window opens. 3. Expand an adapter group folder. Adapters are grouped as follows: SQL OLAP ERP Procedures Sequential and indexed DBMS 4. Then expand a specific adapter folder and click a version (or, in some cases, simply the adapter name). The Add to Configuration window opens. 5. If required, enter connection and authentication information values for the displayed parameters. (Some adapters do not require any input for configuration.) 6. Click Configure. A confirmation message appears, and the configured adapter is added to the Adapters tab. 7. If you click the Continue button, the Manage and Configure Data Adapters dialog box opens, enabling you to perform a variety of other tasks, including creating synonyms, testing or deleting the connection, and changing or viewing the connection s properties. Specific options vary by adapter. 3-4 iway Software

83 Procedure: How to Test an Adapter Connection From the Web Console 1. From the Web Console menu bar, select Data Adapters. The Configuring Data Adapters pane opens at the right. 2. Expand an adapter in the navigation pane. Configuring Adapters 3. Click the adapter connection and, if available for the selected adapter, click Test. The test results appear in the right pane. Test results vary, depending on adapter. Procedure: How to Test an Adapter Connection From the Data Management Console 1. Select the Adapters tab at the bottom of the Data Management Console (DMC) navigation pane. A list of configured adapters opens. 2. Right-click an adapter and, if available for the selected adapter, click Test. The test results appear in the right pane. Test results vary, depending on adapter. Changing the Adapter Configuration The Adapters navigation pane lists the adapters that have already been configured for the current operational instance. The parameters that apply for each adapter are fully described in the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os. The following general information applies. Click an Adapter in the navigation pane and choose from the tasks that are available for that adapter. The following table lists and describes the available tasks, or functions. Function Add connection Change Settings View Settings Remove Description Adds a connection for adapters that have the functionality to support multiple connections. Displays the Change Setting pane, where you can change a variety of settings in effect for the selected adapter. Displays a variety of settings in effect for the selected adapter. Removes the adapter configurations and all connection settings from the list of configured adapters. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 3-5

84 Changing the Adapter Configuration Open the Adapter folder in the navigation pane and click a version or connection to choose from the tasks that are available for the selected adapter. The following table lists and describes the available tasks or functions. Function Create Synonym Test Delete/Remove Properties Description Opens the first Create Synonym pane, where you can begin to enter the information required to create a synonym.these panes vary for different adapters. The options for each are fully documented in the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual. Runs a select statement for name/owner against a catalog table with a limit of up to 15 records. (See How to Test an Adapter Connection From the Web Console on page 3-5 and How to Test an Adapter Connection From the Data Management Console on page 3-5.) Deletes connection settings. Note: Entries are deleted from the server global profile, EDASPROF.PRF, but not from the workspace configuration file. Enables you to view and change connection parameters. Note: Duplicate entries are not verified. 3-6 iway Software

85 4 Configuring a Remote Server Clicking Workspace, Remote Servers on the Web Console menu bar opens the Remote Servers pane, where you can add remote server nodes to the communications configuration. For related information, see Adapter for iway in the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual. This adapter allows applications to access data sources that reside on a remote server.

86 4-2 iway Software

87 5 Creating and Working With Applications An application is a platform-independent repository for a group of related components, such as procedures, Master and Access Files, data files, HTML files, PDF files, and GIFs. You can use a variety of application (APP) commands to control the application environment, including the application itself, its component files, and its search paths. Topics: What is an Application? Managing Applications and Paths in the Web Console Managing Applications and Paths in the Data Management Console Application Commands Overview Search Path Management Commands Application and File Management Commands Output Redirection Commands Reports and Help Restricting the Use of APP Commands Accessing Metadata and Procedures Allocating Temporary Files Temporary Space Allocation for UNIX and z/os UNIX System Services Temporary File Directory Structure for Non-PDS Deployment

88 What is an Application? What is an Application? An application is a platform-independent repository for a group of related components, such as procedures, Master and Access Files, data files, HTML files, PDF files, and GIFs. It provides an area on the server that both confers a unique identity on the application s components and facilitates the sharing of components across applications in an organized manner. This construct also simplifies the process of moving a user s application from one platform to another and of deploying PC-developed applications. These components are physically grouped together on an application by application basis for runtime execution. This physical grouping can be within an application under a common root or a virtual mapping to an application anywhere in the file system. The physical application or mapped name is referred to as the application name in this document. A comprehensive set of APPlication commands are provided to control/manipulate the application components, as well as to facilitate applications that can be written and deployed to any platform. The physical location of an application and its components is determined by a configuration parameter called approot. This parameter is set at installation time and stored in the server configuration file, edaserve.cfg. The default value is dependent on the platform, relative to the install ID's home directory, where applicable, as indicated in the following chart. Note: Where directories are referenced in the chart, single-level, lowercase application directories are created below the approot value. The application names must be lowercase and must not contain spaces. For a PDS deployment on the Unified Server, data sets are created for each component type using the approot value as the high-level qualifier. Platform Unified Server HFS Deployment Unified Server PDS Deployment UNIX Linux Windows i5/os OpenVMS Default Value for approot.../ibi/apps approotvalue.appname.component_type.../ibi/apps.../ibi/apps...\ibi\apps.../ibi/apps [.IBI.APPS] 5-2 iway Software

89 Creating and Working With Applications Two applications are provided during installation: a default application called baseapp and an application containing sample files called ibisamp. Access to a particular application component can be explicit or implicit. Implicit access is dependent upon the search path in effect at the time of execution. The search path always includes the default application, baseapp. There is no need to explicitly declare this application. You can change the search path from the Web Console (see Managing Applications and Paths in the Web Console on page 5-3), from the Data Management Console (see Managing Applications and Paths in the Data Management Console on page 5-21), or from within your application code. You can also change the search path temporarily to add application names to the beginning or end of an existing search path. APP commands are described briefly in Application Commands Overview on page 5-21, and in detail later in this chapter. Note: For platforms that support the Universal Naming Convention (UNC), you can specify a network drive for approot. The UNC must be: Minimally one folder below the initial shared location. Not contain spaces. For example: \\mynode\myshare\accnting Managing Applications and Paths in the Web Console In this section: Working in the Application Configuration Pane Filtering Synonyms and Procedures Managing Application Files on the Web Console You begin all path management tasks by selecting either Metadata or Procedures on the Web Console menu bar. Both choices display the Application Directories folder on the navigation pane. Above this pane is a set of icons that provide the quickest way to initiate path management tasks. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-3

90 Managing Applications and Paths in the Web Console A single click on one of the following icon is enough to get you started. Icon Tool Tip Function and Hide and Show tree Filter Configure Path Refresh Toggles the navigation pane on and off, allowing one or both panes to occupy the screen, as needed. Note that these icons are displayed in any context in which you might wish to toggle the navigation pane on and off. Depending upon the selected context in the navigation pane, this icon opens the Filter Metadata Tree pane, where you can filter synonyms, or the Filter Procedures Tree pane, where you can filter procedures and HTML files. Opens the Application Configuration pane from which you can create applications, add applications to the search path, map and reorder applications, delete applications or mappings from the path. The Application Configuration pane provides additional icons designed to facilitate each of these tasks. Depending upon the selected context in the navigation pane, this icon refreshes the synonyms or procedures and HTML files listed in the application tree. Note that this icon is displayed in any context in which you might wish to refresh the display of objects on the navigation pane. 5-4 iway Software

91 Creating and Working With Applications Using Context Menus to Initiate Path Configuration and Filter Options As an alternative to using path management and filtering icons, you can initiate these tasks from right-click menus that appear at three levels of the Application Directories tree. Application Directories folder. Clicking this folder at the top of the application tree, opens a menu from which you can filter metadata or procedures, append applications to the current application path, or configure your application path. The Configure Path option opens an Application Configuration pane from which you can create applications, add them to the path, map and reorder applications, and delete applications or mappings from the path. Individual application folder. Clicking a folder for a specific application, like ibisamp, opens a menu from which you can refresh the application list, remove an application (other than baseapp) from the path, and rearrange the order of applications in the search path. From the Metadata list, you can create a synonym if at least one adapter had been configured. From the Procedures list, you can create a procedure. You can also open a Manage Files pane from which you can copy, move, and delete synonyms and procedures. Individual component in an application. Right-clicking a synonym or procedure component opens a menu from which you can: Move or copy a procedure or synonym from one application to another. Delete a procedure or drop a synonym from an application. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-5

92 Managing Applications and Paths in the Web Console Working in the Application Configuration Pane How to: Create a Profile in the Web Console Edit a Profile in the Web Console Create an Application in the Web Console Map an Application in the Web Console Configure the Application Path in the Web Console Delete an Application in the Web Console Delete an Application s Mapping in the Web Console The applications available for inclusion in the search path are identified by name, type, and physical location. With the exception of the baseapp application, which is always part of the search path, you must explicitly add applications to your search path. On the Web Console menu bar, select Procedures or Metadata. Click the Configure Path Configuration pane opens. icon above the navigation pane. The Application All path configuration tasks are managed from a single pane that provides its own set of icons to facilitate your work. 5-6 iway Software

93 Creating and Working With Applications On a Unified Server using PDS deployment, the physical location designations on the Application Management pane look a little different, but the icons are the same. Click one of the following icons to initiate these tasks. Icon Tool Tip Create Directory under APPROOT Create New mapping Above the Application directories list, the tip reads: Delete application directory or remove mapping Above the APP PATH box, the tips reads: Delete from APP PATH Up in APP PATH Down in APP PATH Copy APP PATH from server and group profiles Appears when configuring a new or existing user or group profile, but not the server profile. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-7

94 Managing Applications and Paths in the Web Console The procedures that follow will explain how to: Create a new profile or edit an existing profile. The profile is the location in which the search path is saved. Three levels of profiles are available for processing from this pane: edasprof (the server s global profile), group (if applicable to the platform), and user. Create a new physical application, which becomes a candidate for addition to the search path in a selected profile. Map an application name to an existing physical location outside of approot. The mapped application also becomes a candidate for inclusion in the search path of a selected profile. Configure the application path in the selected profile. The applications available for inclusion in the search path are identified by name, type, and physical location. With the exception of the baseapp application, which is always part of the search path, you must explicitly add applications to your search path. Delete a physical application or remove an application mapping. Procedure: How to Create a Profile in the Web Console 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Configure Path icon above the navigation pane. The Application Configuration pane opens. 3. Select New Profile from the drop-down list. 4. Enter a new profile name in the box provided. Then, follow instructions for configuring the application path. Procedure: How to Edit a Profile in the Web Console 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. 5-8 iway Software

95 Creating and Working With Applications In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Configure Path icon above the navigation pane. The Application Configuration pane opens. 3. Select a profile from the drop-down list. 4. Click the Edit button. The profile opens in a text editor with its current path displayed. 5. Edit the path information and click the Save icon. Tip: You can also edit a profile s search path by selecting and saving configuration options. Follow instructions for configuring the application path. Procedure: How to Create an Application in the Web Console 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Configure Path icon above the navigation pane. The Application Configuration pane opens. 3. Under Application directories, click the Create Directory under APPROOT icon. 4. Enter the application name in the pop-up window. Note that name may not contain spaces. If the name contains spaces, each section is understood to be a separate application. 5. Click OK. The new application is added to the Application directories list. Note: The application must still be added to the Application Path. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-9

96 Managing Applications and Paths in the Web Console Procedure: How to Map an Application in the Web Console You can assign an application name to a non-approot application anywhere in the file system. This application name becomes a virtual application under approot, which can be referenced in an APP PATH command and any other APP command that takes an application name as a parameter. (Note that mapping does not automatically add an application to the path; it simply makes it available for addition to the search path.) You can create a new mapping to a directory anywhere in the file system and include it in the server s page. Application mappings can be added and deleted on a per profile basis. 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Configure Path icon above the navigation pane. The Application Configuration pane opens. 3. You can include the mapping in a server, group or user profile. The global profile, edasprof, is set by default. Choose a profile from the drop-down list. The selected profile will have the application mapping added to it. 4. Under Application directories, click the Create New mapping icon. An input screen is displayed. 5. In the Mapping name box, enter an application name of up to 64 characters. In the Physical location box: For platforms other than USS, enter the full path of the physical directory to be mapped, in the format required on your platform. (If there are spaces in the directory you are mapping, you must enclose the entire path in double quotation marks.) For USS HFS and PDS deployments, enter values using the following formats: 5-10 iway Software

97 Creating and Working With Applications HFS ext=//dd:ddname or /dir/subdir PDS ext=//dd:ddname If applicable, click the check box next to Create directory if none exists. 6. Click OK. The application is marked Yes in the Mapped column of the Application directories list. Note: The mapping must still be added to the Application Path. Procedure: How to Configure the Application Path in the Web Console You must add an application directory or mapping to the Application Path for it to be accessible. 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Configure Path icon above the navigation pane. The Application Configuration pane opens. 3. To add an application to the server s APP PATH, select the candidate application in the Application Directories list and click the arrow is added to the APP PATH box. between the boxes. The application 4. To reorder applications in the APP PATH, use the Up and Down icons above the APP PATH box. 5. To remove an application from the APP PATH box, select it and click the Delete icon. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-11

98 Managing Applications and Paths in the Web Console 6. Click the Test APP PATH button to test modifications to the search path. An APP PATH Test window like the following opens. Executed profile shows which profiles have been executed. This depends on the level of profile you have selected. Executed command shows the APP command that results from the options selected on the configuration pane. The command will be either APP PATH or APP PREPENDPATH. Effective APP PATH shows the effective application tree that will result from all the executed profiles, including the selected profile level that is, if edasprof was selected, then only edasprof will be executed; if a group profile is selected, edasprof will be executed followed by the group profile; if a user profile is selected then edasprof will be executed, followed by a group profile (if available) and then by the user profile. 7. If you select a group or user profile from the drop-down list, three additional options for configuring the path become available: Copy APP PATH From Server and Group Profiles icon above the APP PATH box enables you to quickly copy the effective APP path from the server profile (and/or from a group profile if available) into the APP PATH box, after which you can make additional adjustments to the path, as required. Override server/group profile radio button below the APP PATH box. This button is selected by default. When you click Test, applications in the APP PATH box are executed in APP PATH format, overriding any previously executed paths (including those defined in the server profile and/or in a group profile, if one exists.) Prepend to server/group profile radio button below the APP PATH box. When you click Test, applications in the APP PATH box are executed in APP PREPENDPATH format. This option adds applications listed in the APP PATH box to the beginning of the effective search path iway Software

99 Creating and Working With Applications 8. When you are satisfied with your changes to the server profile, click the Save button. The navigation pane is updated. Procedure: How to Delete an Application in the Web Console 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Configure Path icon above the navigation pane. The Application Configuration pane opens. 3. Select the application you want to delete from the Application directories list, and click the Delete icon. A confirmation dialog box opens. 4. Click OK to delete the application. Procedure: How to Delete an Application s Mapping in the Web Console 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Configure Path icon above the navigation pane. The Application Configuration pane opens. 3. Select an application that is marked Yes in the Mapped column of the Application directories list. 4. Click the Delete icon. 5. You are prompted to confirm that you wish to delete the mapping from the designated profile. Click OK to proceed. The mapping is removed from the Application directories list. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-13

100 Managing Applications and Paths in the Web Console Note: Any APP PATH commands that reference the deleted APP MAP will not be changed by this action. To remove the previously mapped application from the path, select it in the APP PATH box and click the Delete icon above the box. Filtering Synonyms and Procedures How to: Filter Synonyms in the Metadata Tree in the Web Console Filter Procedures and HTML Files in the Procedures Tree in the Web Console You can limit the synonyms, procedures, and HTML files that appear in the application tree. Procedure: How to Filter Synonyms in the Metadata Tree in the Web Console You can limit the synonyms that appear in the application tree on the Web Console s Metadata Page by applying a filter. Your filtering selections apply to all applications displayed in the navigation pane. 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Filter icon above the navigation pane. The Filter Metadata pane opens iway Software

101 Creating and Working With Applications 3. Click the Filter by drop-down list and choose: Name to filter on a synonym name. Adapter to filter on the adapter (or data source) type that follows the synonym name in the listing on the Metadata navigation pane. Remarks to filter on remarks in the synonym s Filename section. For example: FILE=, SUFFIX=,... REMARKS='Inventory',$ 4. In the Containing input box, enter the string you wish to filter on. The procedure will be displayed if the letter combination appears anywhere in the item selected from the drop-down list. Note that these entries are case sensitive. 5. Click Set Filter. The Filter Status page confirms that the filter was set. The Filter icon is superimposed on the folder icon in the navigation pane. Note: You can remove the filter by clicking the Clear Filter button. Procedure: How to Filter Procedures and HTML Files in the Procedures Tree in the Web Console By default, only procedures are listed in the application tree on the Procedures pane, but, by applying a filter, you can show the procedures and/or HTML files in the application tree. Your filtering selections apply to all application displayed in the navigation pane. 1. If you are not already at the Application Configuration pane, do one of the following: In the Web Console, select Procedures or Metadata from the menu bar. In the DMC, right-click the server name and choose Access Web Console, Procedures or Manage Metadata. The Procedures or Metadata pane opens. 2. Click the Filter icon above the navigation pane. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-15

102 Managing Applications and Paths in the Web Console The Filter Procedures Tree pane opens. 3. Click the Filter by drop-down list and choose: Name to filter on a procedure name. Description to filter on the Description keyword (-*DM_REQ_DESC=) in DataMigrator flows. 4. In the Containing input box, enter the string you wish to filter on. The procedure is displayed if the letter combination appears anywhere in the item selected from the drop-down list. Note that these entries are case sensitive. 5. In the File format box, choose Procedure, HTML or Both Procedure and HTML. The list in the navigation pane displays files in the selected format(s). 6. Click Set Filter. The Filter Status page confirms that the filter was set. The Filter icon is superimposed on the folder icon in the navigation pane. Note: You can remove the filter by clicking the Clear Filter button iway Software

103 Managing Application Files on the Web Console How to: Refresh Synonyms in an Application Copy Synonyms or Procedures From One Application to Another Move Synonyms or Procedures From One Application to Another Drop Synonyms or Delete Procedures From an Application Creating and Working With Applications You can copy and move one or more synonyms or procedures between applications, delete one or more synonyms or procedures from applications, and refresh one or more synonyms in applications. Synonyms. You can copy, move, refresh, and delete individual or multiple synonyms from the Manage Synonyms pane. To see additional information for each listed synonym, select the Extended check box and click Refresh Page. The pane now includes columns for Size, Date Modified, Real Table Name, and Connections. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-17

104 Managing Applications and Paths in the Web Console Procedures. You can copy, move, and delete procedures from the Manage Procedures pane. To see additional information for each listed procedure, select the Extended check box and click Refresh Page. The pane now includes columns for Size and Date Modified. Procedure: How to Refresh Synonyms in an Application 1. From the Metadata navigation pane, click an application and choose Manage Files from the menu. The Manage Synonyms pane for the selected application opens. 2. From the list of synonyms at the bottom of the pane, click check boxes for the synonyms you wish to refresh. To refresh all listed synonyms in the selected application, click the check box at the top of the column. 3. Click the Refresh Synonyms button. Procedure: How to Copy Synonyms or Procedures From One Application to Another 1. From the Metadata or Procedures navigation pane, click an application and choose Manage Files from the menu. The Manage Synonyms or Manage Procedures pane for the selected application opens. 2. To copy files into another application on your path, select that application name from the Application for Copy/Move drop-down list iway Software

105 Creating and Working With Applications 3. From the list of Synonyms or Procedures at the bottom of the pane, click check boxes for the file(s) you wish to copy. To copy all listed files from one application to another, click the check box at the top of the column. 4. Click the Copy button. A confirmation page indicates that the file or files have been successfully copied. 5. Click the Refresh icon above the navigation pane to update the affected applications. Tip: Alternatively, expand the Application Directories folder, expand a specific application folder, click a synonym or procedure, and choose Copy synonym or Copy (procedure) from the menu. Then select the application to which you want to copy the designated component. To copy a group, click the icons of the components (check marks identify the group), then right-click any marked component and select Copy marked to>. Then select the application to which you want to copy the group. From the Web Console, you can only copy two file types: synonyms and procedures. If you need to copy other file types, see Designating File Types for APP Commands. Procedure: How to Move Synonyms or Procedures From One Application to Another 1. From the Metadata or Procedures navigation pane, click an application and choose Manage Files from the menu. The Manage Synonyms or Manage Procedures pane for the selected application opens. 2. To move files into another application on your path, select that application name from the Application for Copy/Move drop-down list. 3. From the list of Synonyms or Procedures at the bottom of the pane, click check boxes for the file(s) you wish to move. To move all listed files from one application to another, click the check box at the top of the column. 4. Click the Move button. A confirmation page indicates that the file or files have been successfully moved. 5. Click the Refresh icon above the navigation pane to update the affected applications. Tip: Alternatively, expand the Application Directories folder, expand a specific application folder, click a synonym or procedure, and choose Move synonym or Move (procedure) from the menu. From a secondary menu, select the application to which you want to copy the designated component. To copy a group, click the icons of the components (check marks designate those that form the group), then right-click any marked component and select Copy marked to>. From a secondary menu select the application to which you want to copy the group. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-19

106 Managing Applications and Paths in the Web Console From the Web Console, you can only move two file types: synonyms and procedures. If you need to move other file types, see Designating File Types for APP Commands. Procedure: How to Drop Synonyms or Delete Procedures From an Application 1. From the Metadata or Procedures navigation pane, click an application and choose Manage Files from the menu. The Manage Synonyms or Manage Procedures pane for the selected application opens. 2. From the list of Synonyms or Procedures at the bottom of the pane, click check boxes for the file(s) you wish to remove. To remove all listed files from the selected application, click the check box at the top of the column. 3. For synonyms, click the Drop button. For procedures, click the Delete button. 4. Click the Refresh icon above the navigation pane to update the affected applications. Tip: Alternatively, expand the Application Directories folder, expand a specific application folder, click a synonym or procedure, and choose Drop synonym or Delete (procedure) from the menu. To delete a group, click the icons of the components (check marks designate those that form the group), then right-click any marked component and select Drop marked or Delete marked. From the Web Console, you can only copy two file types: synonyms and procedures. If you need to copy other file types, see Designating File Types for APP Commands iway Software

107 Creating and Working With Applications Managing Applications and Paths in the Data Management Console On the Windows platform, you can manage your applications from the Data Management Console (DMC) as an alternative to Web Console. On the DMC, the Metadata or Procedures navigation panes provide a set of context sensitive menus at three levels of the application tree: Application Directories folder. Right-clicking this folder at the top of the application tree opens a menu from which you can filter metadata or procedures, append applications to the current application path, create applications, map applications to other locations in the file system, and define the search path. The same options are available on for Metadata and Procedures. Individual application folder. Right-clicking a folder for a specific application, like ibisamp, opens a menu from which you can refresh the application list and create a synonym or a procedure. Individual component in an application. Right-clicking a synonym or procedure component opens a menu from which you can: Copy a procedure or synonym from one application to another using the standard Windows technique. In fact, since the DMC displays multiple servers, you can copy procedures and synonyms across servers using the familiar copy/paste approach. Delete a procedure or synonym from an application. Rename a synonym or procedure using the standard Windows technique. The DMC is available on the Windows platform for all iway Servers: Reporting, Full- Function, and DataMigrator. Since the DMC is the primary interface used by DataMigrator, details about application management from the DMC are described in Managing Application Directories and Configuring the Application Path in Chapter 12, Setting Up DataMigrator. Application Commands Overview Reference: APP Commands Quick Reference This topic lists the platform-independent application (APP) commands that enable you to control the application environment. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-21

108 Application Commands Overview Reference: APP Commands Quick Reference Click any command in the following charts to access detailed information, including the required syntax. Search Path Management Commands Command APP PATH APP PREPENDPATH APP APPENDPATH APP MAP APP SHOWPATH Description Sets or resets the application search path. For details, see APP PATH on page Temporarily adds application names to the beginning of an existing APP PATH search path. For details, see APP PREPENDPATH on page Temporarily adds application names to the end of an existing APP PATH search path. For details, see APP APPENDPATH on page Defines a virtual application that points to a physical location outside of the approot structure. This command makes the virtual application available for addition to the search path; it does not automatically add it to the APP PATH. For details, see APP MAP on page Lists all the currently active applications in the search path. For details, see APP SHOWPATH on page iway Software

109 Creating and Working With Applications Application Management Commands Command APP CREATE APP DELETE APP RENAME Description Creates an application under the approot location. For details, see APP CREATE on page Deletes an application. For details, see APP DELETE on page Renames an application. For details, see APP RENAME on page File Management Commands Command APP COPY APP COPYF[ILE] APP MOVEF[ILE] APP RENAMEF[ILE] APP DELETEF[ILE] Description Copies the contents of one application to a second application. For details, see APP COPY on page *Copies a single component from one application to another. For details, see APP COPYF on page *Moves a single component from one application to another. For details, see APP MOVEF on page *Renames a single component in an application. For details, see APP RENAMEF on page *Deletes a single component of an application. For details, see APP DELETEF on page * The shortened form of the APP commands is used in the remainder of this document. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-23

110 Application Commands Overview Output Redirection Commands Command APP HOLD APP HOLDDATA APP HOLDMETA APP FI[LEDEF] Description Controls where output files are created for any write process in the application, unless an APP FI command has been used to allocate data files. For details, see APP HOLD on page Designates an application as the location for temporary data files created with the HOLD command. For details, see APP HOLDDATA on page Designates an application as the location for temporary Master and Access Files created with the HOLD command. For details, see APP HOLDMETA on page *Provides a platform-independent mechanism for allocating data files. For details, see APP FI[LEDEF] on page * The shortened form of the APP commands is used in the remainder of this document. Report and Help Commands Command APP HELP APP LIST app [HOLD] Description Displays a list of APP commands with a brief description of each. For details, see APP HELP on page Lists the applications under approot. If the HOLD option is used, it lists the applications under approot and writes the output to a temporary file called focappl.ftm, which you can then use in a report request. For details, see APP LIST on page iway Software

111 Creating and Working With Applications Command APP QUERY app [HOLD] Description Lists all files in the application. If the HOLD options is used, it lists all files in the application and writes the output to a temporary file called focappq.ftm, which you can then use in a report request. For details, see APP QUERY on page Search Path Management Commands The server has a default search path for application and system components. You can supplement this search path by using one or more of the following APP commands: In this section: APP PATH APP PREPENDPATH APP APPENDPATH APP MAP APP SHOWPATH APP PATH APP PREPENDPATH APP APPENDPATH Generally, these commands add applications to the beginning of the default search path. The exception is temporary components that are created in the current session. These temporary components are searched first, before the user defined path. You can issue the APP PATH command manually or set the application search path from the Web Console or the Data Management Console. When you configure the application path from the Web Console or the Data Management Console, the APP PATH command is stored in a selectable profile (global, group, or user). The global profile, edasprof, is the default. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-25

112 Search Path Management Commands APP PATH How to: Add an Application to the Search Path Manually The APP PATH command sets the search path to a designated list of application names that refer to single-level names under the approot value. You can specify multiple application names to extend the search path. Syntax: How to Add an Application to the Search Path Manually APP PATH appname1 [appname2] [appname3][[-] [appnamen...]] where: appname1...appnamen Are application names. If you need to specify more application names than can fit on one line, add the continuation character (-) at the end of the first line, and code more application names on the next line. Note: You can use the APP PATH command without an application name to reset the search path to the initial list. APP PREPENDPATH How to: Add Application Names to the Beginning of a Search Path The APP PREPENDPATH command enables you to temporarily add application names to the beginning of an existing APP PATH search path. If you wish to use this command to alter the search path, you must code it manually in your application. Syntax: How to Add Application Names to the Beginning of a Search Path APP PREPENDPATH appname1 [appname2] [appname3][[-] [appnamen...]] where: appname...appnamen Are application names. If you need to specify more application names than can fit on one line, add the continuation character (-) at the end of the first line, and code more application names on the next line. Tip: You can perform this task from the Web Console iway Software

113 Creating and Working With Applications APP APPENDPATH How to: Add Application Names to the End of a Search Path The APP APPENDPATH command enables you to temporarily add application names to the end of an existing APP PATH search path. If you wish to use this command to alter the search path, you must code it manually in your application. Syntax: How to Add Application Names to the End of a Search Path APP APPENDPATH appname1 [appname2] [appname3][[-] [appnamen...]] where: appname1...appnamen Are application names. If you need to specify more application names than can fit on one line, add the continuation character (-) at the end of the first line, and code more application names on the next line. APP MAP How to: Map a Physical File Location Outside of APPROOT Manually Map DDNAME Allocations Example: Sample APP MAP Commands Mapping DDNAME Allocations Reference: APP MAP With Universal Naming Convention (UNC) The APP MAP command allows you to assign an application name to a non-approot application anywhere in the file system. This application name becomes a virtual application under approot, which can be referenced in an APP PATH command and any other APP command that takes an application name as a parameter. Note that mapping does not automatically add a directory to the path; it simply makes it available for addition to the search path. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-27

114 Search Path Management Commands Syntax: How to Map a Physical File Location Outside of APPROOT Manually APP MAP virtualname real_location where: virtualname Is an application name of up to 64 characters that can later be used in an APP PATH command. real_location Is a real full path name or DDname in the native style of the given operating system. Note that if the real location contains spaces, it must be surrounded by double quotation marks. Note: On i5/os, the APP MAP command can only be used to map an IFS directory and not a QSYS library. Example: Sample APP MAP Commands Basic example for Windows: APP MAP test c:\temptest\ Note that if a path name contains spaces, the name must be surrounded by double quotation marks. For example: APP MAP test "c:\temp test\" Syntax: How to Map DDNAME Allocations For the Unified Server (HFS and PDS deployments), the syntax for this type of mapping is APP MAP appnname file_extension=//dd:ddname;file_extension=//dd:ddname;... where: appname Is the name of the application used to reference this mapping in an APP PATH, APP APPENDPATH, or APP APPPREPEND command iway Software

115 file_extension Is one of the following valid server file extensions:.mas.fex.acx.htm.sty.gif.psb Creating and Working With Applications ddname Is the ddname of the allocation you wish to map. The allocation can be performed using JCL code or a DYNAM command. Example: Mapping DDNAME Allocations DYNAM ALLOC FILE MYMAS DA EDAARH.MASTER.DATA SHR REU APP MAP APP1 MAS=//DD:MYMAS; APP APPENDPATH APP1 By default, the server has an APP MAP command in the edasprof.prf file to map the application MVSAPP to the allocations FOCEXEC, MASTER, ACCESS, HTML, FOCSTYLE, GIF, FOCPSB. While allocations of these ddnames are not required for the APP MAP command to be valid, once the ddnames are allocated by JCL or DYNAM commands, they become available for use. Reference: APP MAP With Universal Naming Convention (UNC) On platforms that support Universal Naming Convention (UNC), you must use the UNC to designate a network drive to access APP directories. The UNC must: Be minimally one folder below the initial shared location. Not contain spaces unless enclosed in single quotation marks. For example, \\mynode\myshare\accnting '\\mynode\my share\accnting' Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-29

116 Search Path Management Commands APP SHOWPATH How to: List Active Applications Example: Listing Active Applications in the Search Path THE APP SHOWPATH command lists all the currently active applications in the search path, including baseapp, which is always last. This list mirrors the list of applications displayed in the applications tree on the navigation. pane. Syntax: Example: How to List Active Applications APP SHOWPATH Listing Active Applications in the Search Path The iway Server is generally installed with two default applications: ibisamp (contains sample files), and baseapp (which can contain any files you create). The APP SHOWPATH command generates the following output is: ibisamp baseapp 5-30 iway Software

117 Application and File Management Commands In this section: APP CREATE APP COPY APP COPYF APP MOVEF APP DELETE APP DELETEF APP RENAME APP RENAMEF Designating File Types for APP Commands Creating and Working With Applications The APP commands in this section provide management options for applications and their component files. APP CREATE How to: Create an Application Manually Change Default Characteristics of Component File Types (PDS Deployment Only) Example: Changing Default Characteristics of an Application (PDS Deployment) In general, the APP CREATE command creates an application under the approot location. The exception is a PDS deployment on a Unified Server, where an application is a physical entity and each of its component file types is stored in a separate PDS. The APP CREATE command can create any number of applications with one command. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-31

118 Application and File Management Commands Syntax: How to Create an Application Manually APP CREATE appname1 [appname2] [appname3][[-] [appnamen...]] where: appname1...appnamen Are application names. The application name can be up to 64 characters. The application name may not contain spaces. If the name contains spaces, each section is understood to be a separate application. If you require a name with spaces, you must create it using another mechanism, such as the Windows Explorer. You can then use the APP MAP command to add it to APPROOT. If you need to specify more application names than can fit on one line, add the continuation character (-) at the end of the first line, and code more application names on the next line. The word HOLD cannot be used as an application name. Syntax: How to Change Default Characteristics of Component File Types (PDS Deployment Only) If you are working on a Unified Server in PDS deployment, you can change the default characteristics of individual component file types by issuing a DYNAM SET APP command. This command controls the types of component files that are generated for the application when an APP CREATE command is issued. By default, all component file types are generated. The syntax is DYNAM SET APP FOR filetype [SKIP CREATE] [POSTFIX aaa.bbb] [parms] where: filetype Are the component types that may be affected by this command: FOCEXEC, MASTER, ACCESS, HTML, GIF, FOCSTYLE, MAINTAIN, WINFORMS, ETG. You must issue a separate command for each component type you wish to affect. SKIP Indicates that the designated file type should not be created when the APP CREATE command is issued. CREATE Creates the designated file type when the APP CREATE command is issued. This is the default setting iway Software

119 POSTFIX Creating and Working With Applications Specifies the lower level qualifier of the DSN (data set name) for the component type. The APPROOT value is used to complete the full DSN, which is expressed as approotvalue.appname.component_type The default value for component_type is filetype.data. parms Are the allocation parameters you can set. The default parameter values are: Filetype Parms FOCEXEC RECFM VB TRKS LRECL 4096 BLKSIZE SPACE DIR 50 MASTER RECFM FB TRKS LRECL 80 BLKSIZE SPACE DIR 50 ACCESS RECFM FB TRKS LRECL 80 BLKSIZE SPACE DIR 50 HTML RECFM VB TRKS LRECL 4096 BLKSIZE SPACE DIR 50 GIF RECFM VB TRKS LRECL 4096 BLKSIZE SPACE DIR 50 The GIF filetype creates libraries for GIF and JPG files. FOCSTYLE RECFM FB TRKS LRECL 1024 BLKSIZE SPACE DIR 50 MAINTAIN RECFM VB TRKS LRECL 4096 BLKSIZE SPACE DIR 50 WINFORMS RECFM VB TRKS LRECL 4096 BLKSIZE SPACE DIR 50 ETG RECFM FB TRKS LRECL 80 BLKSIZE SPACE DIR 50 Example: Changing Default Characteristics of an Application (PDS Deployment) The following command indicates that GIF files should not be created when the APP CREATE command is issued. DYNAM SET APP FOR GIF SKIP The following command indicates that Procedures (FOCEXECs) should be created when APP CREATE is issued. DYNAM SET APP FOR FOCEXEC TRKS SP DIR 30 Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-33

120 Application and File Management Commands APP COPY How to: Copy an Application The APP COPY command copies the entire contents of one application to another. The target application must already exist. Syntax: How to Copy an Application APP COPY appname1 appname2 where: appname1 Is the application being copied. appname2 Is the application to which the contents of the first application are being copied. APP COPYF How to: Copy an Application Component Manually The APP COPYF command copies a single component from one application to another. Note that if you copy the component manually, you can, optionally, rename it in the process. Syntax: How to Copy an Application Component Manually APP COPYF appname1 filename1 filetype1 appname2 filename2 filetype2 where: appname1 Is the application that contains the component to be copied. filename1 Is the component to be copied. filetype1 Is the file type of the component to be copied iway Software

121 appname2 Is application to which the named component is being copied. filename2 Creating and Working With Applications Is the component in the second application, after the copy process. filetype2 Is the component type in the second application, after the copy process. For a full list of the types of files you can copy with APP commands, see Designating File Types for APP Commands on page APP MOVEF How to: Move an Application Component Manually The APP MOVEF command moves a single component from one application to another. Note that if you move the component manually, you can, optionally, rename it in the process. Syntax: How to Move an Application Component Manually APP MOVEF appname1 filename1 filetype1 appname2 filename2 filetype2 where: appname1 Is the application name of the component being moved. filename1 Is the component name to be moved. filetype1 Is the file type of component to be moved. appname2 Is the application name to which the component of the first application is being moved. filename2 Is the component name, in the second application, after the move process. filetype2 Is the component type, in the second application, after the move process. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-35

122 Application and File Management Commands For a full list of the types of files you can copy with APP commands, see Designating File Types for APP Commands on page APP DELETE How to: Delete an Application Manually The APP DELETE command deletes an application under approot. Syntax: How to Delete an Application Manually APP DELETE appname1 [appname2] [appname3][[-] [appnamen...]] where: appname1...appnamen Are application names. If you need to specify more application names than can fit on one line, add the continuation character (-) at the end of the first line, and code more application names on the next line. APP DELETEF How to: Delete an Application Component Manually The APP DELETEF command deletes a component in an application. Syntax: How to Delete an Application Component Manually APP DELETEF appname filename filetype where: appname Is the application from which the component is being deleted. filename1 Is the component to be deleted. filetype Is the component type of the file to be deleted. For a full list of the types of files you can copy with APP commands, see Designating File Types for APP Commands on page iway Software

123 Creating and Working With Applications APP RENAME How to: Rename an Application Example: Renaming an Application The APP RENAME command renames an existing application. Note: You cannot rename an application if it is active in the search path. Syntax: How to Rename an Application APP RENAME appname1 appname2 where: appname1 Is the application name to be renamed. appname2 Is the new application name of up to 64 characters. Example: Renaming an Application The following shows APP1 being renamed to APP2. APP RENAME APP1 APP2 Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-37

124 Application and File Management Commands APP RENAMEF How to: Rename an Application Component The APP RENAMEF command renames a single component in an application. Syntax: How to Rename an Application Component APP RENAMEF appname filename1 filename2 filetype where: appname Is the name of the application that contains the component being renamed. filename1 Is the component to be renamed. filename2 Is the new name for the component. The component name may be up to 64 characters and must not already exist since APP RENAME will not overwrite an existing name. filetype Is the component type of the file name to be renamed. For a full list of the types of files you can copy with APP commands, see Designating File Types for APP Commands on page Designating File Types for APP Commands Reference: APP Commands and File Types The APP COPYF, APP MOVEF, APP DELETEF, and APP RENAMEF commands enable you to perform their actions on a wide variety of filetypes. Reference: APP Commands and File Types The following is a comprehensive list of the file types you can use with APP commands and the file extensions associated with the on-disk names for hierarchical file systems. Note that the file types must be coded in uppercase in any APP command that requires it iway Software

125 Creating and Working With Applications Note: This list reflects file types supported across all IBI products and release levels. Particular file types may not be supported in particular releases or with every product. Filetype MASTER FOCSQL OMI HLI FOCEXEC EDAPROF MNTPAINT EDANLS ERRORS MAINTAIN WINFORMS FOCCOMP FOCSTYLE FOCFTMAP AFM HTML TXT PS GIF TDL BMP EXCEL ADR BST EPS File Extension.mas.acx.omi.hli.fex.prf.mpt.nls.err.mnt.wfm.fcm.sty.fmp.afm.htm.txt.ps.gif.tdl.bmp.xls.adr.bst.eps Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-39

126 Application and File Management Commands Filetype PDF XHT XML XSL TABS SMARTLIB FOCUS IBICPG TTEDIT FOCTEMP DATA TRF FMU DDS FOCDEF PFA FOCPSB PFB CONTROL LSN DTD ETL EDAPRFU ETG XSD WSDL File Extension.pdf.xht.xml.xsl.txt.knb.foc.sl.tte.ftm.dat.trf.fmu.DDS.def.pfa.psb.pfb.ctl.lsn.dtd.etl.prf.etg.xsd.wsd 5-40 iway Software

127 Creating and Working With Applications Filetype JPG SVG PNG EDAPSB MHT SQL JS Cascading Stylesheet Microsoft Access database File Extension.jpg.svg.png.psb.mht.sql.js.css.mdb Output Redirection Commands In this section: APP HOLD APP HOLDDATA APP HOLDMETA APP FI[LEDEF] Reference: Interactions Among Output Redirection Commands Four APP commands APP HOLD, APP HOLDDATA, APP HOLDMETA, APP FI[LEDEF] along with the FILEDEF and DYNAM commands comprise a class of commands that control where output is stored. In order to redirect output as you wish, it is important to understand the interactions among these commands. Note: When the same behavior applies for APP HOLD, APP HOLDDATA, APP HOLDMETA, APP FI[LEDEF], we have referred to these commands collectively as APP HOLD*. Note also that although DYNAM (USS only) and FILEDEF are not members of the APP family of commands, these file allocation commands interact with the APP HOLD* commands. Therefore, where appropriate, these commands are also included in this discussion. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-41

128 Output Redirection Commands The most straight forward of these commands is APP HOLD, which allows you to relocate all output to a particular application. You can use this command with operations that produce output files, such as HOLD, SAVE and SAVB, as well as with CREATE SYNONYM, APP QUERY HOLD, and focsort. The APP HOLD* commands are particularly helpful when you are creating permanent files for other applications to use. However, if a command is used at an inappropriate point in the application or if it remains in effect when further steps are performed within the application, the target application may be flooded with intermediate and unintended files. Understanding the behavior of each command and the interactions among them will help you avoid this situation. Reference: Interactions Among Output Redirection Commands This chart describes the behavior associated with each redirection command and the interactions among them if multiple commands are used. Command Stand Alone Notes APP HOLD APP HOLDDATA APP HOLDMETA Redirects all Agent output to the designated application. Redirects the data from HOLD, SAVE, and SAVB operations to the designated application, but does not redirect the associated metadata (see Note 1 after chart). Redirects the metadata from HOLD, SAVE, and SAVB operations to the designated application, but does not redirect the associated data. (See Note 1 after chart.) When issued without a specific appname, APP HOLD has the effect of turning off the command. Overrides APP HOLD Overrides APP HOLD 5-42 iway Software

129 Creating and Working With Applications Command Stand Alone Notes FILEDEF ddname APP FI[LEDEF] ddname DYNAM ddname FILEDEF HOLDMAST APP FI[LEDEF] HOLDMAST DYNAM HOLDMAST Note: Redirects the data from specific HOLD, SAVE, and SAVB operations to the designated target, but does not redirect the associated metadata (see Note 1 after chart). The request's AS phrase must match the ddname. When there is no AS phrase, the ddname must match a predefined default name: HOLD for HOLD output files; SAVE for SAVE output files; and SAVB for SAVB output files. Redirects the metadata from HOLD, SAVE, and SAVB operations to the designated target (using the HOLDMAST ddname), but does not redirect the associated data. (See Note 1 after chart.) The recommended practice is to use this command on a requestby-request basis to avoid overriding previous output. If used as a global setting, previously held output will be overwritten with the same name. Overrides APP HOLD and APP HOLDDATA Overrides APP HOLD and APP HOLDMETA Not all formats have associated metadata. For example, the HOLD FORMAT PDF command does not produce metadata, therefore, there is no metadata to redirect. The use of the APP HOLD command to redirect CREATE SYNONYM output is neither necessary nor desirable since the CREATE SYNONYM command directly supports application names using the syntax: CREATE SYNONYM appname/synonym Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-43

130 Output Redirection Commands APP HOLD How to: Designate a Storage Location for Temporary Files The APP HOLD command defines an application in which to hold output data files (and associated Master and Access Files, if applicable) created by a HOLD, SAVE, or SAVB process in the application. APP HOLD is intended to be used to refresh files that are common for all users of the application. It should not be used for private files since it points to an application area that is used by multiple users. If the same hold name (HOLD or AS name, for example) is used, conflicts between users could result. For related information, see Interactions Among Output Redirection Commands. Syntax: How to Designate a Storage Location for Temporary Files APP HOLD appname where: appname Is the application in which you wish to store output files. Note: Issuing APP HOLD without an appname turns off the effects of the command. APP HOLDDATA How to: Designate a Storage Location for Data Files The APP HOLDDATA command designates an application as the location for storing data files created with the HOLD command. For related information, see Interactions Among Output Redirection Commands. Syntax: How to Designate a Storage Location for Data Files APP HOLDDATA appname where: appname Is the name of the location for the data files created by any write process in the application iway Software

131 Creating and Working With Applications APP HOLDMETA How to: Designate a Storage Location for Master and Access Files The APP HOLDMETA command designates an application directory as the location for storing Master and Access Files created in the application. For related information, see Interactions Among Output Redirection Commands. Syntax: How to Designate a Storage Location for Master and Access Files APP HOLDMETA appname where: appname Is the name of the location for the Master and Access Files created in the application. APP FI[LEDEF] How to: Specify a Physical File Location for Data Files The APP FI[LEDEF] command provides a platform-independent mechanism for allocating data files. For related information, see Interactions Among Output Redirection Commands. Syntax: How to Specify a Physical File Location for Data Files APP FI[LEDEF] filename DISK appname/physical_name where: filename Is the logical file name as known by the server. appname Is an application name. physical_name Is the file name to be allocated. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-45

132 Reports and Help Reports and Help The APP commands included in this topic enable you to obtain information about application, their paths, and their components. APP LIST How to: List Components Example: Listing Applications in APPROOT The APP LIST command lists the applications available under the application root, approot. Syntax: Example: How to List the Applications in APPROOT APP LIST [HOLD] If the HOLD option is used, the output is written to a temporary file called focappl.ftm, which can, in turn, be used in a request to drive a report or some other aspect of an application. The field layout of focappl.ftm is described by the Master File focappl.mas. Listing Applications in APPROOT The following request lists applications that have been stored in the HOLD file focappl.ftm. SELECT DATE,TIME,APPNAME FROM FOCAPPL The APP LIST output is: 15/02/ baseapp 15/02/ ggdemo 15/02/ ncp 15/02/ template 5-46 iway Software

133 Creating and Working With Applications APP QUERY How to: List Components Example: Listing Application Components The APP QUERY command lists all components of an application. Any number of applications can be queried with one command. Syntax: How to List Components APP QUERY appname1 [appname2] [appname3][[-] [appnamen...]][hold] where: appname1...appnamen Are application names. If you need to specify more application names than can fit on one line, add the continuation character (-) at the end of the first line, and code more application names on the next line. If the HOLD option is used, the output is written to a temporary file called focappq.ftm, which can, in turn, be used in a request to drive a report or some other aspect of an application. The field layout of focappq.ftm is described by the Master File focappq.mas. Example: Listing Application Components The following request lists the components of an application stored in the output file focappq.ftm. SELECT DATE,TIME,SIZE,FILENAME,APPNAME FROM FOCAPPQ The APP QUERY output is: 08/03/ eas.mas APP1 08/03/ eas.acx APP1 Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-47

134 Restricting the Use of APP Commands APP HELP How to: Request Help for an APP Command The APP HELP command provides help information for all of the APP commands. Syntax: How to Request Help for an APP Command APP HELP command parameters where: command Is any valid APP command. parameters Are parameters that are available to or required by the command. Restricting the Use of APP Commands How to: Restrict the Use of APP Commands Server administrators can restrict the ability of other classes of users to change the APP environment. When this restriction is set, all user interfaces affected by this server setting, such as the Web Console, the Data Management Console, Developer Studio, and Managed Reporting, display only applications that are in the effective application search path, instead of displaying all applications defined by the server s approot setting. In addition, the use of certain APP commands that users might otherwise issue to bypass the intended controls is restricted. To ensure full administrative capabilities, the restriction is dynamically switched off when a user who has server administration rights logs on from client software or to the Web Console. This capability is supported with all security settings. Procedure: How to Restrict the Use of APP Commands The server administrator can restrict the use of APP commands by other users. 1. On the Web Console menu bar, select Workspace, then Access Control iway Software

135 Creating and Working With Applications 2. Click the Privilege folder in the navigation pane. The Privilege pane opens. 3. In the Administrative Level field, select a user type from the drop-down list. The options are: Basic User, Application Administrator, and Server Operator. 4. In the Administrative Privilege field, deselect the Modify Application Path check box. 5. Click Apply to confirm the setting. Once modification of the application path is blocked, use of the following APP commands is restricted for the designated class of users: The following commands cannot be used. An error message is generated if they are issued. APP CREATE APP DELETE APP RENAME Although no error message is explicitly generated, use of the following commands is restricted if they reference an application outside of the current application path. APP APPENDPATH APP HOLD APP HOLDDATA APP HOLDMETA APP MAP APP PATH APP PREPENDPATH APP COPY APP COPYF[ILE] APP DELETEF[ILE] APP MOVEF[ILE] APP RENAMEF[ILE] Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-49

136 Accessing Metadata and Procedures Accessing Metadata and Procedures In this section: Search Rules Creation Rules for Procedure Files Locating Master Files and Procedures Accessing Existing Data Files Creation Rules for Data Files Data Set Names Permanent files include metadata and procedures that were either created before the session by another application or remain after the session is over for use by another application. Search Rules Unless a file name is fully qualified with the application name, the search rules are 1. The application set using APP HOLDMETA command. 2. The list of applications set in APP PATH (including MVSAPP for z/os). 3. The baseapp application. 4. The EDAHOME/catalog. 5. For stored procedures only: if the file is not found, the server checks to see if the file was allocated with a FILEDEF or DYNAM command, and if so, tries to execute it. Example: Search Paths The following command follows the search path, starting with the application set by the APP HOLDMETA command: EX ABC The next command first executes profile.fex in the application pointed to by APP1, then searches for and executes the procedure ABC: EX APP1/ABC 5-50 iway Software

137 Creating and Working With Applications Creation Rules for Procedure Files Unless a file name is fully qualified or redirected to another location using an APP HOLD, APP HOLDMETA, APP HOLDDATA, FILEDEF, or DYNAM command, it is created in the agent s temporary application area and disappears after the agent is released. For example, on z/os if DYNAM allocation for HOLDMAST or HOLDACC is present, the metadata files are created in the corresponding PDSs (for example, for a CREATE SYNONYM or TABLE FILE file with HOLD). For related information, see Output Redirection Commands on page Locating Master Files and Procedures Once your path is set, you can locate Master Files and procedures using the WHENCE command. Syntax: How to Locate Master Files and Procedures To locate a Master File or procedure, issue the following command WHENCE filename filetype where: filename Is the name of the file you are trying to locate. filetype Is the type of file you are trying to locate. Accessing Existing Data Files You can allocate existing data files using the following methods: DATASET keyword in the Master File. FILEDEF command for non-focus data sources FIXED, RMS, VSAM, XML. USE command for FOCUS data sources. For the z/os Server, native operating system services, when supported. DYNAM command as a USS equivalent for the MVS ALLOCATE command. Superseded by JCL DD card. It is recommended that you use only one method for each allocation. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-51

138 Accessing Metadata and Procedures Creation Rules for Data Files How to: Issue a FILEDEF Command Issue a FILEDEF Command for a Native MVS Dataset Example: Sample Allocations by JCL Samples DYNAM Commands Sample USE Commands For a newly created data file, the location is determined as follows: 1. An application set by APP HOLDDATA applies to all HOLD files. 2. For FILEDEF command, one for each data file. 3. For z/os, native operating system allocations when supported. The request that caused the file to be created determines the file's DCB parameters, such as record length, record format, and so on. For related information, see Output Redirection Commands on page Example: Sample Allocations by JCL The following table contains sample allocations by JCL. VSAM Fixed PDS //VSAM01 DD DISP=SHR, DSN=qualif.DATA.VSAM This type of allocation requires the szero = y parameter in the edaserve.cfg file to support sharing of BufferPool Zero. //FIX01 DD DISP=SHR,DSN=qualif.FIXED.DATA //MASTER DD DISP=SHR,DSN=qualif.MASTER.DATA FOCUS //CAR DD DISP=SHR,DSN=qualif.CAR.FOCUS 5-52 iway Software

139 Creating and Working With Applications Example: Samples DYNAM Commands The following table contains samples of the DYNAM command. VSAM Fixed PDS FOCUS DYNAM ALLOC FILE QVASM DA qualif.qvsam.vsam SHR REUSE DYNAM ALLOC FILE FILE1 DA qualif.file1.data SHR REUSE DYNAM ALLOC FILE MASTER DA qualif.master.data SHR REUSE DYNAM ALLOC FILE CAR DA qualif.car.focus SHR REU Syntax: How to Issue a FILEDEF Command FI filedes DISK app/physfile.ftm where: filedes Is a file designation. physfile.ftm Is a physical file located in the application pointed to by app. Syntax: How to Issue a FILEDEF Command for a Native MVS Dataset FI filedes DISK "//'NATIVE.MVS.DATASET'" where: filedes Is a file designation. NATIVE.MVS.DATASET Is a Native MVS data set. It can contain any number of qualifiers, up to 44 characters long. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-53

140 Accessing Metadata and Procedures Example: Sample USE Commands The USE command supports renaming of Master Files and concatenation of data sets. The USE command is the only mechanism for accessing files on the sink machine. Renaming a Master File USE CAR1 ON CAR END Concatenating Master Files USE CAR1 as CAR CAR2 as CAR END Accessing Files on a Sink Machine USE CAR1 AS FOCSU01 END Data Set Names If a data set name satisfies one of the following conditions, the server assumes that it is an MVS file name: Data set name starts with //. Data set name contains no / and contains at least one. In all other cases, the name is interpreted as an HFS file name. Syntax: How to Define a Data Set The following syntax is supported: DATASET=APP1/physfile.ftm DATASET='qualif.car.data' DATASET=qualif.car.data In addition, on z/os, you can use the following: GDG files PDS members FILENAME=CARGDG,SUFFIX=FOCUS, DATASET='qualif.CARGDG.FOCUS(0)' FILENAME=CARMEMB,SUFFIX=FOCUS, DATASET=qualif.CARPDS.DATA(CARMEMB) 5-54 iway Software

141 Creating and Working With Applications FOCUS, VSAM, Fixed FILENAME=CAR,SUFFIX=FOCUS, DATASET=//'qualif.CAR.FOCUS' Allocating Temporary Files How to: Allocate Temporary Files Allocate Temporary Files to MVS Data Sets Support Long Synonym Names Using DYNAM SET LONGSYNM Reference: Usage Notes for Allocating Temporary Files System Defaults for Allocating Temporary Files to MVS Data Sets Temporary files are transient files that disappear after you end a session. By default, all temporary data files (for HOLD and FOCSORT files) and temporary metadata files, such as temporary Master Files and Access Files, are created in an agent s temporary area, which corresponds to your TSCOM ID. For example, if your TSCOM ID is TS000001, your temporary files are located in //edatemp/ts For z/os, you can control the size and location of these temporary metadata files and data files. You can specify that the temporary files reside in the hierarchical file system, MVS data sets, or in hiperspace. Syntax: How to Allocate Temporary Files To specify the allocation of your temporary files, issue the following command DYNAM SET TEMP[ALLOC] {HFS MVS HIPER} where: HFS Allocates temporary files to the hierarchical file system. HFS is the default value. MVS Allocates temporary files to MVS data sets. HIPER Allocates temporary files to hiperspace. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-55

142 Allocating Temporary Files Reference: Usage Notes for Allocating Temporary Files For z/os, temporary metadata files can be allocated using a similar procedure to allocating permanent metadata files: If DYNAM allocation for HOLDMAST or HOLDACC is present, temporary files are stored in the designated PDSs. If DYNAM SET TEMP[ALLOC] MVS is issued; in the default temporary PDSs. If DYNAM SET TEMP[ALLOC] HIPER is issued; in the HIPERSPACE. Syntax: How to Allocate Temporary Files to MVS Data Sets To alter the default allocation parameters for temporary files for MVS data sets, issue the following command DYNAM SET TEMP[ALLOC] FOR type dynam_parms where: type Is one of the following: HOLDACC, HOLDMAST, HOLD SAVE, REBUILD, FOCUS, FOCSORT, OFFLINE, or FOC$HOLD. dynam_parms Are regular DYNAM ALLOC parameters to be used as default for that type. Note that DCB parameters, if provided here, will be ignored, since they must be compatible with the file type being written. This is similar to the functionality of IBITABLA in the SSCTL Server. The defaults should be overwritten for all cases when, in older versions, a private copy of IBITABLA existed containing different values. Reference: System Defaults for Allocating Temporary Files to MVS Data Sets System defaults for HOLDMAST and HOLDACC are: TRKS 5 5 DSORG PO DIR 36 NEW REU System defaults for all other types are: CYLS 5 10 DSORG PS NEW REU 5-56 iway Software

143 Creating and Working With Applications Syntax: How to Support Long Synonym Names Using DYNAM SET LONGSYNM The server supports synonym names up to 64 characters. However, PDS member names cannot exceed eight characters. The server accounts for this operating environment limitation with the command DYNAM SET LONGSYNM. A synonym comprises a Master File and, usually, an Access File. When you create a synonym with a name exceeding eight characters, the LONGSYNM setting currently in effect determines how the long name of the Master File and of the Access File will be handled. You can issue DYNAM SET LONGSYNM anywhere SET commands are valid, including the global server profile (edasprof.prf) and a stored procedure (FOCEXEC). DYNAM SET LONGSYNM, on servers running on z/os, corresponds functionally to the server configuration file keyword LONGSYNM on servers running on MVS. The syntax is DYNAM SET LONGSYNM {HFS MVS MATCH} where: HFS Specifies that each synonym whose name is longer than eight characters will be created in an HFS directory. This is the default. MVS Specifies that when you save a synonym with a name exceeding eight characters, the server truncates the name, preserving up to the first 6 characters, followed by a left curly brace ({) and a suffix number that ensures the name s uniqueness. (The server preserves the original long name within the synonym s files.) For example, if you create a Master File named VERYLONGNAMETEST, it will be saved as VERYLO{0. If you then create a Master File named VERYLONGNAMEPROD, it will be saved as VERYLO{1. The server chooses a suffix number by taking the next unused number in the sequence for that truncation of a Master File or Access File name. If the next number available for the Master File is different than that available for the Access File, the files will be created with different numbers. For example, if the highest Master File name truncated to VERYLO is VERYLO{8, and the highest Access File name truncated to VERYLO is VERYLO{5, and you create a synonym specifying the name VERYLONGNAMEAGAIN, the new Master File will be saved as VERYLO{9, and the new Access File will be saved as VERYLO{6. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-57

144 Temporary Space Allocation for UNIX and z/os UNIX System Services MATCH Works the same as the MVS setting, except that it ensures that the truncated names of a synonym s Master File and Access File will always match. That is, they will be named using the same suffix number. In the example provided for the MVS setting, if SET LONGSYNM had instead been set to MATCH, both the new Master File and the new Access File would have been named VERYLO{9. Matching names may be a convenience for some people if they manually manage synonym files. It is less efficient than the MVS setting, however. Temporary Space Allocation for UNIX and z/os UNIX System Services When you perform a standard server installation, a file system is created and mounted. The amount of space that is available to a running server using the file system is approximately n megabytes (where n is the size of available space in the file system before the server is installed). It is important to understand the server s utilization of this space on behalf of the user community and the various techniques that can be employed to control the space used. Temporary File Directory Structure for Non-PDS Deployment How to: Specify the edatemp Variable Pre-Allocate Temporary Files Dynamically Allocate FOCUS Files on z/os Temporary space, by default, is created under the configuration directory (ffs, wfs, or dm) in the file system used to install the product. The edatemp directory is two levels deep. The first level directory is used for trace files if tracing is active. By default, the directory is named /edatemp. The subdirectory is used for temporary files. User s have a private directories in order to isolate each user s work from all others. The subdirectory is named /edatemp/tsnnnnnn where nnnnnn is the running data agent s ID number. The edatemp can be a separate file system to which the variable edatemp points. You can export the edatemp variable before the server is started or set it using by editing the edaserve.cfg configuration file from Web Console Workspace Edit Files option iway Software

145 Creating and Working With Applications Syntax: Syntax: How to Specify the edatemp Variable For UNIX, the edatemp variable can be coded in the edastart.sh file: export EDATEMP=/u/iway/edatemp For UNIX System Services, it can be coded in the ISTART JCL member under the EDAENV dd statement: //EDAENV DD * EDATEMP=/u/iway/edatemp For z/os UNIX System Services only, you can set the temporary area to MVS by using the following command in edasprof.prf or user profile. DYNAM SET TEMPALLOC MVS The above are global settings which affect temporary file allocations for all users. How to Pre-Allocate Temporary Files You can pre-allocate an individual file for a user, using the following techniques: UNIX filedef xxx disk /u/another/area/xxx.dat where /u/another/area has enough free space to hold the file. z/os UNIX System Services You can use the same filedef syntax indicated for UNIX, or you can use the DYNAM command to direct the temporary file to MVS. DYNAM ALLOC FILE xxx SPACE Note that, for the DYNAM command, you must to specify the amount of space required. FOCUS files You can use the FILEDEF and USE commands to create a FOCUS file outside the edatemp area. FILEDEF filename DISK /pathname USE filename NEW END Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 5-59

146 Temporary File Directory Structure for Non-PDS Deployment Syntax: How to Dynamically Allocate FOCUS Files on z/os You can dynamically allocate FOCUS files on z/os with the USE command. The command is DYNAM ALLOC FILE ddname SPACE USE ddname AS masterfile END where: ddname Is the DDNAME. masterfile Is the Master File name. If the DDNAME and Master File name are the same, use just the command: DYNAM ALLOC 5-60 iway Software

147 6 Managing Metadata The data source being used determines the type of metadata that is required. For example, When the server accesses a relational data source, it needs to know how to interpret the data stored there. You must create a synonym that describes the structure of the data source and the server mapping of the data types. When the server invokes a transaction or procedure, it needs to know how to build the request, what parameters to pass, and how to format an answer set from the response. You must create a synonym that describes the layout of the request/response area. Whatever your data source, the adapter you are using manages the synonym creation process for you, creating a synonym that meets your specific requirements. This topic describes briefly how to create, test, and otherwise manage a synonym, using the Web Console or the Data Management Console. Detailed information for each adapter is included in the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual. Topics: Creating Synonyms Testing Synonyms Managing Synonyms

148 Creating Synonyms Creating Synonyms Synonyms define unique names (or aliases) for each table, view, transaction or procedure that is accessible from the server. Synonyms are useful because they hide the underlying data source's location, identity, transaction or procedure from client applications. They also provide support for extended metadata features of the server, such as virtual fields and additional security mechanisms. You can create synonyms for supported adapters from the Web Console or the Data Management Console. The begin the process: How to: Create a Synonym From the Web Console Create a Synonym From the Data Management Console Test a Synonym From the Web Console Test a Synonym From the Data Management Console From the Web Console, click Metadata on the menu bar. From the Data Management Console, click the Metadata tab at the bottom of the navigation pane. Although all synonym creation panes have the same look and feel, the parameters are specific to each adapter. To obtain detailed configuration information for an adapter, see the Adapter Administration UNIX, Windows, OpenVMS, i5/os, and z/os manual. Procedure: How to Create a Synonym From the Web Console To create a synonym, you must have previously configured the adapter. You then: 1. Start the Web Console, if it is not already running, and click Metadata on the menu bar. The Managing Metadata pane opens. 2. Click New Synonym to open a pane called Select configured adapter connection to create synonym. 3. Click a connection for the configured adapter. The first of a series of synonym creation panes opens. 4. Enter values for the parameters required by the adapter. 5. After entering parameter values, click Create Synonym. Synonyms are created and added under the specified application directory. The Status pane indicates that the synonyms were created successfully. 6-2 iway Software

149 Managing Metadata 6. You can click Go to Metadata page where you can manage synonyms from the navigation pane. For details, see Managing Synonyms. Procedure: How to Create a Synonym From the Data Management Console To create a synonym, you must have configured the adapter. Then: 1. In the DMC, right-click an application directory and select New, and then Synonym. The Create Synonym window opens showing the adapters that you have configured. 2. Expand a configured adapter folder, select an adapter version or connection, and click OK. The Server Metadata Creation window opens. 3. Enter values for the parameters required by the adapter. 4. After entering parameter values, click Create Synonym. The synonym is created and added under the specified application directory. The Status field on the Metadata creation window shows that the synonyms were created successfully. Tip: Once you have created synonyms, you can manage them from the Metadata navigation pane. For details, see Managing Synonyms. Testing Synonyms After you have created a synonym, it is good practice to ensure that it is able to retrieve data from a data source. You can quickly test this functionality on a sample of up to 20 rows. Procedure: How to Test a Synonym From the Web Console 1. On the Web Console menu bar, click Metadata. 2. Expand an application folder and click the synonym you wish to test. 3. Select Sample Data from the menu. Sample data is displayed in the right pane. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 6-3

150 Managing Synonyms Procedure: How to Test a Synonym From the Data Management Console 1. Click the Metadata tab below the DMC navigation pane. 2. Expand an application folder and right-click the synonym you wish to test. 3. Select Sample Data from the menu. Managing Synonyms Sample data is displayed in the right pane. Once you have created a synonym, you can click synonym name in the navigation pane of either the Web Console or the Data Management Console to access the following options: Option Open in Synonym Editor Edit as Text Edit Access File as Text Sample Data Data Profiling Refresh Synonym Description Opens the synonym s Master File component in the right pane, for viewing and editing using a graphical interface. Enables you to view and manually edit the synonym's Master File. Note: To update the synonym, it is strongly recommended that you use the graphical interface provided by the Open option, rather than manually editing the Master File. Enables you to view and manually edit the synonym s Access File. Retrieves up to 20 rows from the associated data source. Data Profiling provides the data characteristics for a synonym's columns. Alphanumeric columns provide the count of distinct values, total count, maximum, minimum, and average length, and number of nulls. Numeric columns provide the count of distinct values, total count, maximum, minimum, and average value, and number of nulls. Regenerates the synonym. Use this option if the underlying object has been altered. 6-4 iway Software

151 Managing Metadata Option Data Management Impact Analysis Drop Synonym Move Synonym Copy Synonym Description Followed by these options, if applicable: Recreate DBMS Table. Recreate the data source tables. You are asked to confirm this selection before the tables are regenerated. (Note that the table will be dropped and recreated. During the process, data may be lost.) Delete All Data. Deletes all existing data. You are asked to confirm this selection before the data is deleted. Insert Sample Data. Inserts a specified number of sample records, populating all fields with counter values. Generates reports on procedures, synonyms, and columns that provide information on the flows/stored procedures available on a particular server, and the synonyms and columns they use. These reports enable you to evaluate changes before they are made by showing which components will be affected. See the Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual for details about Impact Analysis Reports. Deletes the synonym. You are asked to confirm this selection before the synonym is deleted. Moves the synonym to another application directory. Click the target directory from the resulting list. Copies the synonym to another application directory. Click the target directory from the resulting list. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 6-5

152 Managing Synonyms 6-6 iway Software

153 7 Unicode Support Unicode is a universal character encoding standard that assigns a code to every character and symbol in every language in the world. Since no other encoding standard supports all languages, Unicode is the only encoding standard that ensures that you can retrieve or combine data using any combination of languages. Topics: Unicode and the WebFOCUS Reporting Server Accessing Unicode Data Selecting, Reformatting, and Manipulating Characters Sort Order Under Unicode Unicode PDF Output

154 Unicode and the WebFOCUS Reporting Server Unicode and the WebFOCUS Reporting Server The WebFOCUS Reporting Server supports a Unicode Transformation Format (UTF) called UTF-8 in ASCII environments, and UTF-EBCDIC in EBCDIC environments: For ASCII, the UTF-8 encoding standard assigns each character of each language a code that can be from one to three bytes long. The codes assigned to European characters are one or two bytes long, Middle Eastern characters are two bytes long, and those assigned to Asian characters are three bytes long. This standard is compatible with ASCII format because the first 128 UTF-8 codes have the same one-byte representation as the corresponding ASCII codes. For EBCDIC, the UTF-EBCDIC encoding standard assigns each character a code that can be from one to four bytes long. EBCDIC characters, including C1 control characters, have the same one-byte representation in UTF-EBCDIC. In non-unicode single-byte encoding standards, such as ASCII, each character is assigned a code that is one byte long, limiting the number of characters that can be represented by the standard. When using those standards, it became common to equate a character with a byte of storage. If you had a string of 10 characters, the amount of storage needed was 10 bytes, and many character manipulation routines expected character string lengths to be specified as a number of bytes. With Unicode encoding, bytes and characters are no longer equated: characters are represented internally by a varying number of bytes, depending on the character. If you configure the server for Unicode, you define the length of strings and alphanumeric fields in terms of characters, not bytes. This simplifies specifying string and field lengths. Each character is represented internally by up to three bytes, and the server automatically adjusts for the actual storage length. In reports, each character displays in a report column using one space, regardless of how many bytes it takes up in memory. This character-based processing mode employed for Unicode environments is called character semantics. The non-unicode mode is called byte semantics. Procedures that had been developed using byte semantics will continue to work when deployed in a Unicode environment, without adjustment, in most cases. The main benefit of the new system is the ability to have multiple languages (both European and Asian) in the following Webfocus and Dialogue Manager objects: Titles, descriptions, and names in synonyms. Headings and prompts in procedures. Data for all supported adapters (for example, SAP BW, SAP R/3-ECC, Oracle, DB2, Sybase ASE, Teradata, MySQL, Web Services, Fixed files). For more information, see Accessing Unicode Data. 7-2 Information Builders

155 Unicode Support Procedure: How to Configure the Server for Unicode To configure the server for UTF-8 or UTF-EBCDIC character encoding: 1. In the Web Console, select Configuration from the menu bar s Workspace menu. The General pane opens. 2. Expand the General folder and click NLS. The NLS Configuration Wizard pane opens. 3. Select Unicode (UTF-8) or Unicode (UTF-EBCDIC) from the CODE_PAGE drop-down list. The server will be configured for Unicode once you save this configuration. Accessing Unicode Data Adapters for the following types of data sources support Unicode: SAP BW SAP R/3-ECC Oracle DB2 Sybase ASE Microsoft SQL Server Teradata (CLI) MySQL Web Services XBRL XML Fixed-format sequential files Relational adapters in a Unicode environment assume that the DBMS returns character data to the server already converted to Unicode. The relational adapters convert data to the correct DBMS API when writing to a relational data source (for example, Oracle to UTF-8, Microsoft SQL Server to UTF-16, and DB2 on MVS to UTF-EBCDIC). XML-based adapters (the Adapter for XML, and the Adapter for XBRL) obtain the code page from the XML declaration of the processed XML document. For more information, see Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 7-3

156 Accessing Unicode Data The Adapter for Web Services generates SOAP requests using the UTF-8 code page. Reference: Unicode Considerations for Oracle The adapter supports Unicode data in Oracle release 10g or higher databases that have been configured with the NLS_CHARACTERSET parameter set to UTF8. You must set the NLS_LANG environment variable in the edastart file, in a separate shell file, in a database profile, or in a user profile. Set NLS_LANG using the following syntax NLS_LANG = language_territory.characterset where: language Is the selected language. territory Is the name of the country associated with the selected language. characterset Is the value of the NLS_CHARACTERSET variable that is set in the Oracle database. For Unicode, this is always UTF8. For example, for American English UTF-8, you would use the following setting: NLS_LANG=American_America.UTF8 For information about data type support, see Relational Adapter Data Type Support. Reference: Unicode Considerations for DB2 Information Builders supports DB2 databases, version 8 and higher. To prepare the DB2 environment for Unicode on: Windows, the database must have been created with the option CODESET UTF-8, and you must add the following variable to the environment using Windows or in the edastart file: DB2CODEPAGE=1208 UNIX, the database must have been created with the option CODESET UTF-8, and you must set the LANG and NLS_LANG environment variables in the edastart file or in a separate shell file. For example, for American English, you would export the following variables: export LANG=EN_US.UTF-8 export NLS_LANG=American_America.UTF8 7-4 Information Builders

157 Unicode Support z/os, the database must have been created with the CCSID UNICODE option, and you must ensure that the DSNAOINI environment variable points to a configuration file containing the following specification: CURRENTAPPENSCH=UNICODE The adapter supports Unicode only with the CLI interface. For information about data type support, see Relational Adapter Data Type Support. Reference: Unicode Considerations for Sybase ASE The adapter supports Unicode data in Sybase ASE version 15.0 and higher databases that have been created with the CHARACTER SET option set to UTF-8. You must set the LANG and NLS_LANG environment variables in the edastart file or in a separate shell file before starting the server. For example, for American English, you would export the following variables: export LANG=EN_US.UTF-8 export NLS_LANG=American_America.UTF8 For information about data type support, see Relational Adapter Data Type Support. Reference: Unicode Considerations for Microsoft SQL Server The adapter, using the OLE DB interface, supports Unicode data stored in NCHAR and NVARCHAR fields (where N stands for national). N columns can support data of any language or combination of languages. For information about data type support, see Relational Adapter Data Type Support. Reference: Unicode Considerations for Teradata (CLI) The Adapter for Teradata (CLI) supports Unicode UTF-8 format if: The Teradata CLI client components are part of release TTU8.0 or higher. The Teradata database is release V2R6.0 or higher and appropriate language support was enabled during the sysinit process. Contact your database administrator (DBA) to determine whether international language support has been enabled in your Teradata system and/or consult the Teradata documentation for details about International Character Set support. Note that, at the present time, when Unicode is enabled the length of a Teradata Column Name and/or TITLE cannot exceed 21 characters (bytes). For information about data type support, see Relational Adapter Data Type Support. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 7-5

158 Accessing Unicode Data Reference: Unicode Considerations for MySQL The Adapter for MySQL is implemented using JDBC. This implementation supports Unicode data stored in character fields with CHARACTER SET set to UTF-8. You must set the LANG environment variable in the edastart file or in a separate shell file before you start the server. For example, for American English you would export the following variable: export LANG=EN_US.UTF-8 For information about data type support, see Relational Adapter Data Type Support. Reference: Relational Adapter Data Type Support for Unicode In Unicode databases the information in CHAR(n) columns is stored in a UTF-8 encoding scheme. Most RDBMS Unicode columns of CHAR type specify length in bytes, not characters; the B-modifier in the Actual format denotes that a character column with a fixed byte length might contain a varying number of UTF-8 characters; this is reflected in the AnV Usage format. DBMS Column Type Usage Actual * DB2 CHAR(n) AnV AnB GRAPHIC(n) An An VARCHAR(n) AnV AnVB VARGRAPHIC(n) AnV AnV Oracle CHAR(n CHAR) An An CHAR(n BYTE) AnV AnB NCHAR(n) An An VARCHAR(n CHAR) AnV AnV VARCHAR(n BYTE) AnV AnVB NVARCHAR(n) AnV AnV Sybase ASE CHAR(n) An AnB UNICHAR(n) An An VARCHAR(n) AnV AnVB UNIVARCHAR(n) AnV AnV 7-6 Information Builders

159 Unicode Support DBMS Column Type Usage Actual * Microsoft SQL Server CHAR(n) single byte code page An An CHAR(n) double byte code page AnV AnV NCHAR(n) An An VARCHAR(n) AnV AnV NVARCHAR(n) AnV AnV Teradata CHAR(n) An An VARCHAR (n) AnV AnV MySQL CHAR(n) An An VARCHAR (n) AnV AnV * Note that on EBCDIC platform(s) the ACTUAL size for a B-suffixed format is increased 1.5 times to accommodate the expansion when converting from UTF-8 to UTF-EBCDIC. For example, on MVS the synonym created for a DB2 CHAR(10) column contains the following: USAGE=A10, ACTUAL=A15B. Reference: Unicode Considerations for SAP BW and SAP R/3-ECC SAP uses UTF-16 encoding in its Unicode system. The server uses UTF-8 and handles all conversions between the two encoding schemes. The server may not need to be configured for Unicode when accessing the SAP Unicode system. NLS settings for the server must be configured in such a way that the server code page can handle the list of chosen languages. For example, ISO can accommodate most Western European languages. The 8859 family can handle character specifics with the lower set almost being mapped to US ASCII. Therefore, with one could request English, German, French, and Spanish. When a character set requires a code page that takes more than one byte per character (for example, many Asian languages), the only choice for the server is (UTF-8). The adapters provide access to Unicode SAP BW and SAP ECC systems, respectively. This extends support of data and metadata in multiple languages to the server, consistent with support by the SAP server. A synonym can be created using one or more languages. Those languages will be used to create titles and descriptions. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 7-7

160 Selecting, Reformatting, and Manipulating Characters For SAP BW, the userid and password in the sapserv.cfg file must be able to connect to SAP BW using the enumeration of desired languages. For SAP R/3-ECC, the server logon language is used to retrieve all languages. Reference: Unicode Considerations for Fixed-Format Sequential Files When retrieving a fixed-format sequential file, the server attempts to determine the code page the file was meant to be retrieved with by checking the Master File s CODEPAGE attribute. If the Master File does not contain the CODEPAGE attribute, the server s code page is used to read the file. If you use the Data Management Console to generate a data flow that creates a fixed-format sequential file, you can specify a code page in the Data Management Console. DataMigrator will then create the fixed-format file in a way that can be read by the server when that server has been configured for the specified code page. In a Unicode configuration, HOLD files in BINARY and ALPHA formats are created using UTF-8 conversion, which assigns each character three bytes of storage in ASCII environments or four bytes in EBCDIC environments. Fields defined in the Master File using the data type A in both the USAGE and ACTUAL attributes are described in terms of characters. Fields defined using any other combination of USAGE and ACTUAL attribute values are described in terms of bytes. To force a field in a fixed-format sequential file to be described in terms of bytes, add B to the end of the field s ACTUAL attribute. For example, to specify that a field is stored in 10 bytes, you would specify: ACTUAL=A10B The adapter will then read the specified number of bytes from the record and convert their contents to the number of characters specified by the file s code page. Regardless of how much storage a character occupies, it occupies only one space on a report, as always. Selecting, Reformatting, and Manipulating Characters In character semantics mode, selection tests against a mask are automatically adjusted to work with characters rather than bytes. Formats assigned by reformatting a field in a request or by defining a temporary field are interpreted in terms of characters. Character functions interpret all lengths in terms of characters as well. Example: Defining a Virtual Field Consider the following DEFINE in the Master File for the EMPLOYEE data source: DEFINE FIRST_ABBREV/A5 WITH FIRST_NAME = EDIT(FIRST_NAME, '99999$$$$$');$ 7-8 Information Builders

161 Unicode Support In character semantics mode, format A5 is interpreted as five characters (up to 15 bytes on ASCII platforms, up to 20 bytes on EBCDIC platforms), and the comparison is performed based on this number of bytes. In byte semantics mode, format A5 is interpreted as five bytes, and the comparison is performed based on five bytes. In either case, the correct characters are compared and extracted. Example: Reformatting a Field Consider the following PRINT command: PRINT FIELD1/A10 In character semantics mode, format A10 is interpreted as 10 characters (up to 30 bytes), meaning that up to 30 bytes must be retrieved when this field is referenced. In byte semantics mode, format A10 means that 10 bytes will be retrieved. In either case, the field displays as 10 characters that take up 10 spaces on the report output. Reference: Character Functions That Support Character Semantics In character semantics mode, all character manipulation functions interpret lengths in terms of characters. The following functions operate on alphanumeric strings in character semantics mode when Unicode is configured: String manipulation and extraction functions. GETTOK, OVRLAY, PARAG, REVERSE, SQUEEZ, STRIP, SUBSTR, SUBSTV, TRIM, TRIMV Justification functions. CTRFLD, LJUST, RJUST Length and position functions. ARGLEN, LENV, POSIT, POSITV Format conversion functions. EDIT Decoding, comparison, and editing functions. CHKFMT, EDIT, DECODE, SOUNDEX String replacement functions. CTRAN, HEXBYT, BYTVAL (see notes below), STRREP Case translation functions. LCWORD, LOCASE, LOCASV, UPCASE, UPCASV Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 7-9

162 Selecting, Reformatting, and Manipulating Characters Note: The HEXBYT, BYTVAL, and CTRAN functions have been extended to handle multibyte characters in Unicode configurations. These functions use or produce numeric values to represent characters. In Unicode configurations, they use or produce values in the range: 0 to 255 for 1-byte characters 256 to for 2-byte characters to for 3-byte characters to for 4-byte characters (primarily for EBCDIC) To find the numeric value corresponding to a given character, find its hexadecimal code and convert to decimal with a hex calculator such as the Windows XP Calculator program. (Make sure to use the UTF-8 or UTF-EBCDIC code, not the Unicode code point, which would be the UTF-16 value.) For example, assume you would like to create a variable of format A1 containing the euro sign. The euro sign in UTF-8 is, in hex, E282AC. Converting this to decimal gives Thus, the proper DEFINE or COMPUTE would be: EUROSIGN/A1 = HEXBYT( , 'A1'); If you are creating a FOCEXEC with a UTF-8 compliant editor, you can also get the value of the euro sign in this way: EUROVAL/I8 = BYTVAL(' ', 'I8'); The CTRAN function replaces all occurrences of a character in a string with another character, given the decimal values that represent the hexadecimal codes for the two characters. Traditionally, this technique was used to replace characters that were difficult to input directly. Decimal values of characters can be complicated to determine. Therefore, if you want to replace characters or character strings that you can input directly using a UTF-compliant text editor, Information Builders recommends that you use the STRREP string replacement function. The following translates all of the euro signs in a 40-character UTF-8 field to pound sterling signs ( = C2A3 or 49827): NEWFLD/A40 = CTRAN(40, OLDFLD, EUROVAL, 49827, 'A40'); 7-10 Information Builders

163 Sort Order Under Unicode Unicode Support Sort order is based on the binary values assigned to the characters. When the server is configured for Unicode, the sort order is based on the Unicode encoding standard. If ascending values of the codes correspond to the alphabetical order of the letters in the language being used, a report can be sorted in alphabetical order. This is entirely dependent on the encoding standard and its mapping of codes to letters. In many, but not all cases, the encoding standard assigns codes in the alphabetical order of each language. For example, Ukrainian added a new letter (Cyrillic capital letter ghe with upturn) to its alphabet after the UTF-8 coding specification had already been set. This letter was not assigned a code that sorts it alphabetically, either in Unicode or in code page 1251 (used for Ukrainian). It sorts differently and incorrectly using either encoding scheme. With code page 1251, this letter sorts as the first letter on the report output. With UTF-8, this letter sorts as the last letter on the report output. To determine whether a language sorts alphabetically, you can examine the hexadecimal codes assigned to its letters on the code page you are using and check whether ascending hexadecimal codes match the alphabetical order. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 7-11

164 Unicode PDF Output Unicode PDF Output Reporting from a Unicode data source with PDF output format is available when using the following two fonts which support Unicode characters: Lucida Sans Unicode, which is used to display single-byte characters only. This font is available on Windows version 2000 and higher. Arial Unicode MS, which is used to display both single-byte and double-byte characters. This font can be installed as an option from the Microsoft Office CD, version 2000 and higher. The Lucida Sans Unicode font is the default font if the WebFOCUS Server is configured for UTF-8 (code page 65001) or UTF-EBCDIC (code page 65002). If the server is configured for Unicode, and you want to use the Arial Unicode MS font instead, you must specify the Arial Unicode MS font in the stylesheet. Alternatively, if the WebFOCUS PDF font mapping file (ibi\srv76\home\nls\pdf.fmp) has DEFAULT-FONT=YES specified for Arial Unicode MS, then it becomes the default font. For example: font=arial Unicode MS, style=normal, metricsfile=pdarum AFM *, DEFAULT-FONT=YES, $ For more information about how to use the PDF font mapping file, see the Creating Reports With WebFOCUS Language manual Information Builders

165 8 Creating and Working With Procedures Procedures are reusable components of application logic, written in a 4GL language. From the Procedures navigation pane of the Web Console or the Data Management Console, you can: Create and edit stored procedures. Run procedures at the present time, at a later time, or under stress conditions (Web Console only). Run a variety of reports that monitor many aspects of procedure performance. Configure the application path and manage application files. These tasks are described in detail in Managing Applications and Paths in the Web Console in Chapter 5, Creating and Working With Applications. Topics: Creating a Stored Procedure Editing a Stored Procedure Running a Stored Procedure Stress Testing a Procedure Running Impact Analysis Reports

166 Creating a Stored Procedure Creating a Stored Procedure How to: Create a Stored Procedure from the Web Console Create a Stored Procedure from the Data Management Console You can code a stored procedure in a text editor that is easily accessible from the Web Console and the Data Management Console. Procedure: How to Create a Stored Procedure from the Web Console 1. Select Procedures from the Web Console menu bar. An expanded menu bar is displayed. 2. Click New Procedure. A text editing window opens in the right pane. 3. Type the procedure code, which may be either FOCUS or SQL. You are responsible for the accuracy of the syntax you enter. However, any errors that are generated will be displayed in the right pane, as well as in the Session Log, which you can access from the My Console option on the menu bar. 4. Click the Run, Save, or Save as icons. 5. When you Run the procedure, the output is displayed in the right pane. When you Save as (or Save for the first time), you are prompted for the name of the procedure and the name of the application in which to store it (baseapp is the default). The procedure is added to the application folder in the navigation pane. Tip: You can also open the text editor by clicking an application folder in the navigation pane and choosing New Procedure from the menu. In this case, you are prompted only for the procedure name since the application is already identified. 8-2 iway Software

167 Creating and Working With Procedures Procedure: How to Create a Stored Procedure from the Data Management Console 1. Right-click an application directory in the Procedures tab of the navigation pane and select New, then Stored Procedure. A text editing window opens. 2. Type the procedure code, which may be either FOCUS or SQL. You are responsible for the accuracy of the syntax you enter. However, any errors that are generated will be displayed in the Server Messages tab below the workspace when you execute the stored procedure. 3. Choose Save As from the File menu or click the Save button on the toolbar. Enter a procedure name in the Save As window. The procedure is listed in the Procedures tab of the navigation pane. Editing a Stored Procedure How to: Edit a Procedure From the Web Console Edit a Procedure From the Data Management Web Console Once you have created a procedure, you can open the text editor to view or revise it. Tip: In addition to editing procedure code, you can copy, delete, or move a procedure component using options on the Procedures navigation pane. For details about these and other path management options, see Managing Applications and Paths in the Web Console in Chapter 5, Creating and Working With Applications. Procedure: How to Edit a Procedure From the Web Console 1. Select Procedures from the Web Console menu bar. 2. In the Procedures navigation pane, expand the Application Directories folder and click a procedure in an application folder. 3. Choose Edit from the menu. The procedure opens in the text editor. 4. When you have made your changes, click the Save icon. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 8-3

168 Running a Stored Procedure Procedure: How to Edit a Procedure From the Data Management Web Console 1. Click the Procedures tab below the navigation pane. 2. Expand the Application Directories folder and right-click a procedure in an application folder. 3. Choose Open from the menu. The procedure opens in the text editor. 4. When you have made your changes, click the Save icon. Running a Stored Procedure You can run a procedure from the Web Console with the following variations: In this section: Running a Stored Procedure Running a Procedure With Different Variables Prompting for Amper Variables in Live and Deferred Procedures Scheduling Requests for Deferred Execution Run the procedure immediately. Change default values of amper variables, then run the procedure. Run the procedure at a later time (deferred), and, if you wish, monitor procedures in the deferred execution queue. Some of these tasks can also be performed from the Data Management Console. Running a Stored Procedure How to: Run a Procedure From the Web Console Navigation Pane Run a Procedure From the Data Management Console Navigation Pane You can run a stored procedure from an application folder located on the Procedures navigation pane. In addition, when you create or edit a stored procedure in the text editor, you can run the procedure directly from that window, with or without first saving it (see How to Create a Stored Procedure from the Web Console on page 8-2 or How to Create a Stored Procedure from the Data Management Console on page 8-3). 8-4 iway Software

169 Creating and Working With Procedures Procedure: How to Run a Procedure From the Web Console Navigation Pane 1. Select Procedures from the Web Console menu bar. 2. In the Procedures navigation pane, expand the Application Directories folder, then expand an application folder and click a procedure. 3. Choose Run from the menu. The output appears in the right pane. If output cannot be generated, an error message is displayed. Tip: For additional information, click My Console on the menu bar and choose Session Log. Click the message in the log to see expanded information in a separate window. Procedure: How to Run a Procedure From the Web Console Text Editor 1. Select Procedures from the Web Console menu bar. 2. In the Procedures navigation pane, expand the Application Directories folder, then expand an application folder and click a procedure. 3. Choose Edit from the menu. The procedure opens in the Text editor. 4. Enter or edit procedure code. 5. Optionally, save the procedure. 6. Click the Run icon above the edit window. The output appears in the right pane. Procedure: How to Run a Procedure From the Data Management Console Navigation Pane 1. Click the Procedures tab below the navigation pane. 2. Expand the Application Directories folder and right-click a procedure in an application folder. 3. Choose Run from the menu. The output appears in the right pane. If output cannot be generated, an error message id displayed in the Console log at the bottom the DMC window. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 8-5

170 Running a Stored Procedure Running a Procedure With Different Variables You can run a stored procedure with amper variable values that differ from those originally specified in the procedure. Procedure: How to Run a Procedure With Different Variable Values From the Web Console 1. Select Procedures from the Web Console menu bar. 2. In the Procedures navigation pane, expand the Application Directories folder, then expand an application folder and click a procedure. 3. Select Run Advanced, then Run changing defaults from the menu. The procedure s amper variables are displayed, along with their default values (if any). 4. Type or replace any values you want to test, and then click Run to display the procedure output. Procedure: How to Run a Procedure With Different Variable Values From the Data Management Console 1. Click the Procedures tab below the navigation pane. 2. Expand the Application Directories folder and right-click a procedure in an application folder. 3. Select Run Advanced, then Run changing defaults from the menu. The procedure s amper variables are displayed, along with their default values (if any). 4. Type or replace any values you want to test, and then click Run to display the procedure output. 8-6 iway Software

171 Creating and Working With Procedures Prompting for Amper Variables in Live and Deferred Procedures Whether run immediately or deferred from the Web Console, first-level (non-nested) procedures, can prompt for Dialogue Manager amper variables, with the following exceptions: -IF THEN ELSE branching, -GOTO branching, and -PROMPT with a list amper variable values. (These commands may produce unexpected results.) Scheduling Requests for Deferred Execution How to: Schedule the Deferred Execution of a Request When you run a procedure in deferred mode the procedure is added to the queue of deferred procedures and run based on your specifications. You can schedule the deferred execution of a request by picking the month and day from a calendar and the time from hour and minute drop-down lists. In addition, if deferred execution fails due to insufficient space in the dmf_dir directory (the location where deferred requests and responses are stored), you can request to be notified by . Procedure: How to Schedule the Deferred Execution of a Request 1. From the Web Console menu bar, click Procedures. 2. In the Procedures navigation pane, expand the application tree, click a procedure, and choose Run Advanced, then Run Deferred from the menu. The Deferred Execution window opens. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 8-7

172 Running a Stored Procedure 3. Enter a date in the input box (the default is the current date) or click the Calendar icon to open calendar, where you can: a. Click the left or right arrow to change the month. (If you wish to change the month, you must do so before you change the date.) b. Click a date. The calendar closes and your selection is reflected in the Date box. 4. Click the hour and/or minute pull-down lists to change the time. 5. Click Continue to submit the change. A message is displayed, indicating that the request is queued for execution at the specified time. Procedure: How to View a List of Deferred Procedures From the Web Console 1. Select Procedures from the Web Console menu bar. 2. In the Procedures navigation pane, expand the Application Directories folder and click a procedure in an application folder. 3. Select List Deferred from the menu. A list of procedures in the deferred execution queue is displayed. 8-8 iway Software

173 Creating and Working With Procedures Stress Testing a Procedure Stress testing enables you to simulate request execution in order to ensure that the server will retrieve data satisfactorily under specified conditions. The mechanism behind stress testing is a record and playback feature in which the exact sequence of user actions applied through a browser are recorded and then reproduced (played back), simulating a single user or multiple users under the same or different conditions. You can use the generated files and the recorded sequences, known as HTI scripts, along with server traces, to test new configurations, and to diagnose problems. From the Web Console Playback of HTI Scripts pane, you can initiate test runs under the following separate and combined conditions: How to: Run a Stress Test Example: Sample Stress Test Log Sample Performance Reports Requests run simultaneously by a number of users (expressed as threads). You can retest using a variety of scenarios. This features enables you to determine in advance the system s ability to grow (that is, its scalability). Requests executed at varying intervals. This feature enables you to determine in advance the system s ability to adjust to increases in workload. In addition to these basic tests, you can specify a number of advanced conditions to refine the diagnostic process. For example, stress testing generally provides information about the retrieval performance of the iway Server going against one or more data sources (also called back end processing). If, however, you are working in a client environment like WebFOCUS, you may wish to test data retrieval performance beginning at a user s browser, going through a Web server (front end processing), to the iway Server to the data source. You can request that the test be redirected to the Web server to track retrieval over the longer path. Then, by comparing back end test results with front end test results, you can more accurately diagnose the origin of a performance problem based on any other conditions you specify. For a full list of the basic and advanced stress test conditions you can apply, see General Playback Parameters in Chapter 15, Troubleshooting. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 8-9

174 Stress Testing a Procedure Procedure: How to Run a Stress Test 1. Select Procedures from the Web Console menu bar. 2. In the Procedures navigation pane, expand the Application Directories folder. 3. Expand an application, click a procedure, and select Run Advanced, then Run Stress from the menu. The Playback of HTI Script Files pane opens. 4. Enter basic test conditions: Number of Threads, Interval Parameter, and a Test Description. Click Advanced if you wish to specify additional conditions. For a full list of options, see General Playback Parameters in Chapter 15, Troubleshooting. 5. Click Start. Results are displayed in a separate window. For an illustration, see Sample Stress Test Log on page The script is listed under the tested procedure in the directory C:\ibi\scale. 6. Open the Performance Reports folder on the Playback navigation pane and choose: Basic Report Extended Report For an illustration, see Sample Performance Reports on page Example: Sample Stress Test Log ---- Started at 12:57: Received: thread=01 request=0001; timing: resp=0.062 sec, transf=0.000 sec, start=06/29/ :57: Finished at 12:57: Total Execution Time: sec Total Number of Requests: 1 Total Number of Threads: 1 Interval Parameters: 500,-1,-1 Average Server Response: sec Average Data Transfer Time: sec Average Request Processing Time: sec Standard Processing Deviation: sec Minimum Processing Time: sec Maximum Processing Time: sec terminating main thread 8-10 iway Software

175 Creating and Working With Procedures Example: Sample Performance Reports Basic Report Advanced Report Running Impact Analysis Reports How to: Run an Impact Analysis Report for a Procedure From the Web Console Run an Impact Analysis Report for a Procedure From the Data Management Console Example: Sample Impact Analysis Reports for a Procedure Standard Impact Analysis Reports An Impact Analysis report enables you to determine the impact of changing a synonym, synonym column, or procedure. The report shows you how and where the object is used. For example, running the report on a procedure tells you from which applications and procedures the original procedure is run. Running the report on a synonym tells you which tables or other data sources the synonym describes, and in which procedures it is referenced. This enables you to determine how changing the synonym, column, or procedure could affect the rest of your application. You can run Impact Analysis reports from the Web Console and from the Data Management Console. When run from the Data Management Console, reports also provide drill-down links so that you can, for example, run an Impact Analysis report on a synonym, see a procedure listed in the report, and click the procedure to edit it. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 8-11

176 Running Impact Analysis Reports Procedure: How to Run an Impact Analysis Report for a Procedure From the Web Console 1. Select Procedures from the Web Console menu bar. 2. In the Procedures navigation pane, expand the Application Directories folder. 3. Expand an application and click the procedure. 4. Select Impact Analysis from the menu. The Impact Analysis report opens in the right pane. Procedure: How to Run an Impact Analysis Report for a Procedure From the Data Management Console 1. Click the Procedures tab below the navigation pane. 2. Expand the Application Directories folder. 3. Expand an application and right-click a procedure. 4. Select Impact Analysis from the menu. The Impact Analysis report opens in the right pane. Example: Sample Impact Analysis Reports for a Procedure The following reports were generated for the mntstmt sample procedure in the Web Console and the Data Management Console. Web Console Data Management Console 8-12 iway Software

177 Running Standard Impact Analysis Reports Creating and Working With Procedures In addition to the reports you can run for an individual procedure, synonym, or column, you can select the following standard Impact Analysis reports from in the Reports folder in the Procedures navigation pane of the Web Console or the Data Management Console: The Synonyms by Procedure report lists your procedures and the synonyms that they use, sorted by procedure. The report includes whether the synonym is used as a source or a target, the adapter type, the table name and description, load type and prior to load options, and directory locations. The Procedures by Synonym report lists your synonyms and the procedures they are used in, sorted by synonym. The report includes whether the synonym is used as a source or a target, the adapter type, the table name and description, load type and prior to load options, and directory locations. The Columns by Procedure report lists the columns used in your procedures and their synonyms sorted by data flow. The report includes how the column is used, as well as directory locations. The Procedures by Column report lists your procedures and their synonyms sorted by column. The report includes how the column is used, as well as directory locations. The Synonyms by Procedure - Enterprise report includes the same information as a Synonyms by Procedure report, but for the server and all its subservers in a hub/subserver environment. This report does not appear if the server you re reporting on doesn't have any remote server's configured. The Procedures by Synonym - Enterprise report includes the same information as a Procedure by Synonym report, but for the server and all its subservers in a hub/subserver environment. This report does not appear if the server you re reporting on doesn't have any remote server's configured. Note: Enterprise reports appear only if you have subservers. Example: Standard Impact Analysis Reports These following reports include the procedure and synonym directories, columns and column types, synonym usage (source or target), adapter type, table name, description, and prior to load and load type options. This output was generated from the Data Management Console. The Web Console produces identical output with a different look and feel. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 8-13

178 Running Impact Analysis Reports The Synonyms by Procedure report lists each procedure and the synonym(s) it uses. The Procedures by Synonym report lists each synonym and the procedure(s) that use it. The Columns by Procedure report lists each procedure and the synonym(s) and columns it uses iway Software

179 Creating and Working With Procedures The Procedures by Column report lists each column by synonym and by the procedure(s) that use it. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 8-15

180 Running Impact Analysis Reports 8-16 iway Software

181 9 Resource Analyzer and Resource Governor Overview Resource Analyzer and Resource Governor are optional components of the server. Resource Analyzer monitors data usage activity by collecting the attributes of requests and storing them in a set of Usage Monitoring tables. It automatically keeps track of each request, which data sources and columns it accessed, when it was run, how long it took, which resources it consumed, and more. Resource Analyzer allows you to report on, graph, and analyze end-user request traffic. Resource Governor controls monitoring, system configuration parameters, and governing rules. It provides preemptive governing for requests issued to both relational and non-relational data sources and uses the same Usage Monitoring tables as Resource Analyzer. An administrator can also define site-specific thresholds controlling the amount of resources a request can use. Based on the usage and threshold information, Resource Governor builds rules about how to govern requests against specific data sources. The governing facility uses the rules when inspecting each request, stopping any request that is estimated to exceed the predetermined resource thresholds. Important: For all platforms except MVS, you perform configuration from the Web Console. For MVS, you perform configuration from the Resource Analyzer or Resource Governor Administration tool. Topics: Resource Analyzer and Resource Governor Add-on Tools

182 Resource Analyzer and Resource Governor Add-on Tools Resource Analyzer and Resource Governor Add-on Tools How to: Configure the Server to use Resource Analyzer and Resource Governor If you are licensed to use Resource Analyzer and Resource Governor, you can configure these add-on tools from the Web Console. For more information on using these products, see the Resource Analyzer Administrator's and User's Manual and the Resource Governor Administrator's and User's Manual. Procedure: How to Configure the Server to use Resource Analyzer and Resource Governor In earlier releases, Resource Management was configured with a license key at installation. As of Release 7.1, Resource Management is configured from the iway Web Console after installation of the server is complete. (For MVS and VM, Resource Management is configured from the Resource Analyzer or Resource Governor Administration tool.) To configure Resource Management, after the server is installed, you must: 1. Click Resource Management on the Web Console menu bar. 2. Click Configure Resource Management on the expanded Web Console menu bar. 3. Type your license key and select a collection repository and monitor type. 4. Configure the repository. 5. Run the configuration verification program (CVP). Note: If you are only planning on running Resource Analyzer and not Resource Governor on your server, this step is not necessary. You are ready to begin using Resource Analyzer. When you enable Resource Management, it automatically turns on monitoring and governing (if applicable). However, you can disable and re-enable monitoring and governing at any time. 9-2 iway Software

183 10 Configuring and Administering Resource Management From the Web Console The iway Web Console enables you to configure and administer Resource Management. Note: To configure and administer Resource Management on MVS, you must use the Resource Management Administration tool, instead of the Web Console. Topics: Configuring Resource Management Administering Resource Management From the Web Console Migrating the Resource Management Repository

184 Configuring Resource Management Configuring Resource Management How to: Configure Resource Management Using a FOCUS Repository Configure Resource Management Using a Relational Repository Reference: Resource Management Configuration Pane In earlier releases, Resource Management was configured with a license key at installation. As of Release 7.1, Resource Management is configured from the iway Web Console after installation of the server is complete. To configure Resource Management, after the server is installed, you must: 1. Enable Resource Management from the Web Console. 2. Type your license key and select a repository type. 3. Configure the repository. Resource Management can be configured to create Usage Monitoring tables in a FOCUS repository or in a relational repository. The repository holds data on resource usage. If you want to use a FOCUS repository, see How to Configure Resource Management Using a FOCUS Repository on page If you want to use a relational repository, see How to Configure Resource Management Using a Relational Repository on page iway Software

185 Configuring and Administering Resource Management From the Web Console Procedure: How to Configure Resource Management Using a FOCUS Repository To enable Resource Management, you must have a valid license key. After typing the key, you can specify the type of repository for Usage Monitoring (a FOCUS repository is the type used in this procedure. For a relational repository, see the next procedure). The Usage Monitoring tables are then created. This procedure creates Usage Monitoring tables in a FOCUS repository using a licence code for both Resource Analyzer and Resource Governor. 1. On a Windows system, from the Programs Menu, select iway Software (or Information Builders, if you have a WebFOCUS server installation, rather than iway), then the server type, then Web Console. Note: If you are using an operating system other than Windows, enter where: ipaddress Identifies the server where Resource Analyzer or Resource Governor is to be configured. port Is the port number for that server. Note: On the Program Menu under iway Software, the server types can include iway Full Function Server, or iway 76 DataMigrator Server. On the Program Menu under Information Builders, the server type can include a WebFOCUS 76 Server. Resource Analyzer can be configured on any of these servers. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-3

186 Configuring Resource Management The iway Web Console opens, as shown in the following image iway Software

187 Configuring and Administering Resource Management From the Web Console 2. Click the Resource Management link on the toolbar. The Resource Management page opens, as shown in the following image. 3. Click the Configure Resource Management link on the toolbar. The Resource Management Configuration pane opens, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-5

188 Configuring Resource Management 4. Select FOCUS/FDS for the Repository Type. 5. Type the license key from the packing slip. There are different keys, one for Resource Analyzer, one for Resource Governor, and one if both products are licensed. 6. Click Next. The Resource Management Configuration pane opens. The following image shows the configuration pane for both Resource Analyzer and Resource Governor. 7. Type a Server Name. This field defaults to the host server name, but any identifier of up to 48 characters is acceptable, provided it is unique across all servers where Resource Analyzer or Resource Governor is installed. Select the Global Monitoring and Monitoring Preference options. For more information on these options, see Resource Management Configuration Pane on page iway Software

189 8. Click Configure. Configuring and Administering Resource Management From the Web Console A message appears indicating that Resource Management configuration is in progress. When completed, the Resource Management: Resource Analyzer/Governor page opens, and the navigation pane on the left appears, as shown in the following image. Procedure: How to Configure Resource Management Using a Relational Repository To enable Resource Management, you must have a valid license key. After typing the key, you can specify the type of repository for Usage Monitoring (a relational repository is the type used in this procedure. For a FOCUS repository, see the previous procedure). The Usage Monitoring tables are then created. This procedure creates Usage Monitoring tables in a relational repository using a licence code for both Resource Analyzer and Resource Governor. 1. On a Windows system, from the Programs Menu, select iway Software (or Information Builders, if you have a WebFOCUS 7server installation, rather than iway), then the server type, then Web Console. Note: If you are using an operating system other than Windows, enter where: ipaddress Identifies the server where Resource Analyzer or Resource Governor is to be configured. port Is the port number for that server. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-7

190 Configuring Resource Management Note: On the Program Menu under iway Software, the server types can include iway Full Function Server, or iway 76 DataMigrator Server. On the Program Menu under Information Builders, the server type can include a WebFOCUS 76 Server. Resource Analyzer can be configured on any of these servers. The iway Web Console opens, as shown in the following image iway Software

191 Configuring and Administering Resource Management From the Web Console 2. Click the Resource Management link on the toolbar. The Resource Management page opens, as shown in the following image. 3. Click the Configure Resource Management link on the toolbar. The Resource Management Configuration pane opens, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-9

192 Configuring Resource Management 4. Select Relational for the Repository type. 5. Type the license key from the packing slip. There are different keys, one for Resource Analyzer, one for Resource Governor, and one if both products are licensed. 6. Click Next. The Resource Management Configuration pane opens. This image shows the configuration pane for both Resource Analyzer and Resource Governor using a relational repository. 7. Type a Server Name. This field defaults to the host server name, but any 48 character identifier is acceptable, provided it is unique across all servers where Resource Analyzer or Resource Governor is installed. Select the Global Monitoring and Monitoring Preference options. 8. Select a Data Adapter and the appropriate Connection Name from the drop-down menu. 9. Set Create Repository to Yes, unless the repository has already been created using the Data Adapter s native Data Definition Language (DDL). 10. Provide an Owner Name. By default, the tables are created for the specified owner name in the default database, and the owner must be authorized to create tables in the database iway Software

193 Configuring and Administering Resource Management From the Web Console 11. For servers running on MVS UNIX System Services, provide a DB2 DBSPACE. 12. Select Global Monitoring and Monitoring Preference options. 13. Click Configure. A message appears indicating that Resource Management configuration is in progress. When completed, the Resource Management: Resource Analyzer/Governor page opens, and the navigation pane on the left appears, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-11

194 Configuring Resource Management Reference: Resource Management Configuration Pane The Resource Management Configuration pane differs for FOCUS and relational repositories. The configuration pane for relational repositories has additional fields/options. The following image shows the Resource Management Configuration Pane for FOCUS repositories. The Resource Management Configuration pane for FOCUS repositories has the following fields/options: Server Name. Used by Resource Analyzer or Resource Governor as the server name in collected data and on reports. Any identifier of up to 48 characters is acceptable but the value should be unique across all servers where Resource Analyzer or Resource Governor is installed. Host server (computer) name is the default. Global Monitoring. Indicates whether Global Request Monitoring is disabled or enabled. When Global Monitoring is set to ON, Resource Analyzer or Resource Governor collects information on all SQL SELECT and FOCUS TABLE, TABLEF, MATCH, GRAPH, MODIFY, and MAINTAIN requests against any data source. OFF is the default value iway Software

195 Configuring and Administering Resource Management From the Web Console Monitor Preference. All Data. Collects all information about a request. This enables all reports in Resource Analyzer and allows Resource Governor to create rules for governing. This is the default. Query, Froms, Relations and Columns. Collects SMQUERY, SMFROMS, SMRELATIONS, and SMCOLUMNS data. This disables aggregation reports in Resource Analyzer. This allows Resource Governor to create rules for governing. Query, Froms and Relations. Collects SMQUERY, SMFROMS, and SMRELATIONS data. This disables column usage reports as well as aggregation reports in Resource Analyzer. This is the minimum amount of data required to allow Resource Governor to create rules for governing with a 100% confidence level. Query and Froms. Collects SMQUERY and SMFROMS data. This disables column usage and aggregation reports in Resource Analyzer. This enables Resource Governor to create rules for governing, but reduces the governor's confidence level in the rules. Query only. Collects only the SMQUERY data. This disables all detail reports, columns usage reports, and aggregation reports. Only summary reports and procedure resource usage reports will be available. This will not allow Resource Governor to create rules for governing. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-13

196 Configuring Resource Management The following image shows the Resource Management Configuration pane for relational repositories. The Resource Management Configuration pane for relational repositories has the following additional fields/options: Data Adapter. Identifies the data adapter and the connection name to be used for storing Resource Analyzer or Resource Governor Usage Monitoring data, as well as the system administration tables. The connection name is the logical name used to identify a particular set of connection attributes. This setting also determines the SUFFIX used when creating the Master Files for these tables. Create Repositories. Determines whether the repositories will be created or not. Select No if the repositories have already been created using the Data Adapters native Data Definition Language (DDL). When No is selected, the configuration process will not issue DROP TABLE, DROP INDEX, CREATE FILE, and CREATE INDEX commands. Because the configuration process will always initialize the repositories with default data and issue the default GRANTS, the repositories must exist when the commands are executed or the configuration will fail. Yes is the default value iway Software

197 Configuring and Administering Resource Management From the Web Console Owner Name. Is the owner name of the tables used for system administration during collection by Resource Analyzer or Resource Governor. By default the tables are created for the specified owner name in the default database and the owner must be authorized to create tables in the database. If the tables are to be created in an alternate database that the owner has rights to, and the technique is supported by the RDBMS, the database name must be specified as well (for example, database.owner). Consult the appropriate RDBMS documentation for the appropriate syntax. DB2 DBSPACE. Is the name of the MVS DB2 Database or Tablespace that the collection repositories will be created in. If this field is blank, then the default PUBLIC database will be used and a tablespace will be created for each collection repository. The format is database name or database.tablespace name. Note: This field is only valid for MVS UNIX System Services and is ignored on all other platforms. All other fields/options are identical to those for FOCUS repositories. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-15

198 Administering Resource Management From the Web Console Administering Resource Management From the Web Console How to: Enable/Disable Monitoring & Governing Reset Monitor Preference Monitor Data Sources Monitor Relational Sources View Sample Data and Data Sources Properties Delete Monitor Data for a Particular Data Source Remove Resource Management Delete Monitor Data Reference: Resource Management Tools and Context Menus Resource Management Configuration Pane Monitor Preference Options Data Source Options Monitored Data Source Properties Pane Resource Management Repository Maintenance Pane Resource Analyzer s Usage Monitoring facility allows you to monitor requests as they are submitted by users, and logs information about request usage. This information includes the usage statistics associated only with data retrieval or data manipulation in the case of MODIFY or MAINTAIN. This request information is stored in Resource Analyzer s Usage Monitoring tables. You can specify the Monitor Preference, which allows you to change what information is collected for monitored data sources. The information does not include the time utilized in Dialog Manager, file allocation, writing of intermediate HOLD files, sorting of data retrieved, and computation time associated with user-written subroutine library functions and FOCUS DEFINE statements. For all platforms except for MVS, the Usage Monitoring functions are accessed from the server s Web Console. For information on accessing Usage Monitoring for MVS, see Usage Monitoring in Chapter 4, Resource Analyzer Administration for MVS Servers of the iway Resource Analyzer Administrator s and User s Manual iway Software

199 Configuring and Administering Resource Management From the Web Console The Web Console enables you to administer Resource Management. You can: Enable/Disable Monitoring & Governing. Maintain the Repository. Reconfigure Resource Management. Remove Resource Management. Enable/disable global monitoring. Set monitoring preferences. Refresh gktable. Add data sources to be monitored. View the properties of data sources and the sample data they produce. Access reports. Access to these tasks is provided by the Resource Management link on the toolbar. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-17

200 Administering Resource Management From the Web Console Reference: Resource Management Tools and Context Menus The following image shows the Resource Management page. The navigation pane is on the left and the Monitoring, Reports, and Utilities folders are expanded in the tree. The Run context menu for the Procedures Never Used report is selected. The navigation pane contains the following tools and context menu options. Context menus appear when you click a folder or on an item in an expanded folder. Resource Management Active/Inactive. Displays a context menu with two options: Enable/Disable Monitoring & Governing. This is a context menu of the Resource Management - Active folder, and enables or disables monitoring and governing. Note: When you disable monitoring and governing, the Resource Management - Active folder will change to become Resource Management - Inactive iway Software

201 Configuring and Administering Resource Management From the Web Console Show/Hide Relational Sources. This option determines whether you show or hide the relational sources in the tree of the Web Console. Regardless of the setting you can still view and monitor relational sources from the Resource Management Administration Tool. Monitoring. Displays a context menu with the following options: Enable/Disable Global Monitoring. Turns Global Monitoring on and off. Set Monitor Preference. Opens the Resource Analyzer and Governor System Settings pane where you can set Monitor Preferences. Refresh GKTABLE. Refreshes the table that records which data sources are being monitored and governed. You will only use this option if directed to do so by Customer Support for debugging purposes. Application Directories. This folder contains your application directories, and each displays a context menu with the following option: Add to monitor. Opens a pane where you can set monitoring for the data sources in the selected application directory. Note: Data sources that are added from the Web Console display in the Resource Management Console with both synonym name and application directory, for example, ibisamp/dminv. If another synonym of the same name appears in a different application directory, (for example, baseapp/dminv), it will be ignored. Only the synonym in the directory you specify will be monitored. Governing. Utilities. Reconfigure Resource Management. Opens the Resource Management Configuration pane where you can reset configuration options. Note: If you want to switch the repository type between relational and FOCUS, you must first remove Resource Management by selecting Remove Resource Managment. After you click Remove, the page refreshes, and the Configure Resource Management link reappears on the toolbar. Repository Maintenance. Opens the Resource Management Repository Maintenance pane where you can delete all monitor data or monitor data for a specific date range. Remove Resource Management. Opens the Remove Resource Management pane where you can remove resource management products from the server. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-19

202 Administering Resource Management From the Web Console Reports. The following image shows the Resource Management navigation pane with the Reports menu expanded to display some of the available reports, as well as the Reports context menu iway Software

203 Configuring and Administering Resource Management From the Web Console Note: If you are licensed for Resource Analyzer and Resource Governor, the available reports for both appear in the tree, as shown here. If you are licensed only for Resource Analyzer or only for Resource Governor, then only those reports for which you are licensed will appear in the tree. In addition to Run, the Reports context menu also contains Run Deferred and List Deferred. Run Deferred prompts you for a date and time to execute the report and submits the report to the deferred queue. List Deferred lists the procedures that are deferred. This folder contains the following reports. Monitored Data Summary. Opens the Monitored Data Summary report which provides information about data sources being monitored, including the number of queries, and the first and last access dates. Monitored Procedure Summary. Opens the Monitored Procedure Summary report, which provides information about procedures being monitored, including the number of executions, and the first and last execution dates. Procedures Never used. Opens the Procedures Never Used report which lists the procedures which have never been executed. Resource Analyzer. Expands to enable access to Resource Analyzer reports. Resource Governor. Expands to enable access to Resource Governor reports. Procedure: How to Enable/Disable Monitoring & Governing When you enable Resource Management, it automatically turns on monitoring and governing (if applicable). However, you can disable and re-enable monitoring and governing at any time. 1. Launch the iway Web Console. 2. Click the Resource Management option on the toolbar. 3. Select the Resource Management - Active/Inactive folder on the tree in the navigation pane and click the Enable/Disable Monitoring & Governing context menu. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-21

204 Administering Resource Management From the Web Console Procedure: How to Reset Monitor Preference Monitor Preference enables you to monitor all data or only data from specific types of usage. The information that Resource Analyzer monitors is stored in the Usage Monitoring tables. 1. Launch the iway Web Console. 2. Click the Resource Management option on the toolbar. 3. Click the Monitoring link in the navigation pane and select Set Monitor Preference from the context menu, as shown in the following image. The Resource Analyzer and Governor System Settings pane opens, as shown in the following image iway Software

205 Configuring and Administering Resource Management From the Web Console 4. Select a Monitor Preference from the drop-down menu. 5. Click Update. Reference: Monitor Preference Options The following image shows the Resource Analyzer and Governor System Settings pane. The Resource Analyzer and Governor System Settings pane has the following Monitor Preference options: All data. Collects all information about a request. This enables all reports in Resource Analyzer and enables Resource Governor to create rules for governing. All is the default value. Query, Froms, Relations and Columns. Collects SMQUERY, SMFROMS, SMRELATIONS, and SMCOLUMNS data. This will disable aggregation reports in Resource Analyzer. This enables Resource Governor to create rules for governing. Query, Froms and Relations. Collects SMQUERY, SMFROMS, and SMRELATIONS data. This will disable column usage reports as well as aggregation reports in Resource Analyzer. This is the minimum amount of data required to allow Resource Governor to create rules for governing with a 100% confidence level. Query and Froms. Collects SMQUERY and SMFROMS data. This will disable column usage and aggregation reports in Resource Analyzer. This enables Resource Governor to create rules for governing, but reduces the governor's confidence level in the rules. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-23

206 Administering Resource Management From the Web Console Query only. Collects only the SMQUERY data. This will disable all detail reports, columns usage reports and aggregation reports Resource Analyzer. Only summary reports and procedure resource usage reports will be available. This will not allow Resource Governor to create rules for governing. Procedure: How to Monitor Data Sources Data sources must be monitored to provide monitor data, which can then be used to analyze performance or govern usage. 1. Launch the iway Web Console. 2. Click the Resource Management option on the toolbar. 3. Click an application directory in the navigation pane and select Add to monitor, as shown in the following image iway Software

207 Configuring and Administering Resource Management From the Web Console The Monitor Data Sources pane opens to display all unmonitored synonyms in the selected application directory, as shown in the following image. 4. Select the check box(es) for the data sources you want to monitor. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-25

208 Administering Resource Management From the Web Console 5. Click Monitor. The Monitor Data Sources pane reopens displaying the selected data sources with monitoring enabled, as shown in the following image iway Software

209 Configuring and Administering Resource Management From the Web Console 6. Click the Refresh button. The data sources you selected now appear in the tree, as shown in the following image. Procedure: How to Monitor Relational Sources Monitoring relational sources means monitoring SQL direct passthru requests to relational sources that do not use synonyms. Relational sources must be monitored to provide monitor data, which can then be used to analyze performance or govern usage. Prior to Release 7.6, relational data sources could only be monitored from the Resource Management Administration Tool. As of Release 7.6, they can be monitored from the Web Console, just like other data sources. In order to monitor relational sources, you must select Show Relational Sources from the Resource Management - Active node of the tree. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-27

210 Administering Resource Management From the Web Console To monitor relational sources: 1. Launch the iway Web Console. 2. Click the Resource Management option on the toolbar. 3. Click Resource Management - Active in the tree in the tree on the navigation pane and select Show Relational Sources from the context menu. 4. Expand the Relational Sources object in the tree, click the appropriate data adapter, and select Add to Monitor. In the example shown in the following image, MS SQL Server is the adapter selected for relational source monitoring. The Enter Data Source for monitoring pane appears. In the example shown in the following image, you can enter an MS SQL Server relational source for monitoring iway Software

211 Configuring and Administering Resource Management From the Web Console 5. Enter the relational source you wish to monitor, as shown in the following image. 6. Click Monitor. 7. Click the Refresh button. The data sources you selected now appear in the tree, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-29

212 Administering Resource Management From the Web Console Procedure: How to View Sample Data and Data Sources Properties Viewing sample data enables you to determine whether you are properly set up to access your data sources. 1. Launch the iway Web Console. 2. Click the Resource Management option on the toolbar. 3. Expand an Application Directory in the tree. 4. Click a monitored data source. The context menu appears, as shown in the following image iway Software

213 Configuring and Administering Resource Management From the Web Console 5. To view sample data, click the Sample Data option from the context menu. Sample data from the data source appears, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-31

214 Administering Resource Management From the Web Console 6. To view the data source properties, click the Show monitored data option from the context menu. The Resource Analyzer and Governor Monitored Data pane opens, as shown in the following image iway Software

215 Reference: Data Source Options Configuring and Administering Resource Management From the Web Console When you click a data source in the Resource Management tree, the data source context menu opens, as shown in the following image. The data source context menu has the following options: Show monitored data. Displays the current usage information and lets you change the monitor status for the selected data source. Sample Data. Displays sample data for the data source. Delete from repository. Deletes data from the repository. You can choose to delete monitor data, system data, or both. You can also delete all data for the selected data source or specify a date range. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-33

216 Administering Resource Management From the Web Console Reference: Monitored Data Source Properties Pane The following image shows the Monitored Data Source Properties pane. The Monitored Data Source Properties pane has the following fields/options: Data Source. Is the name of the application directory and synonym being monitored in the specified application directory. Usage Count. Is the number of times the synonym was accessed. First Used. Is the date the synonym was first accessed. Last Used. Is the date the synonym was last accessed. Last User. Is the ID of the last user to run a procedure accessing the synonym. Last Procedure. Is the name of the last procedure to run using the synonym or is Ad- Hoc if no procedure was used, for example, if the last usage was by Sample Data. At Line. Is the location in the procedure where the synonym is used. It will be 0 (zero) for ad-hoc queries iway Software

217 Configuring and Administering Resource Management From the Web Console Database Location. Is the physical location of the data source. It will be blank for relational tables. Monitor Status. On. Turns monitoring for the data source on. Off. Turns monitoring for the data source off. Procedure: How to Delete Monitor Data for a Particular Data Source You can delete monitor data for a particular synonym from the repository using the Repository Maintenance pane. 1. Launch the iway Web Console. 2. Click the Resource Management option on the toolbar. 3. Expand an application directory. 4. Click a data source and select Delete from repository. The Resource Management Repository Maintenance pane opens, as shown in the following image. 5. Select the type of Data Source you wish to delete (Monitor, System, or Both). 6. Enter a Start Date and End Date or click the calendar icon on the right of each date input box to choose the dates. 7. Click Delete. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-35

218 Administering Resource Management From the Web Console Procedure: How to Delete Monitor Data You can delete monitor data from the repository using the Repository Maintenance pane. 1. Launch the iway Web Console. 2. Click the Resource Management option on the toolbar. 3. Expand the Utilities folder in the navigation pane and select Repository Maintenance. The Resource Management Repository Maintenance pane opens, as shown in the following image. 4. Enter a Start Date and End Date for deletion of data through that range, or click the calendar icon on the right of each date input box to choose the dates. 5. Click Delete. Note: Caution should be used when using this utility. Make sure you have a backup of the data before you proceed iway Software

219 Configuring and Administering Resource Management From the Web Console A dialog box opens prompting you select OK or Cancel to delete monitor data, as shown in the following image. 6. Click OK. Reference: Resource Management Repository Maintenance Pane The Resource Management Repository Maintenance pane varies depending on whether you are deleting data throughout the entire repository or just for a particular data source. The following image is the Resource Management Repository Maintenance pane for a particular data source. The Resource Management Repository Maintenance pane for a particular data source has the following fields/options: Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-37

220 Administering Resource Management From the Web Console Type of data to delete Monitored. Deletes monitor data for the data source within the date range. System. Delete only System data for the data source. This effectively removes the data source from monitoring and governing. The only means of monitoring data for the data source will be if Global monitoring is enabled or if the data source is used in a joined data request where one of the other data sources are being monitored. Both. Deletes both Monitor and System data. Start Date. Is the starting date for deleting monitor data. The default is today s date. End Date. Is the ending date for deleting monitor data. The default is today s date. The following image is the Resource Management Repository Maintenance pane for the entire repository iway Software

221 Configuring and Administering Resource Management From the Web Console The Resource Management Repository Maintenance pane for the entire repository has the following fields/options: Start/End Date. Are the start and end dates for deleting monitored data. The default date is today s date. Delete. Deletes all monitored data from the start date through the end date. Caution should be used when using this utility. Make sure you have a backup of the data before you proceed. Procedure: How to Remove Resource Management You can remove Resource Management from the server from the Resource Management Configuration pane. This is required if you want to change the repository type from FOCUS to relational, or vice versa. 1. Launch the iway Web Console. 2. Expand Utilities and click Remove Resource Management. Migrating the Resource Management Repository In this section: Requirements for Migrating the Resource Management Repository Migrating a Resource Management Repository on UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os After Completing the Migration When upgrading Resource Analyzer from a previous release, if you wish to access the monitor data from the previous release, you must migrate the contents of the previous release's Resource Management repository into the new release's repository. The migration procedure is executed in batch to migrate the repository used by Resource Analyzer from prior releases to Release 7.6. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-39

222 Migrating the Resource Management Repository Requirements for Migrating the Resource Management Repository Before running the migration procedure, follow the instructions in Resource Analyzer and Resource Governor Add-on Tools for configuring Resource Analyzer and/or Resource Governor in the new release. The following conditions are required in order to migrate the Resource Management Repository. The new Resource Management repository tables must use a different owner than the one used for the previous release's repository tables or, in the case of migrating data stored in FOCUS, a new directory. Monitoring must be turned off before running the migration procedure. To turn off monitoring on MVS or on other platforms in releases prior to Release 7.1.3, in the server's profile (EDASPROF.PRF), comment out the line SET SMARTMODE=ON. In Release and higher, use the server's Web Console to Disable Monitoring & Governing. If you turn monitoring back ON and continue to monitor in the old release, you will need to re-run the migration in order to migrate the newly monitored data. When migrating monitor data stored in FOCUS, the tables must be available during migration. No actively running sink machine (SU) process is recommended or required. When migrating monitor data stored in a relational database, this procedure can only be used to migrate the data to the same database server connection (for example, from a SQL Server repository in 5.3 to a SQL Server repository in 7.6). For both relational and FOCUS migration, the repository tables in the old release locations remain where they were and can be used as backup. Note: When you run the migration more than once (which is necessary if you continued monitoring in the old release after migration and want the newly monitored data to be migrated), you will get a duplicate record error message. The duplicates are ignored and the new records are added iway Software

223 Configuring and Administering Resource Management From the Web Console Migrating a Resource Management Repository on UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os How to: Migrate a Resource Management Repository on UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os Example: Migrating a Resource Management Repository in UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os For these platforms, the migration procedure is executed in an interactive session by using the command, edastart -x. The migration procedure, GKEMIGRE, is executed with specific parameters, based on site-specific needs. When migrating data stored in a FOCUS repository in these platforms, the tables are created in the edaconf\catalog directory of the new server. For an example, see Migrating a Resource Management Repository in UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os on page Syntax: How to Migrate a Resource Management Repository on UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os The following syntax is used to migrate a Resource Management repository on UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os. EX GKEMIGRE oldconf=, oldrel=, oldeng=, oldown=, oldsrv=, frdate=, todate=, sysfiles= where: oldconf Is the full path statement to the catalog directory of the configured server of the release you are migrating from, for example, /u2/ibi/srv53/wfs/catalog in UNIX and c:\ibi\srv53\wfs\catalog in Windows. oldrel Is the three-digit release number of the release you are migrating from (530, 710, or 713). Note: For Service Pack releases, 530 includes all 5.3x releases; 710 includes 7.1.0, 7.1.1, and 7.1.2; and 713 includes and all later releases. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-41

224 Migrating the Resource Management Repository oldeng Is the relational database used to store the Resource Management repository of the release you are migrating from. The value of this parameter must be the same as the value of the variable &ENGINE in the procedure GKESET in the release you are migrating from. Simply edit the procedure GKESET to obtain the correct value. oldown Is the owner of the tables of the release you are migrating from. The value of this parameter must be the same as the value of the variable &OWNER in the procedure GKESET in the release you are migrating from. oldsrv Note: This parameter is not used when migrating data stored in a FOCUS repository. Is the server name used by Resource Management in the old release. If you do not know the server name, it can be found in GKESET FOCEXEC. frdate Is the first or oldest date of data to be migrated from the previous release. The format of the date is YYYYMMDD and allows you to migrate data for a specific date range. The default is the first date of monitored data. todate Is the last date of data to be migrated from the previous release. The format of the date is YYYYMMDD and allows you to migrate data in a specific date range. The default is the last date of monitored data. sysfiles Determines whether system tables are to be migrated. The default is NO. A value of YES migrates the system tables. Example: Migrating a Resource Management Repository in UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os The following is an example of the migration executed in UNIX, Windows, UNIX System Services, OpenVMS, z/os and i5/os: edastart -x "EX GKEMIGRE oldconf=/eda/ibi/srv53/wfs, oldrel=530, oldeng=db2, oldown=edadba, oldsrv=edasrv1, todate= , frdate= , sysfiles=yes" iway Software

225 Configuring and Administering Resource Management From the Web Console After Completing the Migration When you have finished running the migration procedure, you must run the GKETABLE procedure to re-create the GKTABLE control file. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 10-43

226 Migrating the Resource Management Repository iway Software

227 11 Resource Analyzer Reports After you have enabled Usage Monitoring for a period of time and Resource Analyzer has collected a reasonable amount of data, you can display several reports and graphs about the monitored data. This chapter describes the various reports you can run and view with Resource Analyzer. Topics: Reports Overview Resource Analyzer Reporting Resource Analyzer Report Options General Reports Usage Analysis Reports Impact Analysis Report Performance Analysis Reports Network Analysis Reports Graph Reports Custom Reports

228 Reports Overview Reports Overview Resource Analyzer produces a range of different reports, depending on the type of information you want and the types of issues you are addressing: Monitored Data Summary. Opens the Monitored Data Summary report which provides information about data sources being monitored, including the number of queries, and the first and last access dates. Monitored Procedure Summary. Opens the Monitored Procedure Summary report, which provides information about procedures being monitored, including the number of executions, and the first and last execution dates. Procedures Never Used. Opens the Procedures Never Used report which lists the procedures in the APP PATH which have never been executed. Usage Analysis Reports. These reports represent the types of analysis most commonly used for research. They provide detailed information on users, procedures or data sources. Impact Analysis Report. This report provides information on the effects of column changes. Performance Analysis Reports. These reports are designed to help reduce excessive overhead. They help identify costly requests and unused data sources that may need to be reviewed to determine if the resource or storage usage could be reduced. Network Analysis Reports. These reports show network traffic on the Web server for requests Graph Reports. These reports provide a graphical view of peak transaction and resource periods, cumulative usage, and query volume versus resource utilization. Custom Reports. This option allows you to run customized reports, written according to your needs. See How to Create a Custom Report With WebFOCUS on page to learn how to create Usage Monitoring reports with WebFOCUS and how to deploy them on the Custom Report s page. For more information about how to access these reports, see Custom Reports on page Note: Before you begin running and viewing the various Resource Analyzer reports, review the general information about reporting with Resource Analyzer in Resource Analyzer Report Options on page iway Software

229 Resource Analyzer Reports Resource Analyzer Reporting How to: Access Resource Analyzer Reports Run Resource Analyzer Reports For all platforms except for MVS, Resource Analyzer reporting is accessed from the Web Console. Procedure: How to Access Resource Analyzer Reports To access Resource Analyzer reports: 1. Launch the server s Web Console. 2. Click Resource Management on the toolbar and expand the Reports and Resource Analyzer folders, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-3

230 Resource Analyzer Reporting Procedure: How to Run Resource Analyzer Reports To run Resource Analyzer reports: 1. Expand the Reports folder on the tree in the navigation pane. For more information, see How to Access Resource Analyzer Reports on page Click the desired report in the tree, and select Run from the context menu. The following image shows a Monitored Procedure Summary report being run. Note: In addition to Run, the Reports context menu also contains Run Deferred and List Deferred. Run Deferred prompts you for a date and time to execute the report and submits the report to the deferred queue. List Deferred lists the procedures that are deferred iway Software

231 Resource Analyzer Reports Resource Analyzer Report Options In this section: Selection Criteria Online Help Drilling Down With Reports Monitor Preference and Reports Alternate Reporting Output Finding the Report With the Information You Want How to: Set the Lines Per Page Turn Off Data Visualization Format a Report Set Selection Criteria Dates for Reports There is general information that applies to all Resource Analyzer reports. This information includes setting date ranges for report selection criteria, online help, drilling down on reports for more details, and displaying reports in graphical format. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-5

232 Resource Analyzer Report Options Selection Criteria Before you execute a report, you can select the date range of Usage Monitoring data to include along with other criteria used in the report. To specify these options, click the Reports folder on the tree in the navigation pane, then select Preferences from the context menu, as shown in the following image iway Software

233 Resource Analyzer Reports Note: To specify these options on MVS, click Report Options on top of the Resource Analyzer Reports window, shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-7

234 Resource Analyzer Report Options The Report Preferences window opens, as shown in the following image. By default, the Visualize Data checkbox is checked, indicating Data Visualization is ON, the Report format is set for HTML, and the Use Today s Date checkbox is checked, indicating that the default date in the End date input box is today s date. The default date in the Start date input box is January 1, The information you supply here will apply to any report you run. To change this information, return to this screen, then type and save the new criteria. Resource Analyzer report selection criteria information is saved from session to session, so you will not need to reset it when you re-connect to the server. Note: When connected to an MVS server, the window will look slightly different, and the Report format cannot be specified. Procedure: How to Set the Lines Per Page To set the lines per page: 1. Type the number of lines you wish in the Lines per page input box. 2. Click Save iway Software

235 Resource Analyzer Reports Procedure: How to Turn Off Data Visualization You now have the option of turning off Data Visualization when displaying reports. By default, the Visualize Data checkbox is checked, indicating that Data Visualization is ON, as shown in the following image. To turn off data visualization: 1. Uncheck the Visualize Data checkbox. 2. Click Save. Note: When connected to an MVS server, the window will look slightly different, and the Report format cannot be specified. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-9

236 Resource Analyzer Report Options Procedure: How to Format a Report To change the report format: 1. Click the Report format drop-down menu. If you are licensed for Active Reports, you can choose that as your report format. In the following image, the Active Report format is being selected from the drop-down menu. For more information on Active Reports, see the WebFOCUS Managed Reporting End User s Manual. 2. Select a format option. 3. Click Save. Note: When connected to an MVS server, the window will look slightly different, and the Report format cannot be specified iway Software

237 Resource Analyzer Reports Procedure: How to Set Selection Criteria Dates for Reports By default, January 1, 1995 appears in the Start Date input box and today s appears for the for the End Date input box. You may change these values by typing directly into the boxes, or by selecting dates from a pop-up calendar. The earliest start date you can enter is January 1, If you enter an earlier date it will automatically be changed to today's date. To set selection criteria dates for reports: 1. Type a date into the date input box on the left (Start Date). or Click the calendar icon that appears to the right the date input box. A calendar appears from which you can choose the month, day, and year for the Start date of the Usage Monitoring data on which you want to report. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-11

238 Resource Analyzer Report Options 2. Type a date into the End Date input box. or Click the calendar icon that appears to the right the End date input box. A calendar appears from which you can choose the month, day, and year for the start date of the Usage Monitoring data on which you want to report. Note: The Use Today's Date check box is already checked. If you want to use an end date other than the current date, you must uncheck the Use Today's Date checkbox; otherwise, today s date will be used. 3. Click Save. The report options window closes and, if you reopen the options window, the new values will appear. Note: Clicking Save is necessary. If you do not click Save, the options you choose will not be used in reporting. When connected to an MVS server, the window will look slightly different, and the Report format cannot be specified. Online Help When you run Resource Analyzer Reports you have an online help feature at your disposal, accessible through the? Help button in the report window. The online help provides background information about the report you are running. Drilling Down With Reports When you execute Resource Analyzer reports, initially, you will usually see a general summary report for the category. Most of the column headings of the reports are hyperlinked. Click the column heading links to re-sort the report by different columns. In addition, other hyperlinks in the report let you drill down to more detailed information. These hyperlinked drill-down options are described in more detail throughout this chapter. The sections below describe the individual reports. Some of these sections contain a table of drill-down links. In the tables of drill-down links, terms shown in italic represent placeholders, indicating the term can have different values, depending on the selections for that report iway Software

239 Monitor Preference and Reports Resource Analyzer Reports If you change the Monitor Preference setting and do not collect all the information, some reports will have missing data. When those reports are executed, the following message appears: This report is not available due to monitor preference. To enable this report contact your administrator and request that ALL DATA level granularity be enabled in Resource Analyzer and/or Resource Governor. Alternate Reporting Output Many Resource Analyzer reports can be output in both tabular and graphical formats. Reports can also be reformatted into a number of different outputs. Reports initially appear in the format specified by the Report format in the Resource Management: Report Properties pane. If the report is available in graphical format, a View Graph icon appears at the top of the report. Click the View Graph icon to view the report as a graph. To toggle back to tabular format, click the View Table icon at the top of the report. To reformat a report, click the Reformat As icon. The Reformat As option window opens, as shown in the following image. The window contains a Select Format drop-down menu, allowing you to choose a helper application in order to display reports a variety of formats. The format that you select will be used on any drill-down reports. Reports run from the tree will use the Report format set in the Resource Management: Report Properties pane. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-13

240 General Reports Finding the Report With the Information You Want Because Resource Analyzer reports are organized within an interconnected set of drilldown hyperlinks, many of the reports are accessible through multiple categories, depending on how far you drill down, or what path of hyperlinks you click through. To find the report with the information you need most quickly and efficiently, carefully consider in which general report category it is most likely to appear, and begin your reporting from within that category. General Reports In this section: Monitored Data Summary Monitored Procedure Summary Procedures Never Used These reports provide overviews of the data sources and procedures being monitored, as well as those procedures in the server s application path that have never been executed. Monitored Data Summary The Monitored Data Summary report provides an overview of the data sources that are being monitored, including the number of queries, and the date of first and last access. To access the Monitored Data Summary report in the Web Console, click Resource Management on the toolbar and expand the Reports folder. Click the Monitored Data Summary report, and select Run from the context menu iway Software

241 The following image shows the Monitored Data Summary report. Resource Analyzer Reports This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... Data_Source Report Generated Detailed Resource Usage Data Description Details the resources used by requests to the data sources Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-15

242 General Reports Monitored Procedure Summary The Monitored Procedure Summary report provides an overview of the procedures that are being monitored, including the number of executions, and the first and last execution dates. To access the Monitored Procedure Summary report in the Web Console, click Resource Management on the toolbar and expand the Reports folder. Click the Monitored Procedure Summary report, and select Run from the context menu. The following image shows the Monitored Procedure Summary report iway Software

243 Procedures Never Used Resource Analyzer Reports The Procedures Never Used report lists those procedures in the server s application path that have never been executed. To access the Procedures Never Used report in the Web Console, click Resource Management on the toolbar and expand the Reports folder. Click the Procedures Never Used report, and select Run from the context menu. The following image shows the Procedures Never Used report. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-17

244 Usage Analysis Reports Usage Analysis Reports In this section: Users Reports Procedures Reports Data Sources Reports Usage Analysis reports provide information on reporting activity. To access Usage Analysis reports in the Web Console, expand the Usage Analysis folder in the tree and then expand the appropriate Usage Analysis report folder (Users, Procedures or Data Sources). Click the desired type of usage analysis (Frequency of Use, Resources Used, or Historical Usage) and select Run from the context menu iway Software

245 Resource Analyzer Reports The following image shows the Usage Analysis and Users report folders expanded. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-19

246 Usage Analysis Reports Usage Analysis Categories There are three basic Usage Analysis categories: Users. This category provides a variety of information about the users at your site, such as how many requests each user submits, the dates and resource consumption of those requests, the data sources certain users are accessing the most, and whether they are issuing ad hoc or cataloged requests, summarized or detailed requests, and so on. Procedures. This category gives a variety of information about the remote procedures used to submit requests, including the actual syntax of the requests. Data Sources. This category shows how your data sources are being accessed, what kind of activity patterns are occurring at your site, and the earliest and latest data access dates. These reports show more detailed information, such as aggregate functions used against columns, and column use in relations, sorting, and grouping. Types of Usage Analysis Usage Analysis Reports can measure three types of usage: Frequency Usage. Focuses on how frequently particular data sources are accessed, users make requests, or procedures are executed. Resource Usage. Focuses on the resources consumed by requests to particular data sources, by particular users, or with particular procedures. Historical Usage. Shows data source, user, and procedure information over time iway Software

247 Resource Analyzer Reports Users Reports In this section: Users Report by Frequency Usage Users Report by Resource Usage Users Report by Historical Usage One of the best techniques for improving system performance is to educate users about request preparation. Education involves familiarizing users with what data is available and what constitutes the designs of different data sources. If users understand what is required of them in executing requests, their expectations about system response will be more realistic. After educating users, you can then organize elements of the data according to user needs, taking into account efficient grouping and clustering of this data. Some questions to consider about users are: Are users familiar with the cardinality of the data sources and the impact of multiple joins? Have the profiles of the users been identified? Who are the novices and who are the experienced users, and what are their habits and performance expectations? Do users visit data very often or sporadically? Are users profiles predictable or do they operate in binary mode, where most of the time they impose no activity on the system but sometimes they consume every computer resource possible? The Users reports help you analyze the activity of users at your site and determine such information as: whether users are novice or experienced, which data sources they are accessing most often, when they are using the most resources, and so on. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-21

248 Usage Analysis Reports Users Report by Frequency Usage The following image shows the Users Report by Frequency Usage, which provides a summary of user activity. This report lists users on the left, followed by columns with hyperlinked headings that indicate the number of requests the users submitted, their percentage of total requests and resource usage, and their first and last access dates. Click any of the hyperlinked column headings to re-sort the report by that column. This report has several hyperlinks that allow you to drill down to additional reports. The following table lists and describes these hyperlinks. Drill-Down Hyperlink: Click... A value under the User column. Report Generated Data Source Use by User Description Lists the data sources accessed by the specified user, information about the requests, and dates of access. Also allows you to drill down to see column and data type information, as well as procedures used in requests by the specified user iway Software

249 Resource Analyzer Reports Drill-Down Hyperlink: Click... A value under the Number Procedures column. A value under the % Total Requests column. A value under the % Total Resources column. Report Generated Procedure Summary for User Frequency of Use Procedure Summary for User Resources used by User Description Lists the procedures executed by the specified user along with statistics about each procedure s executions. Lists the procedures used for requests by the specified user, along with request and resource information and dates of access. Also allows you to drill-down to see detailed request information for each procedure as well as the actual request syntax. Summarizes the resource usage of the specified user, including number of requests, elapsed time, CPU seconds, I/Os, rows returned, and access dates. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-23

250 Usage Analysis Reports Users Report by Resource Usage The following image shows the Users Report by Resource Usage, which provides information on resource utilization by user. This report lists users along with the number of requests they submitted, total and average elapsed time, CPU seconds, I/Os, and rows, and their first and last access dates. Click any of the hyperlinked column headings to resort the report by that column. This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the User column. Report Generated Data Source Use by User Description Lists the data sources accessed by the specified user, information about the requests, and dates of access. Also allows you to drilldown to see column and data type information, as well as procedures used in requests by the specified user iway Software

251 Users Report by Historical Usage Resource Analyzer Reports The following image shows the Users Report by Historical Usage, which provides information on historical activity by user. This report lists users along with the number of requests they submitted in a particular year and the percentages of their requests and resource usage out of that year s totals. Click any of the hyperlinked column headings to re-sort the report by that column. This report has several hyperlinks that allow you to drill down to additional reports, summarized in the following table. Drill-Down Hyperlink: Click... A value under the User column. Report Generated Data Source Use by User Description Lists the data sources accessed by the specified user, information about the requests, and dates of access. Also allows you to drill down to see column and data type information, as well as procedures used in requests by the specified user. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-25

252 Usage Analysis Reports Drill-Down Hyperlink: Click... A value under the Year column. A value under the % Total Requests column. A value under the % Total Resources column. Procedures Reports In this section: Report Generated Access per Month for User during Year Procedure Access for User by Year by Month Resources used by User Description Summarizes by month the number of requests made by the specified user, along with the percentage of that user s requests and resource usage out of the particular date s totals. Lists the procedures executed by the specified user, by year and month, along with statistics about each procedure s executions. Also allows you to drill down to see detailed request information for each procedure as well as the actual request syntax. Summarizes the resource usage of the specified user, including number of requests, elapsed time, CPU seconds, I/Os, rows returned, and access dates. Procedures Report by Frequency Usage Procedures Report by Resource Usage Procedures Report by Historical Usage The Procedures reports supply a variety of information about the procedures with which users submit requests at your site. This information will help you compare the relative resource usage of cataloged versus ad hoc requests, find out which procedures are the most popular and frequently executed, and thus determine the truly mission-critical applications run at your site iway Software

253 Procedures Report by Frequency Usage Resource Analyzer Reports The following image shows the Procedures Report by Frequency Usage, which provides a summary of procedures being executed. This report lists procedures executed at your site by type, along with statistics about each procedure s executions. This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Type column. Report Generated Request from Procedure Ad hoc or Procedure Summary (depending on procedure type selected) Description Lists the date and time as well as user, resource, and execution information for all procedures of the specified type. Also allows you to drill down further to see the actual request syntax. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-27

254 Usage Analysis Reports Procedures Report by Resource Usage The following image shows the Procedures Report by Resource Usage, which provides a summary of resource utilization by procedure. This report summarizes the resource usage for the procedures executed at your site, including their percentage of total procedures and resources used, as well as total CPU seconds, elapsed time, I/Os, rows, and first and last execution. This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Type column. Report Generated Procedure Resource Utilization Description Summarizes the executions, users, total and average resource usage, and execution dates for procedures of all types. Also lets you drill down on procedure names to see more detailed usage information as well as the actual request syntax iway Software

255 Procedures Report by Historical Usage Resource Analyzer Reports The following image shows the Procedures Report by Historical Usage, which provides information on historical activity by procedures. This report summarizes by year the number of executions, users, and percentage of executions and resources used by the types of procedures at your site. Click any of the hyperlinked column headings to re-sort the report by that column. This report has two hyperlinks that allow you to drill down to another report, described in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Type column. A value under the Year column. Report Generated Procedure Access by Year by Month Same as above. Description Lists the year and month for all executed procedures of the specified procedure type, as well as their number and percentage of executions, their number of users, and their resource usage percentage. Same as above. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-29

256 Usage Analysis Reports Data Sources Reports In this section: Data Sources Report by Frequency Usage Data Sources Report by Resource Usage Data Sources Report by Historical Usage In order to improve system performance at your site, it is helpful to determine which data sources are most mission-critical, most popular among your users, and most resourceintensive. The Data Sources reports show you how your data sources are being accessed as well as illustrate various activity patterns at your site and the earliest and latest dates that data was accessed. Data Sources Report by Frequency Usage The following image shows the Data Sources Report by Frequency Usage, which provides a summary of data sources being used. This report lists all accessed data sources along with the number and percentage of requests to each data source, the number of users, the percentage of resources consumed, and access dates. Click any of the hyperlinked column headings to re-sort the report by that column iway Software

257 Resource Analyzer Reports This report has several hyperlinks that allow you to drill down to additional reports, summarized in the following table. Drill-Down Hyperlink: Click... A value under the Data Source column. A value under the Data Type column. A value under the Number Requests column. A value under the Number Distinct Users column. A value under the % Total Requests column. A value under the % Total Resources column. Report Generated Column Level for Data Source Data Source Data Sources of type Data Type Request Activity for Data Source: Data Source Users of Data Source Procedures Using Data Source Resources Used by Data Source Description Shows usage for the columns for the specified data source, including whether they were used with functions, relations, selects, sorts, and groups, and how many days the column has been unused. Also allows you to drill down to see more information about when the columns were used. Lists all the data sources of the specified data type (the engine used in your enterprise) along with the dates of first and last access for each data source. Shows request activity for all users of the specified data source, including I/ Os, rows returned, and elapsed time. Also allows you to drill- down further to see the actual request syntax. Lists all users of the specified data source along with a summary of the resources they have used. Lists the procedures used to access the specified data source, along with their resource usage and dates of access. Also allows you to drill-down on a procedure name to see request information for that procedure and the actual request syntax. Lists the resources used by the specified data source, sorted by date. Also allows you to drill down on the dates to see more detailed data access information by month. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-31

258 Usage Analysis Reports Data Sources Report by Resource Usage Understanding the patterns of resource usage at your site, including CPU and elapsed time, I/Os, and rows returned, can be helpful in several ways. This kind of information can help you determine which data sources might be good candidates for pre-joining, preaggregation, or denormalization, and decide which data to index. In addition, you can monitor users and inform them of their resource usage to encourage them to plan their requests more efficiently. Accessing the Data Sources report category by the Resource Utilization mode of analysis can help you with all of these issues. The following image shows the Data Sources Report by Resource Usage, which provides a summary of resource utilization by data source. This report summarizes the resources used by all data sources at your site, including both total and average elapsed time, CPU seconds, I/Os, and returned rows. Click any of the hyperlinked column headings to re-sort the report by that column iway Software

259 Resource Analyzer Reports This report has several hyperlinks that allow you to drill down to additional reports, summarized in the following table. Drill-Down Hyperlink: Click... A value under the Data Source column. A value under the Data Type column. A value under the Number of Requests column. Report Generated Column Level for Data Source Data Source Data Sources of type Data Type Procedures Using Data Source Description Shows usage for the columns for the specified data source, including whether they were used with functions, relations, selects, sorts, and groups, and how many days the column has been unused. Also allows you to drill down to see more information about when the columns were used. Lists all the data sources of the specified data type (the engine used in your enterprise) along with the dates of first and last access for each data source. Lists the procedures used to access the specified data source, along with their resource usage and dates of access. Also allows you to drill down on a procedure name to see request information for that procedure and the actual request syntax. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-33

260 Usage Analysis Reports Data Sources Report by Historical Usage The accessibility of a Web environment makes rapid growth of your user base inevitable. As more users are accessing more data, monitoring site activity becomes more important, offering you information about the following areas: How much data is being requested. What the busiest times of the day, week, and month are. Which users are most active against which data sources. What standard response times have been. Accessing the Data Sources report category by historical analysis lets you analyze user activity to determine the peaks and valleys in system usage, supplying you with a solid basis for deciding how to schedule requests, educate users, and so on. The following image shows the Data Sources Report by Historical Usage, which provides information on historical activity by data source. This report summarizes request activity by year and month for all accessed data sources at your site. Click any of the hyperlinked column headings to re-sort the report by that column iway Software

261 Resource Analyzer Reports This report has several hyperlinks that allow you to drill down to additional reports, summarized in the following table. Drill-Down Hyperlink: Click... A value under the Data Source column. A value under the Data Type column. A value under the Month column. A value under the Number Distinct Users column. Report Generated Column Level for Data Source Data Source Data Sources of type Data Source Data Access for Data Source during Month Year User Activity Historical Analysis Using Data Source Data Source Description Shows usage for the columns for the specified data source, including whether they were used with functions, relations, selects, sorts, and groups, and how many days the column has been unused. Also allows you to drill down to see more information about when the columns were used. Lists all the data sources of the specified data type (the engine used in your enterprise) along with the dates of first and last access for each data source. Shows data access information for the specified data source and month, including number of requests, elapsed time, CPU seconds, I/Os, and rows returned. Also allows you to drill down on a specific date (month, day, and year) to see request information for that date as well as the actual request syntax. Lists the users for the specified data source by year and month along with request and usage information. Also lets you drill down to see a variety of more detailed resource, request, and access information. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-35

262 Impact Analysis Report Drill-Down Hyperlink: Click... A value under the % Total Requests column. A value under the % Total Resources column. Impact Analysis Report In this section: Report Generated Procedures Using Data Source during Month Year Resources Used by Data Source during Month Year Description Lists the procedures used to access the specified data source, along with their resource usage and dates of access. Also allows you to drill down on a procedure name to see request information for that procedure and the actual request syntax. Lists the resources used by the specified data source, sorted by date. Also allows you to drill down on the dates to see more detailed data access information by month. Change Impact for Column Report The Impact Analysis Report provides information on the affects of column changes. To access the Impact Analysis report in the Web Console, click Resource Management on the toolbar and expand the Reports and Resource Analyzer folders. Expand the Impact Analysis folder. Click the desired report, and select Run from the context menu. The available report is the Change Impact for Column Report. It provides which procedures and end users will be affected by changes to column names and format. This report supplies you with information that can help you understand the rippling effects of data schema changes. Note: In the tables of drill-down links, terms shown in italic represent placeholders, indicating the term can have different values, depending on the selections for that report iway Software

263 Change Impact for Column Report Resource Analyzer Reports It is very useful to determine in advance which users and applications will be most affected by impending data source schema changes. The Change Impact for Column reports determine how data-source modifications affect users and their applications. Click the Change Impact for Column Report and select Run. Enter the name of the column for which you want to examine information and click View Report. Any use of a column with that name in any monitored table is reported. The report window opens, as shown in the following image. This report summarizes the procedures used to access the specified column. This report has two hyperlinks that allow you to drill down to additional reports summarized in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Name column. A value under the Data Source column. Report Generated Requests from Procedure Procedure Name Column Level for Data Source Data Source Description Shows a variety of information, including date and time, user, CPU seconds, elapsed time, I/Os, and rows returned, about the requests made with the specified procedure. Also allows you to drill down further to see the actual request syntax. Shows usage for the columns for the specified data source, including whether they were used with functions, relations, selects, sorts, groups, or never used. Also allows you to drill down to see more information about when the columns were used. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-37

264 Performance Analysis Reports Performance Analysis Reports In this section: Procedure Benchmarks Report CPU Bound, I/O Bound, Large Answer Set Procedures Report Long-running Requests Report Large Volume Request Report Dormant Data Report Excessive Joins Report Repeated Aggregations Report Candidates for Column Index Report Performance Analysis Reports are designed to help reduce excessive overhead. They help identify costly requests and unused data sources that may need to be reviewed to determine if the resource or storage usage could be reduced iway Software

265 Resource Analyzer Reports To access Performance Analysis reports in the Web Console, click Resource Management on the toolbar and expand the Reports and Resource Analyzer folders. Expand the Performance Analysis folder. Click the desired report, and select Run from the context menu, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-39

266 Performance Analysis Reports The following reports are available: Procedure Benchmarks Report. Measure iterative improvements in resource expenditure and analyze the response time of requests to determine whether Service Level Agreement (SLA) standards are being met. CPU Bound, I/O Bound, Large Answer Set Procedures Report. View the most resource-intensive requests to identify causes of network and machine use bottlenecks. Long-running Requests Report. Uncover procedures with long-running requests, which use excessive resources and result in long waits for users. Large Volume Request Report. Identify requests returning more data than necessary and target them for optimization. Dormant Data Report. Uncover which data sources, columns, and data are infrequently or never accessed, and which can make response times slower and batch updates more cumbersome. This helps you decide how to better organize your data sources. Excessive Joins Report. Reveal which columns are frequently joined, helping you determine how to create pre-joined tables. Joining too many tables is expensive and slow. Repeated Aggregations Report. Show which data sources might be the best candidates for summarization or pre-aggregation, to improve performance. This helps you avoid Aggregations can cause bottlenecks during query execution. Candidates for Column Index Report. Identify columns that should be indexed. Note: In the tables of drill-down links, terms shown in italic represent a placeholder, indicating the term can have different values, depending on the selections for that report iway Software

267 Procedure Benchmarks Report Resource Analyzer Reports Benchmarking is a process by which you determine whether your site s service level agreements (SLAs) are being met. Use the Procedure Benchmarks reports to identify response times for requests and other information for analyzing site performance. Click the Procedure Benchmarks report on the tree in the navigation pane and select Run from the context menu. A pane containing a Benchmark Procedure input box opens, as shown in the following image. In the Benchmark Procedure input box, type the name of the procedure for which you wish to examine information and click View Report. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-41

268 Performance Analysis Reports The Monitored Procedure Detail report appears, showing, as shown in the following image. This report shows information about executions of the specified procedure, including execution date and time, user, CPU and elapsed time, usage type and client type. Click any of the hyperlinked column headings to re-sort the report by that column iway Software

269 Resource Analyzer Reports CPU Bound, I/O Bound, Large Answer Set Procedures Report Some of the most helpful information Resource Analyzer can provide is about which requests are using the most resources. This kind of information helps you identify causes of network and machine-use bottlenecks and enables you to decide what data needs to be indexed, what requests need to be scheduled, or which users need to be educated. The CPU Bound, I/O Bound, Large Answer Set Procedures reports help you with this investigation. Click the CPU Bound, I/O Bound, Large Answer Set Procedures report and select Run from the context menu. A window appears with input boxes for the user to enter IOs, rows, CPU time, and elapsed time, as shown in the following image. For a request to be included in the report, it need only exceed one of the resource values specified, not all. Specify criteria to limit your report to information on requests that consume resource usage values above a certain average and click View Report. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-43

270 Performance Analysis Reports The CPU Bound, I/O Bound, Long Running or Large Answerset Procedures report appears, as shown in the following image. This report lists the most resource-intensive procedures, those whose average resource usage values, including CPU seconds, elapsed time, I/Os, and rows returned, exceed at least one of the limits you specified. The report also lists the average resource usage values for each procedure. Click any of the hyperlinked column headings to re-sort the report by that column. This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Name column. Report Generated Requests from Procedure Procedure Description Lists the date and time, user, and resource information for each request of the specified procedure. Also allows you to drill down further to see the actual request syntax iway Software

271 Long-running Requests Report Resource Analyzer Reports Procedures with long running requests use excessive resources, a particular problem when dealing with operational systems. These procedures should be targeted for optimization. Click the Long-running Requests report and select Run from the context menu. The report window opens, as shown in the following image. By default the report is sorted by Average Elapsed Seconds and Average CPU Seconds. This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Name column. Report Generated Requests from Procedure: Procedure Name Description Shows the requests that were executed from the selected procedure. Also allows you to drill down further to see the actual request syntax. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-45

272 Performance Analysis Reports Large Volume Request Report Large volume requests are requests that return more data than might be necessary. These requests can be targeted for optimization. You can identify these reports with the Large Volume Requests Report. Click the Large Volume Requests report and select Run from the context menu. The report window opens, as shown in the following image. By default the report is sorted by Highest Average Rows. This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Name column. Report Generated Requests from Procedure Name Description Shows the requests that were executed from the selected procedure. Also allows you to drill down further to see the actual request syntax iway Software

273 Dormant Data Report Resource Analyzer Reports Dormant data, or data that is very infrequently accessed, can slow response times on your site. Use the Dormant Data reports to identify which data sources and columns have been less recently or never queried and can be deleted or archived to improve performance. Click the Dormant Data report and select Run from the context menu. The report window opens, showing, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-47

274 Performance Analysis Reports This report shows a variety of information about each data source, such as number of requests, users, resource usage, and access dates. The Days Since Used column indicates the number of days that have passed since the data source was last accessed. The report also includes a Never Used? column that uses a sleep icon to indicate that a data source has never been accessed and is therefore dormant. By default, the report is sorted by access dates, with those data sources that have no access dates (and are therefore dormant) listed first, and includes all data sources in the application path, including those that aren't being monitored. This report has one hyperlink that allows you to drill-down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Data Source column. Report Generated Dormant Data Summary: Column Level for Data Source Description Shows which columns were never accessed in the specified data source, and also lists all accessed columns along with last access time in days. Shows usage for the columns, including whether they were used with functions, relations, selects, sorts, and groups iway Software

275 Excessive Joins Report Resource Analyzer Reports Joining too many tables can be slow and costly. De-normalization can be an effective method for cutting CPU time and improving response times. The Excessive Joins reports help you determine which data is most frequently joined by user requests, and helps you decide how to plan your de-normalizing strategies. Click the Excessive Joins report and select Run from the context menu. The report window opens, listing, as shown in the following image. This report lists the most frequently joined data sources along with the procedures used to join them. This report has one hyperlink that allows you to drill-down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Procedure Name column. Report Generated Requests from Procedure Joining Data source1, Data source2, Data sourcen Description Shows a variety of information, including date and time, user, CPU seconds, elapsed time, I/Os, and rows returned, about the requests making the specified join. Also allows you to drill-down further to see the actual request syntax. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-49

276 Performance Analysis Reports Repeated Aggregations Report Efficiencies can be created by calculating column values once and storing the results in summary tables for repeated use. This saves the cost of calculating these values every time a report is run. Click the Repeated Aggregations report and select Run from the context menu. The Candidates for Summary Level Databases report opens, as shown in the following image. This report shows how many requests used different functions on certain columns of data sources, along with the dates of access. Click any of the hyperlinked column headings to re-sort the report by that column iway Software

277 Resource Analyzer Reports This report has one hyperlink that allows you to drill down to another report, as described in the following table. Drill-Down Hyperlink: Click... A value under the Function column. Report Generated Procedure Summary - Frequency of Use Using Function on Data Source.Column Name Description Summarizes the procedure types (cataloged and ad hoc) that have executed the specified function for the specified data source and column, along with statistics about each procedure s executions. Also allows you to drill-down further to see a list of the cataloged procedures and information about them. Candidates for Column Index Report Indexing columns that are frequently used in selection criteria for reports can improve efficiency. This report identifies columns that should be indexed. Click the Candidates for Column Index report and select Run from the context menu. The report window opens, as shown in the following image. This report shows how often columns were used as selection criteria in requests. Click any of the hyperlinked column headings to re-sort the report by that column. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-51

278 Network Analysis Reports This report has two hyperlinks that allows you to drill-down to another report, described in the following table. Drill-Down Hyperlink: Click... A value under the Data Source column. A value under the Data Type column. Report Generated Column Level for Data Source Data Source Data Sources of type Data Type Description Shows usage for the columns for the specified data source, including whether they were used with functions, relations, selects, sorts, groups, or never used. Also allows you to drill-down for information about when the columns were used. Shows the data sources of that type and their first and last access dates. Network Analysis Reports In this section: Bandwidth by Database Report Resources by Connection This new category of Resource Analyzer reports shows network traffic for requests on the Web server, for example, the users for each connected IP address iway Software

279 Resource Analyzer Reports To access Network Analysis reports in the Web Console, click Resource Management on the toolbar and expand the Reports and Resource Analyzer folders. Expand the Network Analysis folder. Click the desired report, and select Run from the context menu, as shown in the following image. The following reports are available: Bandwidth by Database. Shows the number of bytes retrieved to the Web server for requests. The report analyzes the bandwidth by database type for each year/month combination. Resources by Connection. Shows the resources consumed by the different IP connections. Note: In the tables of drill-down links, terms shown in italic represent a placeholder, indicating the term can have different values, depending on the selections for that report. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-53

280 Network Analysis Reports Bandwidth by Database Report The Bandwidth report shows the number of bytes retrieved to the Web server for requests. The report analyzes the bandwidth by database type for each year/month combination. Click the Bandwidth by Database report and select Run from the context menu. The report window opens, as shown in the following image. This report has two hyperlinks that allows you to drill-down to another report, described in the following table. Drill-Down Hyperlink: Click... A value under the Database column. A value under the Year/Month. Report Generated Bandwidth for Data Sources for Database Type Bandwidth by Day for Database Type during Year/ Month. Description Shows the bandwidth for each data source of the database type. Shows the bandwidth for each day of the selected year/month iway Software

281 Resources by Connection Resource Analyzer Reports Resources by Connection report shows the resources consumed by the different IP connections. Click the Resources by Connection report and select Run from the context menu. The report window opens, as shown in the following image. This report has one hyperlink that allows you to drill-down to another report, described in the following table. Drill-Down Hyperlink: Click... A value under the Connection column. Report Generated Resources by Connection in Network Node Description Shows the resources for each connection address. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-55

282 Graph Reports Graph Reports In this section: Peak Transaction/Resource Periods and Cumulative Hourly Use Reports Query Volume vs. Resource Utilization Reports Resource Analyzer provides a number of graphs for resource and performance analysis. To access Graph Reports in the Web Console, click Resource Management on the toolbar and expand the Reports and Resource Analyzer folders. Expand the Graph Reports folder. Click the desired report, and select Run from the context menu, as shown in the following image iway Software

283 The eight Resource and Performance Analysis Graphs appear in the tree: Resource Analyzer Reports Peak Transaction Periods By Hour of Day. Determine transaction-bottleneck periods by hourly request activity. By Day of Week. Determine transaction-bottleneck periods by daily request activity. By Month. Determine transaction-bottleneck periods by monthly request activity. Peak Resource Periods By Hour of Day. Determine transaction-bottleneck periods by hourly resource usage. By Day of Week. Determine transaction-bottleneck periods by daily resource usage. By Month. Determine transaction-bottleneck periods by monthly resource usage. Cumulative Hourly Use. Determine hourly system usage. Query Volume vs. Resource Utilization. Profile query volume against system resource utilization. Peak Transaction/Resource Periods and Cumulative Hourly Use Reports These graph reports allow you to determine transaction-bottleneck periods for request activity or resource usage by different time periods. Click a graph report and select Run from the context menu. The Run Report window opens, as shown in the following image. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-57

284 Graph Reports You can filter a report by data source name and/or user by entering a valid data source name and/or user name, or by entering ALL, to indicate all data sources and all users. The default is ALL. After you select your data sources or accept the default, click View Report. The following image shows an example of the Cumulative Hourly Use graph iway Software

285 Query Volume vs. Resource Utilization Reports Resource Analyzer Reports Un-tuned queries frequently return more data than necessary. Identify the procedures running these requests and target them for optimization. Click the Query Volume vs. Resource Utilization report, and select Run from the context menu. The report window opens, as shown in the following image. This report compares the number of requests to one of four factors of resource usage: CPU seconds, elapsed time in seconds, rows returned, and I/Os (all mapped on the vertical axis). This information is shown for each hour of the day, with the hours mapped along the horizontal axis. The values on the vertical axis are cumulative for the time period of the dates you select for Usage Monitoring data for reports. For more information on setting report date ranges, see Selection Criteria on page By default, the first graph that appears shows requests graphed against CPU seconds. To view the graph for requests versus one of the other resource factors, select the appropriate option at the top of the screen and click the Draw button. The new graph appears. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-59

286 Custom Reports Custom Reports How to: Create a Custom Report With WebFOCUS You can create customized reports that appear on the Resource Analyzer reporting pages by using any WebFOCUS tools for report development. WebFOCUS enables developers to quickly prototype and deploy reports on the web. When you have finished creating your report(s), move the reports and any support files to an application directory in the server's application path on the WebFOCUS server. Once the new reports are deployed on the WebFOCUS server, they can be added to Resource Analyzer's Custom Reports page. For more information on building reports with WebFOCUS, see the Creating Reports With WebFOCUS Language manual or the Creating Reports With Graphical Tools manual. To access Custom Reports in the Web Console, click Resource Management on the toolbar and expand the Reports and Resource Analyzer folders, and click the Custom Reports. The list of available Custom Reports appears in the right pane, as shown in the following image. The list of reports can be customized to include your own WebFOCUS reports. To run a report, simply click the Report name. Procedure: How to Create a Custom Report With WebFOCUS 1. Create a report using WebFOCUS. For more information on building reports with WebFOCUS, see the Creating Reports With WebFOCUS Language manual or the Creating Reports With Graphical Tools manual. Make sure to test the procedure before adding it to the Custom Reports page. 2. Copy the procedure to an application directory in the server's APP PATH on the WebFOCUS server iway Software

287 Resource Analyzer Reports 3. Edit the file named rargcust.htm. On Windows XP/2000, UNIX, UNIX System Services, OpenVMS, and i5/os, the file is located in the server s home\etc directory. On MVS, it is located in the web server s virtual directory named ibi_start. Edit this file to accommodate your new report titles and descriptions. Locate the section Beginning of lines to duplicate/modify for each report. It is in that section that you will make your changes. First, include the reference to the name of the report (FOCEXEC) that will be executed. In the line: <TD height="43" width="150"><a HREF='#' Replace the # with the link to the report, as follows: <TD height="43" width="150"><a HREF='javascript:linkTo("myreport") Note that myreport is the name of the newly created report without the.fex extension. Next, provide the flyover help and the text that appears for the Hyperlink. In the line: title='right click this page and select View Source to see comments on adding your reports'>report name</a> Replace the text in the title with the text for flyover help, and replace the words Report name with a user friendly report name that will appear on the window for the Hyperlink. For example: title='this is a custom report added on 12/29'>My custom report</a> Finally, provide a description for the new report. In the line: <TD height="43">report description goes here.</td> Replace the words Report description goes here with the description of the new report. For example: <TD height="43">custom Report for RA.</TD> For example, after editing, the lines would look like this: <TD height="43" width="150"><a HREF='javascript:linkTo("myreport")' title='this is a custom report added on 12/29'>My custom report</a></ TD> <TD height="43">custom Report for RA.</TD> Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 11-61

288 Custom Reports On Windows XP/2000, UNIX, UNIX System Services, OpenVMS, and i5/os, save the edited file in the server's baseapp directory. By default, that directory is [drive]:\ibi\apps\baseapp. On MVS, save the edited file in the web server s virtual directory named ibi_start. The report will now appear on the Custom Reports page, as shown in the following image. 4. Click the report name to view your report iway Software

289 12 Setting Up DataMigrator Before you create data flows and process flows in DataMigrator, setup steps must be completed. The Data Management Console (DMC) is used to perform the major setup and administration tasks that are required before you can build flows. As a developer, you will probably perform most of these tasks yourself. Some DataMigrator setup tasks may be performed by a server administrator, if that is a separate function in your organization. A server administrator may use the Web Console to perform these tasks, which may vary somewhat based on how and where data is stored at your site. As an alternative, the Web Console can also be used to perform the setup and administration tasks that are available in the DMC. You can use this chapter as a checklist to ensure that, regardless of the distribution of setup tasks at your site, all of the preparation steps are completed before your design work begins. Topics: DataMigrator Setup At a Glance Remote Server Setup At a Glance DataMigrator Setup Initiating Server Administration Tasks Authorizing DataMigrator Server Usage and Administration Managing Application Directories and Configuring the Application Path Configuring Data Adapters Creating Metadata Testing Sample Data and Process Flows Performing Server Administration Tasks From the Web Console Upgrading DataMigrator From Version 4.3 or 5.1

290 DataMigrator Setup At a Glance DataMigrator Setup At a Glance The two principal components of DataMigrator are the iway DataMigrator Server, which includes the Web Console, and the Data Management Console. 1. Install the DataMigrator Server on the platform that will contain your target data (this is the platform you will be moving data to). DataMigrator Server is typically installed on the platform where your data target (a data warehouse, data mart, or another type of target) will reside. Your first task is determining that location. The following list of tasks assumes that your source data resides on that same platform. Note: At many sites, source data is on a different platform from the one on which the DataMigrator Server is installed. If this is the case at your site, you need to install, configure, and test one or more remote servers, using the process described in Remote Server Setup At a Glance on page For Windows servers, the DMC is installed with the server. For non-windows servers, you need to install the DMC separately. See How to Install the Data Management Console on page The DMC can be installed on each Windows machine that will be used to build flows or on a shared network drive. 3. Start the DataMigrator Server. 4. Start the DMC from the iway Software>iWay 76 DM Client group in the Windows Start menu. For Windows servers, the DMC is under iway Software>iWay 76 DataMigrator Server. 5. Configure one or more nodes in the DMC s configuration file. This step identifies the name and port of the DataMigrator Server you will be connecting to and adds the server name(s) to the DMC s server list. See How to Add a Node to Identify the Server to the Data Management Console on page Tip: If, during the installation of the DMC, you configured it to access the DataMigrator Server, this step is optional. When installing a Windows server, a default LOOPBACK node is configured. This node shouldn t be deleted. 6. Connect to and test the DataMigrator Server from the DMC. You can test that the server is started and able to perform basic data retrieval (against sample data). See How to Test the Server on page You can also test the server from the Home page of the Web Console iway Software

291 Setting Up DataMigrator 7. Configure and test data adapters for the source data you will be using from the DMC s Adapters tab. The test verifies that the configuration was successful and you can access the data adapter. You can also configure and test adapters from the Configuring Data Adapters page of the Web Console. Note: If all of your source data is stored on remote servers, omit this step and Step 8 and proceed to Step Create and test the metadata for the source data from the DMC. The test verifies data retrieval functionality for the specific data sources you are using. You can also create and test the metadata from the Managing Metadata page of the Web Console. Note: If you are using more than one data source for the same adapter, repeat Step 8 as many times as necessary before going to Step 9. If, however, you have data sources in a variety of adapters, repeat Step 7 and Step 8, then proceed to Step Configure and test the data adapter for the data target from the DMC s Adapters tab. You can also configure and test adapters from the Configuring Data Adapters page of the Web Console This step is necessary if the data target is of a different database type than the data source(s) or if all of your data is on remote servers. After completing this step, proceed to Step 10. Note: If you have more that one data adapter for your data targets, repeat Step 9 as many times as necessary. Step 9 is not necessary if the data target(s) and data source(s) are of the same database type. Proceed from Step 8 to Step Create and test the metadata for one or more data targets from the DMC. You can also create and test the metadata from the Managing Metadata page of the Web Console. Note: This step assumes that you are moving data to existing target tables. If you are building new target tables in the DMC, this step is not required. 11. Open and test three sample flows dmvpx, dmvpy, and dmvpz which are provided for this purpose. For each one, run and view the last log to confirm that the DataMigrator Server is configured and properly processing flows. See Testing Sample Data and Process Flows on page Configure server operations, including security, runtime ids, log and statistics tables. See Performing Server Administration Tasks From the Web Console on page Note: Authorize any users who will be using DataMigrator from the Data Management Console or Web Console. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-3

292 Remote Server Setup At a Glance 13. Configure the application path and set up additional application directories. See Managing Application Directories and Configuring the Application Path on page These procedures can also be performed from the Web Console. 14. Configure notification and the scheduler from the Web Console s DataMigrator Workspace configuration page. See Configuring DataMigrator Server Operations on page For detailed information about the Web Console pages used to set up DataMigrator for local data access, see Performing Server Administration Tasks From the Web Console on page Remote Server Setup At a Glance Although the DataMigrator Server is typically installed on the same platform as the target data for DM applications, there is no such restriction for source data. In fact, the DataMigrator Server frequently resides on one platform while the source data resides on one or more platforms that are remote from the DataMigrator Server itself. In these situations, you must configure the remote servers (also called subservers) to make the data accessible to the DataMigrator Server for processing. First, complete the basic DataMigrator Server configuration steps described in DataMigrator Setup At a Glance on page After completing these steps, you are ready to start the setup for one or more remote servers. To set up the remote server, complete these steps: Configure remote servers for data sources and create metadata. Return to the DataMigrator Server and configure it to access the remote servers so that you can use the data residing there. The following steps describe this process: 1. Install (if necessary) the remote server on the platform required by your site. (In many situations, the remote server may have already been installed.) 2. Start the DMC from the iway Software>iWay 76 DM Client group in the Windows Start menu. For Windows servers, the DMC is under iway Software>iWay 76 DataMigrator Server. 3. Configure one or more nodes for the remote server in the DMC s configuration file. This step identifies the name and port of the remote server you will be connecting to and adds the server name(s) to the DMC s server list. See How to Add a Node to Identify the Server to the Data Management Console on page iway Software

293 Setting Up DataMigrator 4. Connect to and test the remote server from the DMC. You can test that the server is started and able to perform basic data retrieval (against sample data). See How to Test the Server on page You can also test the server from the Home page of the Web Console. 5. Configure and test the data adapter(s) for the data source(s) you will be using from the DMC s Adapters tab. The test verifies that the configuration was successful and you can access the data adapter. You can also configure and test adapters from the Configuring Data Adapters page of the remote server's Web Console. 6. Create and test the metadata for the data source(s) you will be using from the DMC. The test verifies data retrieval functionality for the specific data sources you are using. You can also create and test the metadata from the Managing Metadata page of the remote server's Web Console. Note: If you are using more than one data source for the same adapter, repeat Step 6 as many times as necessary before going to Step 7. If, however, you have data sources in a variety of adapters, repeat Step 5 and Step 6, then proceed to Step Connect the DataMigrator Server to the remote servers. Once you have installed and configured the remote servers, with their data sources, you must establish a connection from the DataMigrator Server to the remote servers so that DataMigrator will be able to access the data that resides on those servers. To do this, you return to the DataMigrator Server s Web Console Home page and select Remote Servers from the navigation pane. To add the connection to the remote server(s), you click Add in the navigation pane. 8. Create metadata to mirror the metadata on the remote server(s) from the DataMigrator Server's Web Console Remote Servers page. (Note that for remote servers you create metadata from the Remote Servers page rather than from the Metadata page that you used for the DataMigrator Server.) This step makes the data on the remote server accessible to the DataMigrator Server. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-5

294 DataMigrator Setup DataMigrator Setup How to: Install the Data Management Console Launch the Data Management Console and Connect to a Server Add a Node to Identify the Server to the Data Management Console Test the Server Reference: WebFOCUS Environments Requirements for Installing the Data Management Console In addition to providing a graphical interface for designing flows, the DMC can also be used to perform the major setup and administrative tasks. Note: When you install a Windows server on a machine where you re building flows, the DMC is installed automatically. For other server types or for access to remote Windows servers, the DMC must be installed separately. Reference: WebFOCUS Environments The DMC allows you to configure the mid-tier environment for a WebFOCUS server. If you have a WebFOCUS server and Developer s Studio, the DMC will have an additional entry in the tree for WebFOCUS environments. There will be an entry for each WebFOCUS server iway Software

295 Setting Up DataMigrator Right-clicking a server name under WebFOCUS environments and selecting Properties opens the WebFOCUS Environment Properties dialog box. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-7

296 DataMigrator Setup Right-clicking a server name under WebFOCUS environments and selecting Access Servlet Administration opens the iway Web Console Servlet Configuration page, which shows configuration files for the server, communication s, and the workspace. Reference: Requirements for Installing the Data Management Console To install the DMC, you need the following: Pentium 550 mhz processor or higher. 79 MB of hard disk space. 512 MB of RAM. SVGA or higher resolution graphics card set to at least 800 X 600 pixels and high color (16 bit). (The preferred setting is 1024x768, with a color depth of 16 bits.) CD/DVD drive for installation. A mouse or compatible pointing device supported by Windows. A network (TCP/IP) connecting to the DataMigrator Server. Windows 2000, 2003 or XP iway Software

297 Setting Up DataMigrator Procedure: How to Install the Data Management Console 1. Close any open programs. 2. Insert the iway 76 Windows CD-ROM in your CD-ROM drive. The setup program will start automatically. If it does not, run SETUP.EXE. The setup program begins and the InstallShield Wizard opens. 3. In the Choose Setup Language window, select a language and click Next. The License Agreement opens. 4. Click Yes to accept the terms of the license agreement. If you do not accept the terms of this agreement, click No to exit the InstallShield Wizard. If you click Yes, the Software Registration window opens. 5. Enter your user name, company name, and license key in the corresponding fields. Your license key is found on the packing slip you received with your iway 76 Data Management Tools CD. Click Next. The InstallShield Wizard displays the Select Program Folder window. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-9

298 DataMigrator Setup 6. The default Program Folder name, as it will appear in the Windows Start menu, is IWAY 76 Client. If you wish to use a different folder name, enter it here. (You can also choose a folder from the Existing Folders list.) Click Next. The Select the Standard Location Prompt dialog box opens iway Software

299 Setting Up DataMigrator 7. Select a radio button for a local or network drive installation and click Next. The Select Directories window opens. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-11

300 DataMigrator Setup 8. Accept the default root and product configuration directories, or browse to directories in which you prefer to install your software. Accept the default disk designation or, if applicable, choose another disk from the list. 9. Click Next. 10. The Configure Remote Server window opens. When you install the software, you can set up communication to a server. When you start the software, the server you identify here appears in the Server list in the navigation pane. If necessary, you will be able to enter additional server nodes as needed, after the installation is completed iway Software

301 Setting Up DataMigrator 11. Click Next. In the Node box, enter the name of the DataMigrator Server. In the Host box, enter the machine name or IP address where the DataMigrator Server is running. In the Port box, enter the Port number of the DataMigrator Server. If you used the defaults when you installed your DataMigrator Server, the HTTP Listener port number is 8117 and the TCP Listener port number is Optional. If you enter a User ID and password in the Security input boxes, the iway client saves the entries, setting security to Explicit by default. You will not be prompted for them again from the DMC. Optional. You can enter Local User Credentials (local password) to start a service for the DMC on your local machine. This enables you to open the Web Console from your browser, where you can configure your DM client. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-13

302 DataMigrator Setup Files are copied to the designated locations. Percent of progress is noted during this process. Informational messages indicate that setup is configuring the product based on your specifications and that the program folder and icons are being created. 12. Optionally, you can start the DataMigrator Server and Web Console, or start the Data Management Console as soon as the installation is complete. 13. Click Finish. Procedure: How to Launch the Data Management Console and Connect to a Server Note: For non-windows server installations, the DMC is under iway Software>iWay 76 DM Client>Data Management Console. For Windows server installations, the DMC is under iway Software>iWay 76 DataMigrator Server>Data Management Console. 1. From the Windows Program menu, choose iway Software>iWay 76 DM Client>Data Management Console or iway Software>iWay 76 DataMigrator Server>Data Management Console. The DMC opens, with the available servers appearing under Procedures in the navigation pane on the left. 2. Right-click on the server you wish to use and select Connect. The Enter Connection Information dialog box opens. 3. If your server has security enabled, enter your user ID and password in the User Name and Password fields. Windows requires that your user name be no longer than 32 characters iway Software

303 Setting Up DataMigrator Note: If you select Save Userid and Password, you do not need to reenter these credentials each time you connect, and the dialog box does not appear. However, you must reenter this information when you change your password for the server. To do so, right-click the server name in the navigation tree and select Properties to reopen the Remote Server Configuration dialog box. 4. Click Connect. For data retrieval and processing to occur, you must perform this connection step each time you start the DataMigrator Server and the DMC. Procedure: How to Add a Node to Identify the Server to the Data Management Console You can set up the DMC to connect to any number of servers in your enterprise. When the DMC opens for Windows servers, the default LOOPBACK node is listed under Servers in the navigation pane. It does not appear if you open the DMC from a non-windows installation. Warning: Do not delete the LOOPBACK node, since it is required for internal processing. To add another server node in this location: 1. Right-click Servers and select Add Server Node. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-15

304 DataMigrator Setup The Server Node Configuration dialog box opens. Note: The DMC connects to server nodes using an HTTP listener port and the properties specified in the Basic tab. Applications that connect via the EDA API, like Resource Analyzer/Governor, use a TCP listener port and the properties specified in the Advanced tab. 2. In the Node Name field, enter a name for the Server node you wish to add. 3. In the Host field, enter the machine name or IP address where the DataMigrator Server is running. For a server running on the same PC as the client, you can enter localhost. 4. In the HTTP Listener Port field, enter the port number of the DataMigrator Server, which is 8117 if you used the installation defaults. This port listens to all incoming requests from the DMC. 5. Optionally, use a Secured Sockets Layer (SSL) by selecting that check box. 6. Optionally, enter a description of the node in the Node Description field iway Software

305 Setting Up DataMigrator 7. Security is set to Explicit by default. When this setting is in effect, the User ID and password you used to log on to Windows are not passed to the server. If security is required, you must enter it either at connection time or in the Security credentials fields to the right. Alternatively, for servers running on Windows, you can choose IWA, which passes the Windows User ID and password to the server when a connection is made. 8. Click OK. The node is added to the Server(s) tree, as shown in the next screen: You can test the connection between the DMC and the DataMigrator Server you have added. Procedure: How to Test the Server Before you proceed, it is recommended to test the connection between the DMC and the DataMigrator Server. To ensure that the server is running and that you are able to retrieve sample data: 1. In the DMC, right-click the server name and select Test Server. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-17

306 DataMigrator Setup If you can connect to the server, the Input Query dialog box opens. The default query is select car from car. You can change the test query, but the default, based on sample data delivered with your software, is sufficient to verify that you can retrieve data. 2. Click Test. The answer set appears in the right pane of the DMC, behind the Input Query dialog box. 3. Click Cancel to close the Input Query dialog box and examine the test output iway Software

307 Initiating Server Administration Tasks Setting Up DataMigrator Although all required server administration and monitoring tasks can be performed by a designated administrator directly from the DataMigrator Server Web Console, an authorized developer can conveniently initiate the more common administration tasks from the DMC using a server administration ID. To perform any of these tasks, your server must be running so that you can connect to it from the DMC. Procedure: How to Launch the Web Console You can access the Web Console directly from the DMC to perform additional server administration tasks. This procedure assumes that the server has already been started. 1. From the navigation pane, right-click a server name, and select Access Web Console. 2. From the secondary menu, select the option that is related to the task you wish to perform. The following Web Console pages are available from the DMC. Home (to see all available console options) Agents Page Scheduler Configuration Page Procedures Page Configure Data Adapters Page Manage Metadata Page Authorizing DataMigrator Server Usage and Administration DataMigrator Server administration functions require a connection with a server administration user ID, such as the user ID that was used to install and configure the server. This user can add additional server administration user IDs. Note: To use DataMigrator from the Data Management Console or Web Console, a user must be at least an Application Administrator. Procedure: How to Add Server Administration IDs 1. In the Web Console, from the menu bar, click Workspace, then click Access Control. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-19

308 Authorizing DataMigrator Server Usage and Administration The Security Mode page opens. 2. Click the Users folder and select New User iway Software

309 Setting Up DataMigrator The Access Control page opens. 3. Fill in the User Name, Domain, and fields. For the Server administration level, fill in the Password and Confirm Password fields. 4. Select an administration level: Server Administrator Permits all functions. Application Administrator Permits management of flows. This administration level displays flows in the Web Console. It is the minimum level required for DM developers who want to use the Web Console to view their flows and/or to use the DMC to create or edit flows. Server Operator Permits monitoring of server processes. Basic User Provides no administrative or monitoring capabilities. 5. Click Create. 6. Click Save and Restart to save your changes. Note: The Access Control page s appearance will vary depending on the Security Mode setting. If the Security Mode is set to OFF, no other options will be available. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-21

310 Managing Application Directories and Configuring the Application Path Managing Application Directories and Configuring the Application Path How to: Create an Application Directory in the Data Management Console Delete an Application Directory in the Data Management Console Add Application Directory Mappings in the Data Management Console Delete Application Directory Mappings in the Data Management Console Configure the Application Path in the Data Management Console Filter Application Directories in the Metadata Tree in the Data Management Console Filter Application Directories in the Procedures Tree in the Data Management Console Reference: Application Directories Options Procedures and the synonyms they use reside in application directories. The Application Path is a list of viewable application directories. It determines their order of appearance in the navigation pane. The Application Path is the default search criteria for the server. The server searches each of the directories listed in the Application Path sequentially to find the requested procedure/synonym. By default, the server profile (EDASPROF.PRF) is run for all users when they connect to the DataMigrator Server to provide access to all application directories in the server s search path. However, you can control a user s access to application directories by creating individual user profiles. Each user can then: Access only the application directories specified in the application path specified for that profile. Use synonyms and procedures in the specified application path iway Software

311 Setting Up DataMigrator Grouping procedures and synonyms into application directories provides better control. For your convenience, two directories are included in the server s search path during installation: baseapp is included in the search path for every user profile the DM administrator creates. This directory cannot be removed. ibisamp contains sample files you can use to create procedures, as well as sample procedures. You can, of course, set up additional application directories in the server s search path. The following operations are available from the Application Directories folder by right-clicking (DMC) or by clicking (Web Console): Adding or deleting application directories. Setting up application directory mappings for different user profiles. Configuring the application path by adding, removing, or reordering application directories. Filtering the procedures or synonyms that appear in the application directories You can also use the Configure Application Path window to set the viewable directories for DataMigrator, as well as add new directories and mappings. To use DM procedures that reside in a directory other than ibi\apps\baseapp, the directory must be added to the list of viewable directories. Note: You can also manage application directories and configure the Application Path from the Procedures page of the Web Console. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-23

312 Managing Application Directories and Configuring the Application Path Procedure: How to Create an Application Directory in the Data Management Console 1. Right-click Application Directories in the navigation pane and select Directories. The Manage Application Directories dialog box opens. 2. Click the New button iway Software

313 The Manage Application Directories - Create Directory dialog box opens. Setting Up DataMigrator 3. Enter the name of the new application directory, and click Create. Caution: The directory name may not contain spaces, special characters, or capital letters. Capital letters are converted to lower case. If the name contains spaces, each section is understood to be a separate directory. If an application directory is created outside of the DMC or Web Console, the same rules apply. The new directory will appear in the Manage Application Directories dialog box. Note: The directory must still be added to the Application Path. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-25

314 Managing Application Directories and Configuring the Application Path Procedure: How to Delete an Application Directory in the Data Management Console 1. Right-click Application Directories in the navigation pane and select Directories. The Manage Application Directories dialog box opens. 2. Select the check box for the directory you want to delete and click Delete Selected iway Software

315 Setting Up DataMigrator A confirmation dialog box opens. 3. Click OK. Procedure: How to Add Application Directory Mappings in the Data Management Console You can create a new mapping to a directory anywhere in the file system and include it in the server's path. Application directory mappings can be added and deleted on a per profile basis. 1. Right-click Application Directories in the navigation pane and select Mappings. The Manage Application Directory Mappings dialog box opens. 2. From the drop-down menu, select a user profile. This profile will have the directory mapping added to it. 3. Click the New button. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-27

316 Managing Application Directories and Configuring the Application Path The Manage Application Directory Mappings - Create Mapping dialog box opens. 4. In the Mapping name box, enter an application name of up to 64 characters. 5. In the Physical directory box, enter the full path of the physical directory to be mapped, in the format required by your platform. 6. Click the Create button. The new mapping appears in the Manage Application Directories Mappings dialog box. 7. Click Cancel. Note: The mapping must still be added to the Application Path iway Software

317 Setting Up DataMigrator Procedure: How to Delete Application Directory Mappings in the Data Management Console 1. Right-click Application Directories in the navigation pane and select Mappings. The Manage Application Directories Mappings dialog box opens. 2. Select the check box for the mapping you want to delete and click Remove Selected. A confirmation dialog box opens. 3. Click OK. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-29

318 Managing Application Directories and Configuring the Application Path Procedure: How to Configure the Application Path in the Data Management Console You must add an application directory or mapping to the Application Path for it to be accessible. 1. Right-click Application Directories in the navigation pane and select Configure Path iway Software

319 Setting Up DataMigrator The Configure Application Path dialog box opens. 2. Select the profile of the user whose Application Path you wish to set. 3. Select the In Path check box for the directory or mapping you want to add to the application path. 4. Optionally, deselect the In Path check box for any directory or mapping you want to remove from the application path. This allows you to remove the directory or mapping from the path without deleting it completely. 5. Set the directory search order by selecting a directory or mapping and using the up and down arrows. You may want to consider moving the ibisamp directory to the bottom of the list to avoid confusion. If you do not plan to use the sample data, you can remove ibisamp from your Application Path completely. 6. When you have added and arranged all necessary directories and mappings, click Apply. 7. Right-click Application Directories in the navigation pane and select Refresh to see the directory or mapping in the tree. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-31

320 Managing Application Directories and Configuring the Application Path Procedure: How to Filter Application Directories in the Metadata Tree in the Data Management Console You can limit the synonyms that appear in the Metadata Tab s application directory tree by applying a filter. 1. Right-click Application Directories in the Metadata Tab and select Filter. The Filter Metadata Tree dialog box opens. 2. Choose one of the following from the Filter by drop-down menu: Name to filter on a synonym name. Adapter to filter on the adapter (data source) type that follows the synonym name in the listing on the Metadata navigation pane. Remarks to filter on remarks in the synonym s Filename section. For example: FILE=, SUFFIX=,... REMARKS= Inventory,$ Note that these entries are case sensitive. 3. Enter the letter(s) which the synonym s Name, Adapter, or Remarks must contain to be displayed in the application directory tree. Note: The synonym will be displayed if the letter combination appears anywhere in the name, adapter, or remarks. 4. Click the Set Filter button iway Software

321 Setting Up DataMigrator The Filter Status dialog box confirms that the filter was set. A filter icon will appear on application directories that are open or have been opened. Note: The filter can be removed by clicking the Clear Filter button in the Filter Metadata Tree dialog box. Unless the filter is cleared, it remains in effect after the DMC in closed and reopened. The filter will also affect the display in the Web Console. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-33

322 Managing Application Directories and Configuring the Application Path Procedure: How to Filter Application Directories in the Procedures Tree in the Data Management Console You can limit the procedures that appear in the Procedures Tab s application directory tree by applying a filter. 1. Right-click Application Directories in the Procedures Tab and select Filter. The Filter Procedures Tree dialog box opens. 2. Choose one of the following from the Filter by drop-down menu: Name to filter on a procedure name. Description to filter on the flow s description, which can be set in the General page of the Flow Properties dialog box. This method filters flows only, not stored procedures. Note that these entries are case sensitive. 3. Enter the letter(s) which the procedure s Name or Description must contain to be displayed in the application directory tree. Note: The procedure will be displayed if the letter combination appears anywhere in the name or description iway Software

323 Setting Up DataMigrator 4. Optionally, choose one of the following from the File format drop-down menu: Procedure to filter procedures. HTML to filter html files. Both Procedure and HTML to filter both. Note: HTML files do not appear in application directories unless you set the File format drop-down menu to HTML or Both Procedure and HTML. 5. Click the Set Filter button. The Filter Status dialog box confirms that the filter was set. A filter icon will appear on application directories that are open or have been opened. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-35

324 Managing Application Directories and Configuring the Application Path Note: The filter can be removed by clicking the Clear Filter button in the Filter Metadata Tree dialog box. Unless the filter is cleared, it remains in effect after the DMC in closed and reopened. The filter will also affect the display in the Web Console. Reference: Application Directories Options If you right-click Application Directories in the DMC s navigation pane, the following options are available: Refresh Filter Refreshes the application directories tree. Allows you to filter the procedures or synonyms that appear in the application directories tree. Directories Allows you to create and delete application directories. Mappings Allows you to create and delete application directory mappings iway Software

325 Configure path Setting Up DataMigrator Allows you to add and delete application directories and mappings from the application path. Properties Allows you to view the application directories properties. Configuring Data Adapters How to: Add and Configure a Data Adapter Test a Data Adapter Reference: Navigation Pane: Adapters Tab Data adapters must be configured to allow the DataMigrator Server to access data on different types of databases. Once a data adapter is configured, you can create metadata for the tables or views in the form of synonyms. The synonyms are used to both access the data as sources, and to write the data to targets. To access data in the DM process, the data adapters you need must be defined to the server. You need to add and configure a data adapter for every database type you want to access. You can also configure and test data adapters from the Configuring Data Adapters page of the Web Console. For complete documentation on configuring data adapters and for a detailed explanation of the associated connection parameters, refer to the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-37

326 Configuring Data Adapters Procedure: How to Add and Configure a Data Adapter 1. Select the Adapters tab at the bottom of the navigation pane. The Adapters tab opens. Expand the Server node if it is not already expanded. 2. Right-click the Adapters folder and select Add. The Add adapter dialog box opens iway Software

327 Setting Up DataMigrator 3. Expand the adapter group and folder, select an adapter version, and click Configure. The Server Adapter Configuration window opens. 4. Configuring the adapter consists of specifying connection and authentication information for each of the connections you want to establish. Enter the appropriate information and click Configure. A confirmation message appears. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-39

328 Configuring Data Adapters 5. If you click the Continue button, the Manage and Configure Data Adapters dialog box opens, which allows you to create synonyms, test or delete the connection, and change or view connection properties, as well as add and configure other adapters. For complete documentation on configuring data adapters and for a detailed explanation of the associated connection parameters, refer to the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual. Procedure: How to Test a Data Adapter 1. Select the Adapters tab at the bottom of the navigation pane. The Adapters tab opens. Expand the Server node if it is not already expanded iway Software

329 Setting Up DataMigrator 2. Expand the folder for the data adapter. 3. Right-click the configured adapter connection and select Test. The Test Results window opens. Note: The output will vary depending on the adapter. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-41

330 Configuring Data Adapters Reference: Navigation Pane: Adapters Tab The Adapters tab allows you to add and configure adapters from the DMC. The Adapters tab has the following fields/options. Adapters folder Contains the adapters that have been configured for this server, as well as the Remote Servers folder. Remote Servers folder Contains the remote servers that have been configured iway Software

331 If you right-click an adapter folder, the following options are available: Setting Up DataMigrator Add connection Allows you to configure another connection for that adapter. Change settings Allows you to change optimization settings, controlling session parameters, and miscellaneous settings, depending on the adapter. Remove Removes the configured adapter from the server. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-43

332 Configuring Data Adapters If you right-click a connection, the following options are available: Create Synonym Allows you to create a synonym for that adapter. Test Allows you to test the connection. Delete Allows you to delete the connection. Properties Allows you to view and change the connection s properties iway Software

333 Setting Up DataMigrator Creating Metadata How to: Create Synonyms Create a Synonym for a Relational Stored Procedure Test Synonyms Create Sample Procedures and Data Synonyms constitute the metadata that DataMigrator requires to define unique names (or aliases) for each table or view that is accessible from the server. A synonym must be created for every table that DataMigrator accesses. Once you have created the metadata (synonym), it is a good idea to test it to make sure that the data is available for DM processing. You can also create and test metadata from the Managing Metadata page of the Web Console. Procedure: How to Create Synonyms 1. In the Data Management Console, right-click an application directory and select New, and then Synonym. The Create Synonym dialog box opens showing the adapters that you have configured. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-45

334 Creating Metadata 2. Expand a configured adapter folder, select a connection, and click OK. Note: You can also create a synonym by double-clicking an adapter connection from the Adapters tab. The Server Metadata Creation dialog box opens. Note: The contents of this dialog box will depend on the adapter selected. 3. Select the Use current database check box or, alternately, select a different database from the drop-down menu. This option is only available for Informix, Microsoft SQL Server, and Sybase ASE adapters. 4. Optionally, restrict candidates based on object type by selecting/deselecting the corresponding check boxes. The object types will vary depending on the adapter. 5. Optionally, filter the possible candidates by name and owner. Selecting this option adds Owner and Table Name parameters to the dialog box. For the Owner parameter, type a string for filtering the owner IDs, inserting the wildcard character (%) as needed at the beginning and/or end of the string. For example, enter ABC% to select tables or views whose owner IDs begin with the letters ABC; %ABC to select tables or views whose owner IDs end with the letters ABC; %ABC% to select tables or views whose owner IDs contain the letters ABC at the beginning, middle, or end iway Software

335 6. Click Next. Setting Up DataMigrator For the Table Name parameter, type a string for filtering the table or view names, inserting the wildcard character (%) as needed at the beginning and/or end of the string. For example, enter ABC% to select all tables or views whose names begin with the letters ABC; %ABC to select tables or views whose names end with the letters ABC; %ABC% to select tables or views whose names contain the letters ABC at the beginning, middle, or end. The Metadata Creation dialog box opens showing all objects that meet the specified criteria. 7. From the Select Application drop-down list, select a directory. baseapp is the default value. In this example, we've selected the salesdemo application directory. 8. If you have tables with identical table names, assign a prefix or a suffix to distinguish them. For example, if you have identically named human resources and payroll tables (most likely with different owners), assign the prefix HR to distinguish the synonyms for the human resources tables. Note that the resulting synonym name cannot exceed 64 characters. If all tables and views have unique names, leave prefix and suffix fields blank. 9. To specify that this synonym should overwrite any earlier synonym with the same fully qualified name, select the Overwrite existing synonyms check box. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-47

336 Creating Metadata 10. To reflect the current cardinality (number of rows or tuples) in the table during metadata creation, select the Cardinality check box. The use of cardinality is for equi-joins. The order of retrieval is based on the size (cardinality) of the table. Smaller tables are read first. Note: If the cardinality of the tables to be used in the application are dynamic, it may not be beneficial to choose this setting. 11. If you are creating a synonym for a table that has a foreign key to another table, select the With foreign keys check box to provide access to both tables in the synonym and Access File. 12. To specify that the Master File created for the synonym should not contain column information, select the Dynamic columns check box. If this option is selected, column data is retrieved dynamically from the data source at the time of the request. 13. Select the Customize data type mappings check box to access additional settings. 14. From the Longchar as drop-down menu, you can select: TEXT, ALPHA, or BLOB. TEXT is the default value. Use ALPHA for DataMigrator. You can also change the scale and precision settings. 15. Complete your table or view selection: To select all tables or views in the list, select the check box to the left of the Default Synonym Name column heading. To select specific tables or views, select the corresponding check boxes. 16. The Default Synonym Name column displays the name that will be assigned to the synonym. To assign a different name, replace the displayed value. 17. Click Create Synonym. Synonyms are created and added under the specified application directory iway Software

337 Setting Up DataMigrator The status field of the Metadata Creation window shows that the synonyms were created successfully. Procedure: How to Create a Synonym for a Relational Stored Procedure If you create a synonym for a relational stored procedure, you can use that stored procedure as a data source in a flow. When you create the synonym, you ll be prompted for values for the procedure s parameters.we are using Oracle as an example for this procedure. 1. In the navigation pane s Adapters tab, right click a relational Oracle connection and select Create Synonym. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-49

338 Creating Metadata The Select Synonym Candidates (Step 1) dialog box opens. 2. Select the Stored Procedure and Filter by name and owner check boxes. Enter an Owner or Object name or both and click Next. The Select Synonym Candidates (Step 2) dialog box opens iway Software

339 Setting Up DataMigrator 3. Click the radio button for a stored procedure and click Next. The Select Synonym Candidates (Step 3) dialog box opens. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-51

340 Creating Metadata 4. Select check boxes for the parameters and supply their values. Click Create Synonym. Note: Values entered are used only when creating the synonym and are not saved. A confirmation message appears. 5. Click Close iway Software

341 Setting Up DataMigrator The synonym now appears on the Metadata tab. Procedure: How to Test Synonyms 1. In the Data Management Console, right-click a server name and select Connect. 2. Click the Metadata tab to switch to the metadata view. 3. Expand the Application Directories folder, and expand the application directory where you created your synonyms. 4. Right-click the synonym you wish to test and select Sample Data. Sample data appears in the workspace, looking similar to the following: Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-53

342 Creating Metadata Procedure: How to Create Sample Procedures and Data 1. From the DMC s Procedures tab, open the DataMigrator Utilities folder. 2. Double-click Create Sample Procedures and Data, or right-click it and select Open. The Create Sample Procedures and Data dialog box opens iway Software

343 Setting Up DataMigrator 3. From the Sample procedures and data for drop-down menu, choose DataMigrator, File Listener, or All. 4. From the Select DBMS drop-down menu, choose a DBMS type and click Create. FOCUS/FDS will be the only choice if you don t have other adapters configured. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-55

344 Creating Metadata When the creation process is complete, a confirmation message displays. The message will depend on the type of samples you create, i.e. Data Migrator, File Listener, or All. The message also displays in the Message window. The procedures and synonyms appear in the ibisamp application directory, which is created and added to the server s search path during installation. For FOCUS, the sample data is also stored in ibisamp; for other adapters it is stored in the configured adapter s database. The source data for the file listener flow is stored in ibisamp/dmordfl.dat. 5. Ensure that the ibisamp application directory is in the server s path. It will be in the path unless you delete it. In the DMC, examine the navigation tree in the server you are using. On the Managing Metadata page of the Web Console, click the Application Directories link in the navigation pane to see the Configure Application Path page iway Software

345 Setting Up DataMigrator Testing Sample Data and Process Flows Example: Testing the Sample Data Flow DMVPX Testing the Sample Data Flow DMVPY Testing the Sample Process Flow DMVPZ Once you have verified that all required DM setup tasks have been successfully completed, you can perform three simple tests to ensure that your flows will run properly. We created some sample data and process flow procedures for you to use in testing your setup. We recommend that you run these tests before you create and attempt to run your own flows. Example: Testing the Sample Data Flow DMVPX 1. Expand the ibisamp directory in the navigation pane. 2. Double-click the dmvpx data flow. The data flow opens in the workspace at the right. This data flow extracts the department Production data from the data source named employe2 and creates a new data target, also named dmvpx. 3. Click the Run icon on the toolbar and select Run from the drop-down menu. 4. When the data flow run has been completed, the following message appears in the Server Message window: (ICM18763) Request ibisamp/dmvpx complete 5. Right-click dmvpx in the Servers - Procedures tree and select View Last Log. The log, which is displayed in the workspace, indicates that the new table named dmvpx has been created and loaded with six rows. 6. Select Close All from the Window menu to close the log and the data flow window. Example: Testing the Sample Data Flow DMVPY This example assumes that you have already completed Testing the Sample Data Flow DMVPX, since it uses a table that you create there. 1. Expand the ibisamp directory in the navigation pane. 2. Double-click on the dmvpy data flow. The data flow opens in the workspace at the right. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-57

346 Testing Sample Data and Process Flows This data flow extracts the records for the department MIS from the data source named employe2 and adds them to the existing table dmvpx. 3. Click the Run icon on the toolbar and select Run from the drop-down menu. 4. When the data flow run is complete, the following message appears in the Server Message window: (ICM18763) Request ibisamp/dmvpy complete 5. Right-click dmvpy in the Server - Procedures tree and select View Last Log. The log in the workspace shows that the target table exists and that six records for the MIS department were added to the target. Example: Testing the Sample Process Flow DMVPZ The data flows that ran separately in Testing the Sample Data Flow DMVPX and Testing the Sample Data Flow DMVPY now run as a combined process flow. 1. Expand the ibisamp directory in the navigation pane. 2. Double-click on the dmvpz process flow. The process flow opens in the workspace at the right. This process flow sets up the flow of dmvpx followed by dmvpy. 3. Click the Run icon on the toolbar and select Run from the menu. When the process flow runs, the first data flow creates the new table and the second data flow loads it with additional records. 4. When the process flow run is complete, the following message appears in the Server Message window: (ICM18763) Request ibisamp/dmvpz complete 5. Right-click dmvpz in the Servers- Procedures tree and select View Last Log. The log in the workspace shows that the two data flows ran successfully. Next Steps: If you have received these results, you can feel confident that your client/server setup is running correctly and you can proceed to the design phase iway Software

347 Setting Up DataMigrator Performing Server Administration Tasks From the Web Console You can control many key aspects of DataMigrator Server operations from the Web Console, which is directly accessible from the DMC. The Procedures page allows you to: Configure the application path. View and run flows by expanding the approot folder and its application directories. Create sample procedures and data. Migrate procedures created in an earlier release. Set up log and statistics options. Run reports. View run-time information. The Scheduler Configuration page allows you to: In this section: Configuring DataMigrator Server Operations How to: Edit the Scheduler Configuration Set/Update Preferences Configure the Server for Notification Configure a File Listener From the Web Console Edit the Server Configuration Reference: Scheduler Configuration Page Listener Configuration Page Set Scheduler settings. Set notification. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-59

348 Performing Server Administration Tasks From the Web Console Configuring DataMigrator Server Operations How to: Edit the Scheduler Configuration Set/Update Preferences Update Passwords Configure the Server for Notification Configure a File Listener From the Web Console Edit the Server Configuration Reference: Scheduler Configuration Page Listener Configuration Page From the Web Console, you can set up your DataMigrator Server to send an message that notifies recipients of the successful completion or failure of every flow s execution. In addition, from the DMC, you can enable the distribution of messages at any point in a process flow. However, to enable either variation on the notifications process, you must first configure an SMTP service. (You need to set up your server for before it will work anywhere in the flow.) You can also configure a file listener on the server from the Web Console. If you have a file listener configured on the server, you can add a listener object to a process flow in the DMC. The listener object is used to launch a direct load data flow when a particular file type appears in a specific directory. Procedure: How to Edit the Scheduler Configuration 1. From the Web Console menu bar, select Workspace, then Configuration. 2. Expand the Special Services folder, click SCHEDULER, and select Properties from the pop-up menu. The Scheduler Configuration page opens. 3. Make your changes, and click Save and Restart iway Software

349 Setting Up DataMigrator You can also access the Scheduler Configuration page from the Web Console menu bar by selecting Workspace, then Configuration. Expand the Special Services folder, click SCHEDULER, and select Properties from the pop-up menu. Reference: Scheduler Configuration Page The DataMigrator Scheduler runs as a task under the iway DataMigrator Server. The Scheduler must be running to execute not only scheduled data flows, but also deferred data flows, and flows run in parallel groups in a process flow. The Scheduler Configuration pane contains the following fields/options: sched_interval Is how often, in seconds, you want the Scheduler to check for execution of flows. The default value is 60 seconds. sched_ Indicates when to send for all flows that run. The options are: off does not send for every flow, however, you can send per flow from the DMC. This value is the default. Tip: If you wish to send notification on a per-flow basis, select the Notify check box in the Properties panel of your DMC. completion sends when every flow has been completed. failure sends when every flow fails. Note: Before you can use notification, you must configure server support. sched_run_id Determines the user ID that is associated with a scheduled flow when it is run. sched_run_id affects the application directories available to the flow, as well as access to relational data sources and source servers in the profile used by the administrator. Note: Flows submitted from the DMC, the Web Console, or CMRUN are run under the userid that submitted the flow. Valid values are: server_admin_id Runs flows under the first ID that appears in the list of server administrators displayed on the Access Control page. If the ID does not have a password specified, a profile for that user ID must be created. server_admin_id is the default. This setting enables access to all data sources and source servers in the path specified by that server administrator s profile. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-61

350 Performing Server Administration Tasks From the Web Console user Runs flows under the user ID that was used to save the flow. The Application Path specified in the user's profile is utilized. If security is ON and you set sched_run_id to User, to run a scheduled flow for a certain user id: 1. The user id must be a valid user on the system. 2. The user id must be set to an access level of either SERVER or APPLICATION from the Access Control page. 3. The password for the user must be set. A SERVER-level administrator can set the password for SERVER-level ids from the Access Control page when adding a user. If a DataMigrator user with an APPLICATION-level ids wants to run scheduler requests: sched_autostart 1. A SERVER administrator must make them an APP administrator from the Access Control page. 2. The user must set their password on the User Information page. 3. The scheduler must be restarted. (Restarting the server will also restart the scheduler.) Specifies whether the Scheduler should check for flows automatically. The options are: yes automatically starts the Scheduler when the server starts. This is the default value. no does not start the Scheduler when the server starts. Note: The Scheduler must be running to execute not only scheduled data flows, but also deferred data flows, restarted flows, and flows run in parallel groups in a process flow. Save and Restart Saves your changes and restarts the DataMigrator Server iway Software

351 Setting Up DataMigrator Procedure: How to Set/Update Preferences APPLICATION-level administrators can set or change their preferences from the Web Console. 1. From the Web Console menu bar, select My Console, then Preferences. The Preferences page opens. 2. Change your session preferences by selecting the appropriate check boxes. 3. Click Update. Note: Changes to the session preferences will take effect the next time the server or scheduler is restarted. Procedure: How to Update Passwords APPLICATION-level administrators can change their configured passwords from the Web Console. 1. From the Web Console menu bar, select My Console, then Change Password. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-63

352 Performing Server Administration Tasks From the Web Console The User Information page opens. 2. Enter your current operating system password in the Current Password field. 3. Enter the password in the New Password and Confirm Password fields. 4. Select the Update operating system or Update password in admin.cfg check box. 5. Click Update. Note: Changes to the password will take effect the next time the server or scheduler is restarted. Procedure: How to Configure the Server for Notification To enable notifications, you must first configure an SMTP service. (You need to set up your server for before it will work anywhere in the flow.) 1. From the Web Console menu bar, click Workspace, then Configuration. The Configuration page opens iway Software

353 Setting Up DataMigrator 2. Expand the General folder in the navigation pane and click . The page opens. 3. Enter the following information: SMTP_HOST defines the IPv4 address of the SMTP server. The address can be in standard dot notation (for example, smtpmail.yourcompany.com). SENDER_ defines the sender s address, which appears in the 'From' field in s (for example, yourname@yourcompany.com). 4. Click Save. 5. In the General folder in the navigation pane, click Notification. The Notification page opens. 6. Enter the following information: SERVER_ADMIN_ specifies recipients addresses ( address1; address 2;...). WSM_ controls distribution of by Workspace Manager to addresses defined in SERVER_ADMIN_ when specified events occur (event1, event2,...). For example, you might define stopping and starting the server as events that trigger distribution. The following predefined events indicate abnormal states resulting from a fatal software error in which the agent process is no longer running. They are provided for diagnostic purposes: Crashed indicates an error detected by the operating system. Aborted indicates an error detected by the program. NORESOURCE indicates there are no more available agents, the maximum number has been reached. NODISKSPACE indicates there is not enough disk space to process deferred requests. Once the problem has been investigated, the server administrator can clear such such agents using the kill option. 7. Click Save and Restart. 8. After configuring SMTP services, go to the Web Console Scheduler Configuration page and select a sched_ option: off Never send . Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-65

354 Performing Server Administration Tasks From the Web Console completion Send when a flow finishes. failure Send when a flow fails. Note: This setting applies to every flow. Procedure: How to Configure a File Listener From the Web Console If a file listener is configured on the server, you can add a listener object to a Direct Load flow to create a Real Time flow. A Real Time flow is launched when a particular file appears in a specific directory. You can also monitor the listener to manage the agents used for a particular flow. 1. In the DMC, right-click the server name and select Access Web Console, then Scheduler Configuration. The Scheduler Configuration page opens. 2. Click the Listeners folder in the navigation pane and select New, then FILE iway Software

355 Setting Up DataMigrator The Listener Configuration page opens. 3. Change any of the settings as needed and click Save and Restart. The File listener is added to the Listeners page. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-67

356 Performing Server Administration Tasks From the Web Console Reference: Listener Configuration Page The Listener Configuration page has the following fields/options. SchedInterval Indicates how often the listener will scan the application path for new data flows. The default is 60 seconds. ServerAdminId These credentials are used to authenticate the file listener, so the agent can determine whether the listener has been authorized to perform the requested operation. The options are: server admin. The listener always connects to the agent using the server administrator id. user. The listener will connect to the agent using the userid and password that saved the flow. That userid/password must have an access control setting of server administrator or application administrator. DirPoll Indicates how often the listener will check for the presence of a file. The default is 10 seconds. Extension Indicates the type of file that the listener will check for. The default if.ftm iway Software

357 DiscardStrategy Setting Up DataMigrator Indicates what to do with the file after it has been processed by a file agent. The options are: DELETE deletes the file. ARCHIVE copies the file with a timestamp to a directory specified in the data flow. This is the default. PickupStrategy Indicated the mechanism used by file agents to pick up files from their directories. The options are: IMMEDIATE processes the file as soon as it is detected. TRIGGER processes the file when a trigger file is detected. This setting requires an additional setting for the trigger file extension. The trigger file extension is added to the full name of file being listened for. For example, if the trigger file extension is.trg, the trigger file for a data file named input.dat would be input.dat.trg. Note: A trigger is typically used when processing needs to be delayed. By waiting until this secondary file appears, for example while a large file is being FTPed or copied into a directory, the trigger file indicates when processing can begin. Procedure: How to Edit the Server Configuration 1. From the Web Console menu bar, select Workspace, then Configuration. The General Server Configuration page opens. 2. Make your changes, and click Save. Upgrading DataMigrator From Version 4.3 or 5.1 How to: Migrate Requests on UNIX and Windows Migrate Requests on z/os Migrate Requests on i5/os When you upgrade DataMigrator from a previous release of ETL Manager, you must migrate the Synonyms, Access Files, and flows you want to keep. The migration process for release 5.1x or below includes the following tasks: 1. Migrate Synonyms and Access Files. 2. Migrate stored procedures referenced in the procedures panel of any requests. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-69

358 Upgrading DataMigrator From Version 4.3 or Prepare the ETL internal database for migration. 4. Migrate the Requests (which will become flows in Version 7.1). 5. Test the migrated flows. Although procedures vary slightly by operating system, each variation includes these tasks. For details, see the procedure for your operating system. Before you start the migration, review category names for the following special characters: /\:*?"<> Categories names containing these special characters must be renamed before migration. In the migration, spaces in category names are changed to underscores ( _ ). Application names are limited to 18 characters. Notes: There is no need to migrate requests that you created in a 5.2.x release of ETL Manager. They can be run without any changes. When you open and re-save them in the DMC interface they will automatically be restructured based on the new data flow/process flow paradigm. Stored procedures cannot have the same name as requests. Procedure: How to Migrate Requests on UNIX and Windows 1. Locate the Synonyms and Access Files used by your requests. The default locations are: Operating System and ETL Release UNIX, Release 4.3 UNIX, Release 5.1 Windows, Release 4.3 Windows, Release 5.1 Default Location home/ibi/srv43/cpm/catalog home/ibi/srv51/etl/catalog c:\ibi\srv43\cpm\catalog c:\ibi\srv51\etl\catalog 2. Copy the Synonyms and Access Files to the baseapp directory of APPROOT. This is the default directory for Release 5.3 flows. or Copy the Synonyms and Access Files to any directory under APPROOT, then add that directory to the Application Path iway Software

359 Setting Up DataMigrator 3. Prepare the CM/ETL internal database for migration. If your CM/ETL internal tables are stored in: A relational database (such as ORACLE, Microsoft SQL Server, or DB2). Configure an adapter for the data source. For more information, see the Adapter Administration for UNIX, Windows, OpenVMS, i5/os, and z/os manual. FOCUS. No preparation is required if the internal database file (CMSCHED.FOC) and master file (CMSCHED.MAS) are in their original locations. Note that if you are migrating from a disconnected computer and have to copy these files, they should be copied to the same directory. 4. From the DMC, right click the server, and select Access Web Console, Procedures. The Procedures page opens. 5. Open the DataMigrator Utilities folder, and click Migrate 4.x or 5.1 Procedures. The Migrate pane opens. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-71

360 Upgrading DataMigrator From Version 4.3 or By default, all requests will be migrated. To migrate all requests, in the top box of the Migrate pane enter the path to the directory where CMSCHED.MAS and either CMSCHED.ACX or CMSCHED.FOC files reside on the 4.x or 5.1.x Server. The default locations for each platform are as follows: Operating System and ETL Release UNIX, Release 4.3 UNIX, Release 5.1 Windows, Release 4.3 Windows, Release 5.1 Default Location home/ibi/srv43/cpm/copymgr home/ibi/srv51/etl/etlmgr c:\ibi\srv43\cpm\copymgr c:\ibi\srv51\etl\etlmgr To migrate a single request, enter the path in the top box of the Migrate pane, then enter the request name in the bottom box. 7. Click Submit. The message "Migrate procedure submitted" appears. 8. When the migration procedure finishes, review the log created to ensure that all requests migrated successfully. The following message appears for each flow: (ICM18164) Request NAME was created/updated successfully for user: USER. The following message should also appear: (ICM18354) Migration procedure completed successfully. If any requests have not migrated successfully, an error message is displayed. For example, if the synonym for a target table in a request cannot be found for a file named target01, the message will read: (FOC205) THE DESCRIPTION CANNOT BE FOUND Target synonym target01 is not found You must correct the error and rerun the migration procedure without errors before you can open the flow in DataMigrator iway Software

361 Setting Up DataMigrator 9. Review the list of new application directories. By default, flows are located in the APPROOT\baseapp directory. If a category name was previously assigned in the Properties window, a directory with that category's name is created under APPROOT and the following message appears: * New Created APP directories */ newapp * */ Note: You must add any new application directories to the Application Path of each user who needs to access it. 10. In the Procedures page's navigation pane, click Refresh Page, then verify that the application directories and requests are listed. Procedure: How to Migrate Requests on z/os 1. Locate the Synonyms and Access Files used by your requests. These comprise all the data sets concatenated under the ddnames MASTER and ACCESS. 2. Allocate Master and Access PDSes using startup JCL at qualif.etl.data(istart). For example: //MASTER DD DISP=SHR, DSN=qualif.MASTER.DATA //ACCESS DD DISP=SHR, DSN=qualif.ACCESS.DATA All the files from the concatenated datasets under ddnames MASTER and ACCESS appear in the mapped application directory MVSAPP. 3. If the Synonym and Access Files for the CMSCHED tables are in a PDS allocated in step 2, you can skip this step. Optionally, copy the Synonym and Access Files for the CMSCHED tables from the PDS (for example, qualif.copymgr.master.data) to an HFS directory (for example, home /ibi/apps/baseapp/). In an OS/390 ISPF Command Shell session (option 6 from ISPF menu), enter the following command to copy the CMSCHED Synonyms and Access Files: To copy the Synonyms: oput 'qualif.copymgr.master.data(cmsched)' 'home/ibi/apps/baseapp/cmsched.mas' To copy the Access File: oput 'qualif.copymgr.access.data(cmsched)' 'home/ibi/apps/baseapp/cmsched.acx' 4. Prepare the ETL internal database for migration. To do this, configure the Adapter for DB2 where the internal tables are stored. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-73

362 Upgrading DataMigrator From Version 4.3 or From the DMC, right click the server, and select Access Web Console, Procedures. The Procedures page opens. 6. Open the DataMigrator Utilities folder, and click Migrate 4.x or 5.1 Procedures. The Migrate pane opens. 7. By default, all requests will be migrated. To migrate all requests, in the top box of the Migrate pane enter the path to the directory where CMSCHED.MAS and either CMSCHED.ACX or CMSCHED.FOC files reside on the 4.x or 5.1.x Server. The default locations for this platform are as follows: Operating System and ETL Release OS/390, Release 4.3 OS/390, Release 5.1 Default Location home/ibi/apps/baseapp home/ibi/apps/baseapp To migrate a single request, enter the path in the top box, then enter the request name in the bottom box. Note: If you did not copy the files in Step 3, and if the PDS was allocated in the start up JCL under MASTER and ACCESS ddnames, the default location is: 'mas=//dd:master;acx=//dd:access' iway Software

363 Setting Up DataMigrator 8. Click Submit. The message "Migrate procedure submitted" appears. 9. When the migration procedure finishes, review the log created to ensure that all requests migrated successfully. The following message should appear for each flow: (ICM18164) Request NAME was created/updated successfully for user: USER. The following message should also appear: (ICM18354) Migration procedure completed successfully. If any requests have not migrated successfully, an error message is displayed. For example, if the synonym for a target table in a request cannot be found for a file named target01, the message will read: (FOC205) THE DESCRIPTION CANNOT BE FOUND Target synonym target01 is not found You must correct the error and rerun the migration procedure without errors before you can open the flow in DataMigrator. 10. Review the list of new application directories. By default, requests are located in the APPROOT\baseapp directory. If a category name was previously assigned in the Properties window, a directory with that category's name is created under APPROOT and the following message appears: * New Created APP directories */ newapp * */ Note: You must add any new application directories to the Application Path of each user who needs to access it. 11. In the Procedures page's navigation pane, click Refresh Page, then verify that the application directories and requests are listed. Procedure: How to Migrate Requests on i5/os 1. Locate the Synonyms and Access Files used by your requests. The default location is /QSYS.LIB/EDAMAIN.LIB. 2. For each QSYS library, map the directory the new application will be located in into APPROOT using the Configure Application Path window, and then add the new directory to the Application Path. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-75

364 Upgrading DataMigrator From Version 4.3 or Copy the Synonyms and Access Files for the CMSCHED tables from the QSYS library (the default location for this library is /QSYS.LIB/EDAMAIN.LIB/MASTER.FILE) to the IFS directory. To do this, in an i5/os session, enter the following command: To copy the Synonyms: CPYTOSTMF FROMMBR('/QSYS.LIB/EDAMAIN.LIB/MASTER.FILE/CMSCHED.MBR') TOSTMF('home/ibi/apps/baseapp/cmsched.mas') To copy the Access Files: CPYTOSTMF FROMMBR('/QSYS.LIB/EDAMAIN.LIB/ACCESS.FILE/CMSCHED.MBR') TOSTMF('home/ibi/apps/baseapp/cmsched.acx') With the "replace" option: CPYTOSTMF FROMMBR('/QSYS.LIB/EDAMAIN.LIB/ACCESS.FILE/CMSCHED.MBR') TOSTMF('home/ibi/apps/baseapp/cmsched.acx') STFMOPT(*REPLACE) 4. After the Synonyms and Access Files are copied, edit CMCSHED.ACX and change the file name so that it points to the physical location of the table. from TABLENAME=CMCONFIG to TABLENAME=EDAMAIN/CMCONFIG where: EDAMAIN Is the name of the library where the DB2 CMSCHED tables reside. 5. Prepare the ETL internal database for migration. To do this, configure the Adapter for DB2 for the internal tables. 6. From the DMC, right click the server, and select Access Web Console, Procedures. The Procedures page opens iway Software

365 Setting Up DataMigrator 7. Open the DataMigrator Utilities folder, and click Migrate 4.x or 5.1 Procedures. The Migrate pane opens. 8. By default, all requests will be migrated. To migrate all requests, in the top box of the Migrate pane enter the path to the directory where CMSCHED.MAS and either CMSCHED.ACX or CMSCHED.FOC files reside on the 4.x or 5.1.x Server. The default location for this platform is: home/ibi/apps/baseapp To migrate a single request, enter the path in the top box, then enter the request name in the bottom box. 9. Click Submit. The message "Migrate procedure submitted" appears. 10. When the migration procedure finishes, review the log created to ensure that all requests migrated successfully. The following message should appear for each flow: (ICM18164) Request NAME was created/updated successfully for user: USER. The following message should also appear: (ICM18354) Migration procedure completed successfully. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 12-77

366 Upgrading DataMigrator From Version 4.3 or 5.1 If any requests have not migrated successfully, an error message is displayed. For example, if the synonym for a target table in a request cannot be found for a file named target01, the message will read: (FOC205) THE DESCRIPTION CANNOT BE FOUND Target synonym target01 is not found You must correct the error and rerun the migration procedure without errors before you can open the flow in DataMigrator. 11. Review the list of new application directories. By default, requests are located in the APPROOT\baseapp directory. If a category name was previously assigned in the Properties window, a directory with that category's name is created under APPROOT and the following message appears: * New Created APP directories */ newapp * */ Note: You must add any new application directories to the Application Path of each user who needs to access it. 12. In the Procedures page's navigation pane, click Refresh Page, then verify that the application directories and requests are listed iway Software

367 13 Running and Monitoring Your Server The iway Server and its Web Console provide a variety of tools and techniques that you can use to run and monitor your server. Topics: Configuring Workspace Manager Editing Configuration Files Viewing and Editing Your License Number Fine-Tuning the Server Monitoring Server Activity Migrating Your Server

368 Configuring Workspace Manager Configuring Workspace Manager In this section: Workspace Manager Configuration Privileges Configuring an Agent Service Configuring Deployment Modes Configuring for Deferred Management Using JVM Tuning Options to Improve Memory Usage General Workspace Configuration Settings How to: Set the Server Deployment Parameter in a Server Profile Set Deferred Management Properties The Workspace Manager is the component of the iway Server that is responsible for managing all server administrative tasks. These tasks, generally performed by Server Administrators, include monitoring server activity, configuring and adjusting the server s configuration profile, adding users, enabling and creating services, defining deferred execution characteristics, and enabling and disabling alerts. The Server Administrator responsible for the installation, configuration, security, and maintenance of the server uses the Workspace Manager to keep the server available to clients and running at peak efficiency. To use the Workspace Manager, open Internet Explorer and navigate to the HTTP port on the host machine where the iway Server is running. Your Server must be running in order for you to use the Workspace Manager. Tip: This chapter references a number of Workspace related keywords. Within the help system, you can access detailed information about these keywords by clicking the keyword links in this document. You can also click the? icon next to parameters on the Workspace configuration panes iway Software

369 Workspace Manager Configuration Privileges Running and Monitoring Your Server Access to the administrative features of the Web Console can be restricted by defining a list of users in the admin id and storing the list in a release independent file called admin.cfg. This file is located, by default, in /ibi/profiles. The list of users and user roles defined in admin.cfg defines a list of administrators that can be used for authorization and/or authentication according to established security. Administrators are responsible for installing, configuring, and maintaining the Server with varying degrees of responsibility, depending on their administration levels (SRV, APP, OPR). At least one administrator must be defined in the list, although most sites identify other persons to act as backups. For example, a Server Administrator (SRV) can perform all the administrative tasks available through Web Console operations. If more than one Server Administrator is defined, the first valid member on the list is used to impersonate FOCUS Database Server (FDS) and other special services. An Application Administrator (APP) is limited to the administrative tasks that do not require changing configuration or restarting the server. Both Server Administrators and Application Administrators can edit user profiles in the user.prf file. However, Server Administrators can edit all user.prf files, while Application Administrators can only edit their own profiles. Any IDs (beyond the original ID used to configure the server) that are used for server or application administration require read/write privileges to the respective locations that the IDs are expected to manage. To assign these privileges, you must establish group rights for the locations at the operating system level. To view and run Resource Governor procedures, for example, IDs must be at least at the Application Administrator level. For details about Web Console privileges for each administrative level, as well as for non-administrative (basic) users, see Administration Levels and Web Console Privileges in Chapter 2, Server Security. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-3

370 Configuring Workspace Manager Configuring an Agent Service A server configuration requires at least one agent service with the name DEFAULT, defined by a SERVICE block. An agent service is an entity used to define the parameters for a group of data access agents, so that a configuration can manage different groups of data access agents for different purposes. Each data access agent runs for a specific Data Service, and each service may have different values for the settings defined on the services configuration panes. These settings include: The maximum number of data access agents and the number of agents prestarted at server startup for a service, as defined by maximum and number ready. The lifetime of a service's agents, which can be limited through idle agent limit, CPU time limit, and/or memory limit. Incoming connections for which there is no available data access agent. These can be put in a queue for the service (configured using maximum_q and queue limit), and after they are connected, their idle time can be limited using idle session limit. The deployment mode of a service, which defines how data access agents are assigned to connections. For details, see Configuring Deployment Modes on page Configuring Deployment Modes How to: Set the Server Deployment Parameter in a Server Profile The deployment mode of a service defines how data access agents are assigned to connections: In private deployment, a dedicated application agent is assigned for each connection request. Private deployment retains the behavior of all prior server releases. At connect time, global, as well as user and service level profiles, are executed. At disconnect time, all temporary files are removed and database connections are closed. The privileges of each application agent depend on the security mode of the server. With security set to a value other than OFF, authentication is processed for every client logging on to the server. With security OFF, user identification and authentication are not required. The effective user ID becomes the connecting user for the duration of the session iway Software

371 Running and Monitoring Your Server In connection_pooled deployment, the global profile and service profiles are executed when an agent is started, and pooled user profiles are executed on each connection. The WebFOCUS context is cleared once the session is established for a new connection, and then the pooled user profile is executed. With security set to a value other than OFF, all users have the same rights because the effective pooled user is unique, regardless of the connecting user. Connection pooled deployment provides significant performance advantages and is recommended when a large number of users share the same operating system and DBMS credentials. It cannot be used when each connecting user has specific operating system and DBMS rights, nor can it be used for the service DEFAULT with the server s security mode set to DBMS because, in this situation, the profile is disabled for connection authentication. Procedure: How to Set the Server Deployment Parameter in a Server Profile To set the server configuration parameter deployment: 1. From the Web Console menu bar, select Workspace, then Configuration. 2. In the navigation pane, expand the Data Services folder, then click New on the expanded menu bar, followed by Data Service. The New Service pane opens. Tip: For an existing service (for example, DEFAULT, WC_DEFAULT, DMC_DEFAULT, DEFAULT_CPOOL), click the service and choose Properties from the menu to open the Services pane. 3. In the deployment field, choose: private or connection pooling. With private deployment, all profiles are executed on connection. On disconnect, all DBMS connections are dropped. This is the default value. With security set to a value other than OFF, the effective user ID is switched to the connecting user for the duration of the connection. Skip to step 6. With connection-pooled deployment, the global profile and service profiles are executed when an agent is started, and pooled user profiles are executed on each connection. The WebFOCUS context is cleared once the session is established for a new connection, and then the pooled user profile is executed. When you select this option, pooled_user and pooled_password are displayed. With security set to a value other than OFF, all users have the same rights because the effective user is unique (configured using pooled_user and pooled_password) regardless of the connecting user. Continue with steps 4 and 5. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-5

372 Configuring Workspace Manager 4. Select the pooled user from the drop-down list. (This list is populated from the admin.cfg file described in Workspace Manager Configuration Privileges on page 13-3.) This service level keyword is required for connection_pooling deployment with security mode OPSYS. It defines the user ID under which all agents will run. The DBMS user IDs are determined by the connection setting type. 5. Enter the corresponding password. Note that pooled password is only required for connection_pooling deployment on Windows operating systems. 6. Click the Save button. Configuring for Deferred Management How to: Set Deferred Management Properties Monitor the Deferred Process View Deferred Process Statistics Reference: Extensions for Deferred Files You can configure the settings that are used to manage deferred requests and reports from the Web Console Deferred Configuration pane. Deferred management parameters are stored in the edaserve.cfg file. Procedure: How to Set Deferred Management Properties 1. From the Web Console menu bar select Workspace, then Configuration. 2. In the Workspace Configuration navigation pane, expand the Special Services folder, click DMF, and choose Properties from the menu. The Deferred Configuration pane opens. 3. To set properties for the deferred execution of requests, enter values for the following options: dfm_int_min Defines the minimum time interval that the DFM listener sleeps between handling two requests. dfm_int_max Defines the maximum time interval that the DFM listener sleeps between handling two requests 13-6 iway Software

373 dfm_dir Running and Monitoring Your Server Defines the location where deferred requests and responses are stored. For related information, see Extensions for Deferred Files on page dfm_maxage Defines the maximum number of days that deferred reports are kept in the server after they are created. dfm_maxoutput Defines the maximum size of a deferred report expressed as the number of kilobytes [K] or megabytes [M] between 0 and 65535, where 0 means unlimited. Kilobytes is the default. Reports that over this limit are removed. Procedure: How to Monitor the Deferred Process 1. From the Web Console menu bar select Workspace, then Configuration. 2. In the Workspace Configuration navigation pane, expand the Special Services folder, click DFM, and choose Monitor from the menu. The Deferred Monitor pane displays the following information: DFM_Dir Available Disk space is the amount of storage space available in the DFM_DIR directory. This allocation differs according to operating system. For Windows, it is the size of the drive where the server was configured. Number of Requests Done Since Startup is the total number of deferred requests that were executed since the server was started. Number of Responses Ready is the total number of deferred reports stored in the DFM_DIR directory. Procedure: How to View Deferred Process Statistics 1. From the Web Console menu bar, choose Workspace, then Configuration. 2. In the Workspace Configuration navigation pane, expand the Special Services folder, click DFM, and choose Statistics from the menu. The Process Statistics pane displays the following information: Name: DFM Status: Process ID: Port Number: Standard Windows memory management statistics for the monitored process. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-7

374 Configuring Workspace Manager Reference: Extensions for Deferred Files Following table lists possible extensions for the deferred files listed in the dfm_dir directory. Extension RQD RQP RQF RQI RPF RPI DEL Description Data file. Contains user ID, optional flags, and so on. Request file. Indicates request is being executed. Completed request file, ready to be executed. Incomplete request file, request is being received. Complete response file, ready to be retrieved. Incomplete response file. Request is deleted iway Software

375 General Workspace Configuration Settings How to: Set General Workspace Parameters Reference: General Workspace Settings Settings License Settings NLS Settings Notification Settings Running and Monitoring Your Server You can set a variety of general parameters from the Workspace navigation pane, organized under the following categories: General, , License, NLS (National Language Support), and Notification. These settings are saved in appropriate configuration files. Procedure: How to Set General Workspace Parameters 1. On the Web Console menu bar, select Workspace, then Configuration. 2. In the navigation pane, expand the General folder, if not already expanded. 3. Click the one of the following folders: General Settings License NLS Notification The corresponding configuration pane is displayed at the right. 4. Review or change settings as required. 5. Save your changes. When indicated, the server must be restarted for your changes to take effect. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-9

376 Configuring Workspace Manager Reference: General Workspace Settings The following settings are saved in the edaserv.cfg file. If you change the value of an items marked with an asterisk (*), you must restart the server. Parameter edaprint_ history* edaprint_ max_lines* edaprint_ max_days* edaprint_ ipname* hliprint_max_ lines* automatic_ recovery transaction_ coordination _mode* tscom3_kill_ delay1 tscom3_kill_ delay2 profile_ parameter Description Specify the number of saved edaprint.log files to keep. The default value is 5. For details, see Controlling EDAPRINT History in Chapter 15, Troubleshooting. Specify the maximum number of lines for each edaprint.log before it is archived and a new edaprint log is started. For details, see Controlling EDAPRINT History in Chapter 15, Troubleshooting. Specify the maximum number of days for each edaprint.log before it is archived and a new edaprint log is started. For details, see Controlling EDAPRINT History in Chapter 15, Troubleshooting. Enter Y or N to indicate whether the server should convert IP host addresses to names. This requires DNS lookups. The default value is N. Enter the maximum number of lines for the hliprint.log before it is archived and a new hliprint log is started. For details, see Controlling the HLIPRINT Transaction Log in Chapter 15, Troubleshooting. Enter Y or N to indicate whether server should automatically recover crashed listeners and/or special services. The default value is N. Available settings are ON and OFF. ON activates the iway Transaction Coordinator. With this setting, two-phase commit will be used when XA-compliant databases participate in a transaction. The default setting is OFF. Defines the time allowed, in seconds, for an agent to stop before a soft kill is sent. The default value is 16 seconds. Defines the time allowed, in seconds, for a soft kill to work before a hard kill is sent. The default value is 32 seconds. Available settings are Y and N. If the server, user, or group profiles contain any unresolved variables, set the profile parameter keyword to Y. The default setting is N iway Software

377 Running and Monitoring Your Server Reference: Settings The following settings are saved in the odin.cfg file. Parameter smtp_host sender_ Description Enter the IP address of the SMTP server using the notation that is supported for your IP version (for example, for IPv4 use base 256 standard dot notation; when IPv6 is supported on a platform, and enabled, you can use either 256 standard dot notation or IPv6 notation.) Enter the sender address that appears in the 'From' field in s. Note: If send operations fail, verify that the smtp host is active and/or that a virus scanner is not blocking edachkup. Reference: License Settings The following settings are saved in the edaserv.cfg file. For related information, see Viewing and Editing Your License Number on page Parameter License Number License Number for Active Report Site Code Description Enter the License number (required for the type of server you are using). Enter the License number for Active Reports (required to use WebFOCUS Active Reports). Enter the Site code number (required for support calls). Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-11

378 Configuring Workspace Manager Reference: NLS Settings The following settings are saved in the nlscfg.err file. Complete the configuration, then click Save and Restart. The server creates the necessary transcoding, sorting, and monocasing tables for the selected code page. Parameter CODE_PAGE LANG Description Is the code page of the data sources accessed by the server. Select a code page from the drop-down list of supported code pages, including Unicode. The default value is 137 for Windows and UNIX, and 37 for i5/os and z/os. Controls the default value of the code page, and the language of server error messages if available in translation. Choose a language name or abbreviation from the drop-down list. The default value is AMENGLISH (American English) on all platforms. An asterisk to the right of a language for example, French* means that the server is localized for that language: translated server error messages (for example, FOCnnn through FOCnnnnn) are available and the WebFOCUS Reporting Server Web Console is fully displayed in that language once you configure and restart the server. If you choose a language without an asterisk, the server messages and console appear in English. If you would like the messages and console to appear in a language for which the server has not been localized, you can provide translation yourself. To localize the console, translate the file wceng.lng and rename it to wcxxx.lng where XXX is the three-letter language code for the server. For error messages, translate all or any relevant *.err files and append the same three-letter language code to it. All files are located in the \home\nls folder iway Software

379 Running and Monitoring Your Server Parameter CURRENCY Customize code page conversion tables Recreate FOCUS system files Description Enter a one-byte character or hexadecimal value that identifies a currency symbol. Examples of one-byte characters are: for euro for yen $ for U.S. dollar for British pound sterling You can use any other single character to designate the currency symbol. Examples of a hexadecimal value on code page 137 are: 0x80 for euro 0x24 for dollar sign Check this box to display a list of code pages and descriptions for the possible data sources accessed by the server or the client code page. Several code pages are always selected by default and cannot be deselected. These are: 37 --IBM MF United States; U.S. English/Western Europe (Latin 1); U.S. English; IBM MF Open Systems (Latin 1); Windows Latin; Unicode (UTF-8); Unicode (UTF-EBCDIC). Other code pages may also be selected by default, depending on the LANG attribute chosen. The NLS Configuration Wizard creates conversion tables for these code pages to make them available for subsequent conversion. Select any additional code pages for which you want tables to be created. For example, if you want to designate a particular code page to be generated in synonyms for flat (fixed) files or VSAM files, you must already have created a code page conversion table using the Customize code page conversion table option during NLS configuration. For related information, see Synonym Creation Parameters in the adapter chapter for one of these data sources in the Adapter Administration for Windows, UNIX, OpenVMS, i5/)s, and z/os manual. Check this box if you wish to load FOCUS internal files in the server s code page (as defined in the CODE_PAGE field). Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-13

380 Configuring Workspace Manager Parameter Recreate FOCUS sample files Description Check this box if you wish to load the sample files (which are delivered with your software) in the server s code page (as defined in the CODE_PAGE field). Reference: Notification Settings The following notification settings are saved in the edaserv.cfg file. Note that you must first obtain the name of an SMTP host, or configure one, and have that name available when you configure notification. For details, see Settings on page Parameter server_ admin_ and User ID Description Enter a server admin address, then choose a corresponding User ID from the drop-down list and click Add. The ID is added to the list of recognized server administrators. Note: If sends fail, verify that the smtp host is active and a virus scanner is not blocking edachkup iway Software

381 Running and Monitoring Your Server Parameter wsm_ Description Select one or more check boxes to control Workspace Manager s distribution of s to addresses defined in the server_admin_ field when the following predefined events occurs: CRASHED - listeners, special services or agents crashed. ABORTED - agents aborted. NORESOURCE - no more agents are available for required service (maximum number is reached). NODISKSPACE - there is a disk space error in processing a deferred request (in the dfm_directory). The request is automatically rescheduled for 1 minute later, on the assumption that the space problem is temporary. If execution fails again it will be rescheduled for 2 minutes later, then 4, 8, and so on, until the problem is resolved or the request is cancelled. Note: After configuring SMTP services, go to the Scheduler Configuration pane to request that an be sent when a deferred procedure fails. Follow these steps: 1. Click Special Services on the Workspace Configuration navigation pane and choose SCHEDULER, then Properties from the menu. The Scheduler Configuration pane opens. 2. Choose failure from the sched_ pull-down menu to send an message when a procedure fails. Note: If send operations fail, verify that the smtp host is active and/or that a virus scanner is not blocking edachkup. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-15

382 Editing Configuration Files Editing Configuration Files Manually editing configuration files requires extensive knowledge of the inner workings of the server. All files except VERSION.CFG are available for editing in the Web Console text editor. VERSION.CFG is created by the installation/configuration process and is only available for viewing from that page. Procedure: How to Edit Configuration Files 1. From the Web Console menu bar, select Workspace, then Configuration. 2. In the Workspace Configuration navigation pane, expand the Configuration Files folder. You can open the following files for editing: Workspace opens edaserve.cfg Administration opens admin.cfg Communication opens odin.cfg (For related information, see Using JVM Tuning Options to Improve Memory Usage on page ) Server Profile has three options: Server Profile opens edasprof.prf Trace Profile opens ibitrace.fex FDS Profile opens suprof.prf User Profile opens user.prf Note that both Server Administrators and Application Administrators can edit the user.prf file. However, Server Administrators can edit all user.prfs, while Application Administrators can only edit their own profiles. Miscellaneous has three options: Server Startup Script opens edastart.bat NLS opens nlscfg.err Environment opens edaenv.cfg iway Software

383 Viewing and Editing Your License Number Running and Monitoring Your Server You can view and change the current license code and provide and/or change your site code using the License Management pane. The license code is encoded to determine the configuration, additional products available in the configuration, the number of CPUs on the server, and the number of user seats the configuration supports. Procedure: How to View and Edit Your License Number and Site Code 1. From the Web Console menu bar, select Workspace, then Configuration. 2. In the Workspace Configuration navigation pane, expand the General folder and click License. The License Management pane opens. 3. Enter the following codes and click the corresponding Save button: License number (required for the type of server you are using). License number for Active Reports (required to use WebFOCUS Active Reports). Site code number (required for support calls). For more information on how to obtain a new license code, contact Customer Support or the local Information Builders sales office. Fine-Tuning the Server In this section: Using JVM Tuning Options to Improve Memory Usage How to: Fine Tune JVM Settings From the Web Console You can fine-tune the server to optimize performance. A Java Services folder on the Workspace Configuration navigation pane enables you to create and manage multiple client connections to JSCOM3, thereby supporting redundancy and load balancing, as well as the ability to refresh JSCOM3 instances while ensuring that at least one connection is always available. Java exceptions are displayed in the edaprint.log file, and JVM version and path information is displayed in the edaprint.log file and on the Java Services Configuration pane. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-17

384 Fine-Tuning the Server Using JVM Tuning Options to Improve Memory Usage You can obtain better memory usage performance in production servers by properly tuning the JVM heap and stack sizes using three options on the JVM Settings tab of the Java Services Configuration pane. These options set initial Java heap size, maximum Java heap size, and Java thread stack size. The options update the odin.cfg file. For related information, see Editing Configuration Files on page Before setting these parameters, it is useful to understand the following relationships. Heap Size JSCOM3 is the server s interface to the JVM. When you start JSCOM3, you can specify memory allocation for the JVM using the -X options shown in the following table. JVM option passed to JSCOM3 -Xms -Xmx Description Determines the initial (minimum) Java heap size. Determines the maximum Java heap size Heap size does not determine the amount of memory your process uses. As you monitor your Java process, you may notice that the amount of memory used exceeds the amount you have specified for -Xmx. This occurs because -Xmx limits the Java heap size and may allocate memory for other things, including a stack for each thread. Therefore, the total memory consumption of the JVM may exceed the value of -Xmx. Stack Size Each thread in the JVM is assigned a stack. The stack size limits the number of threads you can use. If the stack size is too large, you risk running out of memory since each thread is allocated more memory than it needs. The following chart describes the JVM Option passed to JSCOM3. JVM option passed to JSCOM3 -Xss Description Determines the stack size for each thread. You can make this value as low as 1K: -Xss1K. However, if the stack space is too small, you will eventually see an exception class java.lang.stackoverflowerror iway Software

385 Running and Monitoring Your Server Controlling Heap and Stack Size JSCOM3 uses default values for the minimum (initial) and maximum heap sizes and for the stack size of each thread. To improve performance, you can override the JSCOM3 default settings using the initial Java heap size, maximum Java heap size, and Java thread stack size options. For details, see How to Fine Tune JVM Settings From the Web Console on page You can also choose the Force Finalization option on the Java Services menu, which assists in memory management by releasing memory that is not currently in use by the Java Virtual Machine (JVM). Procedure: How to Fine Tune JVM Settings From the Web Console 1. From the Web Console menu bar, select Workspace, then Configuration. 2. In the navigation pane, click the Java Services folder and choose Properties from the menu. The Java Services Configuration pane opens. 3. Click the JVM Settings tab and enter values for the following parameters: Initial Java Heap Size. This keyword defines the initial Java heap size in megabytes (MB), which reflects the minimum amount of memory that is already being used. Supply a positive integer number. Maximum Java Heap Size. This keyword defines the maximum Java heap size in megabytes (MB). Supply a positive integer number. Note: With server-side Java applications like JSCOM3, it is good practice to set the initial (minimum) and maximum heap sizes to the same value. Java thread stack size. This keyword defines the Java thread stack size in kilobytes (KB). Supply a positive integer number. 4. Click Save and Restart Java Services to update the odin.cfg file and restart the server with the new settings. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-19

386 Monitoring Server Activity Monitoring Server Activity In this section: Monitoring Service Statistics Monitoring Data Services (Agents) Monitoring Sessions Monitoring Connections Monitoring Java Services Monitoring Special Services Monitoring Deferred Requests Monitoring Listeners Monitoring Web Sessions How to: Monitor Server Activity Every server type can be monitored and have its operation parameters changed through the Web Console. These changes can affect the behavior and performance of the server. The following topics describe the panes used to perform such administrative tasks on a running server. Procedure: How to Monitor Server Activity 1. On the Web Console menu bar, click Workspace, then Monitor. 2. Choose the type of statistics you wish to see: Statistics (for Services) Data Services (Agents) Sessions Connections Java Services Special Services Deferred List Listeners iway Software

387 Running and Monitoring Your Server Web Sessions The statistics appear in the right pane. Procedure: How to Refresh or Reset Statistics You can refresh or reset statistics from all Web Console monitoring panes: Click Refresh Now to refresh the statistics, or click a check box and set the number of seconds between refreshes. Click Reset to clear Workspace Manager statistics and start collecting from the beginning. Monitoring Service Statistics How to: View Statistics for a Service Reference: Basic Service Statistics Additional Service Statistics Calculating and Displaying Averages The Statistics pane displays a list of statistics for the running service, as collected by the Workspace Manager. Each Service (for example, DEFAULT, WC_DEFAULT, DFM_DEFAULT, DEFAULT_CPOOL) is represented as a row in the Statistics pane, with a final row for Total service activity. Procedure: How to View Statistics for a Service To view statistics for all services, choose Workspace, Monitor, then Statistics from the Web Console menu bar. The Statistics pane opens. Each service is represented as a row on the chart. For details, see Basic Service Statistics on page and Additional Service Statistics on page To view statistics for a particular service, expand the Data Services folder in the Workspace Configuration navigation pane. Then click a service type, and choose Statistics from the menu. The statistics for the selected service are displayed in the right pane. (Note that these statistics correspond to a row on the Service Statistics pane when you choose Workspace, Monitor, then Statistics.) Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-21

388 Monitoring Server Activity Reference: Basic Service Statistics The following chart lists and explains the parameters that appear on the Statistics pane. For related information, see Additional Service Statistics on page Parameter Service Conn Total Conn Completed Sessions Now Sessions Total Res Fails Sec Fails FOCUS Errors Avg Rsp Time Explanation Name of the service configured for Workspace Manager in the edaserve.cfg file. The service entry simultaneously defines a unique name for an agent service and signals the start of a service block, defining values for configuration parameters at the level of the service. Number of attempted connections to servers since they were started, or from the time statistics were reset. This is different from the total number of sessions, since a persistent session can connect multiple times for different requests. Number of successfully completed connections to servers since they were started, or from the time statistics were reset. Number of sessions that are currently connected to agents. Count of total sessions by all users since the server was started. This is not necessarily the same as the total number of agents started since the server was started, because agents are often reused and can also be pre-started and not used. Number of connections rejected for lack of available agents. This includes timed out queued connections. Number of connections that failed due to invalid credentials. (For details about errors and failures, see the edaprint.log file, which is saved where the server is installed.) Number of completed connections with FOCUS error(s) during request execution. (For example, adapter was not properly configured; data description or procedure was not found.) Average number of seconds for server response. (This figure does not include data transfer time.) iway Software

389 Running and Monitoring Your Server Parameter Queued Now Queue Timeout Queued Peak Queue Time Agents Now Agents Peak Memory Usage (K) Explanation Number of currently queued connections. Not applicable when queuing is off. Note: Currently running jobs are included in the connection total, but not in connections completed or in resource failures. Number of connections that went into the queue and timed out (not available when queuing is off). Maximum number of connections that are queued at any given time (not available when queuing is off). Average number of seconds spent in queue for all connections (not available when queuing is off). Number of agents that are currently running. Maximum number of agents that were running at any given time. Amount of memory, in KB, used by the server. Reference: Additional Service Statistics The following lists provide information about security, including administrative privileges, system and memory status. These statistics appear when you choose Workspace, Monitor, then Statistics from the menu bar. Security and Administration Information Statistic Security Effective server admin Server admin Application admin Server Operator Description Indicates the current Security mode setting. First valid member of a server_admin_id (configured in edaserve.cfg). Special services or listeners are run in the security context of that user account when required. List of Server Administrators configured in edaserve.cfg. List of Application Administrators configured in edaserve.cfg. List of Server Operators configured in edaserve.cfg. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-23

390 Monitoring Server Activity System Status Statistic Workspace manager process id Started on Edashare Edatemp EDATEMP available disk space CPU Usage Description Operating system ID number for the current Workspace Manager process. Date and time when the current instance of the Workspace Manager was started. Location of the edaconf directory. Location of the temporary directory. Number of kilobytes free on the disk used for the EDATEMP directory, where the edatemp subdirectory and EDAPRINT log are stored. Amount of CPU in current use by the Operating System. System Memory Status The following memory statistics are monitored: RAM (KB): RAM free (KB): paging file (KB): free paging file (KB): virtual memory (KB): free virtual memory (KB): Certain variables appear, grouped as follows, only if the corresponding total displays a value other than zero. The following chart lists and describes these variables. For related information, see Calculating and Displaying Averages on page Variable Total number of connections Average time in queue for all connections Description Total connections are displayed only if the number is not zero. Average number of seconds spent in the queue for all connections. Only available when queuing is turned on (maximum_q is greater than zero) iway Software

391 Running and Monitoring Your Server Variable Number of satisfied queued connections Average time in queue for satisfied queued connections Number of queued connections timed out Number of connections run Average agent processing time Average running time proportion Description Total number of connections that were queued and were eventually successfully connected. Connections that were queued but then failed are not counted here. Average number of seconds waiting in queue before connecting, for connections that were queued and were eventually successfully connected. The number of timed out connections is displayed only if the number is not zero. Run connections are listed only if the number is not zero. The part of the connection duration (in seconds) spent only on running the request. Average processing time is listed only if the number is not zero. The percentage of a connection s running time compared to its duration. The average running proportion is displayed only if the value is not zero. Reference: Calculating and Displaying Averages Variables that are averages (avg) are fractional numbers of seconds rounded to the nearest millisecond for display purposes, but actually computed in higher precision, depending on the operating system: Avg Rsp Time is a measure of waiting time - idle time + running (that is, agent processing) time for all connections, divided by number of connections. It is actually the average time from the moment the user clicks to send a request to connect or resume, until the moment the answer appears in the browser, when the user suspends or disconnects the session. Agent processing time is the part of the connection duration spent only on running the request. Running time proportion of a connection is the percentage of its running time compared to its duration. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-25

392 Monitoring Server Activity The accuracy of the three corresponding averages is only limited by the precision of the operating system. In the rare case where a machine is faster than the precision of its time-measuring, accuracy side effects may occur: For an individual connection that has a duration shorter than the precision of the operating system, duration and running time cannot be measured and are both 0, so the server considers it a 100% running time. A high occurrence of these instances produces an overestimated average proportion. If the duration is longer than the precision because of waiting time but the running time is still less than the precision, then a zero is counted toward the average running time and in calculating the proportion, so a 0% running time proportion is recorded. A high occurrence of these instances produces an underestimated proportion. Monitoring Data Services (Agents) How to: View Statistics for an Agent Kill Agents Pre-Start Agents View Error Messages for Agents View Service Properties From the Agents Pane Example: Viewing an Error Message for an Agent Reference: Agent Statistics System-Specific Statistics for an Individual Agent The Agents pane displays the statistics for the current list of agents monitored by the Workspace Manager. From this page, administrators can manage the existing agent processes, which can be monitored and stopped. Authorized administrators can also pre-start new agents iway Software

393 Running and Monitoring Your Server Procedure: How to View Statistics for an Agent To view statistics for all agents, choose Workspace, then Monitor, Statistics from the Web Console menu bar. The Agents pane opens. Each agent is represented as a separate row on the Agents pane. For details, see Agent Statistics on page To view additional statistics for a particular agent, click an agent row and select View Statistics from the menu. These statistics are displayed in a separate window. For details, see System-Specific Statistics for an Individual Agent on page Reference: Agent Statistics The following table lists and explains parameters that appear on the Agents pane. Each agent is represented as a separate row on the chart, under a service. Statistic Tscom ID User State Session Explanation Identification number associated with the agent. User ID associated with the server connection. Current state of the agent. Possible values are starting, stopping, idle, in use, aborted, or crashed. Starting and stopping are normal transitory states, which are self-explanatory. Idle is when the agent is not connected. It has no sessions at all, whether active or suspended. A session connects and until the moment it disconnects. This includes all time spent between a session suspension and resumption when the process is not using the CPU but still has resources allocated for at least one session. Aborted and crashed are abnormal states resulting from a fatal software error detected by the program (aborted) or by the operating system (crashed). The agent process is no longer running and these states are provided for diagnostics purposes. The server administrator can clear (using kill) such agents after the problem is investigated. Session ID uniquely identifying the currently active session. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-27

394 Monitoring Server Activity Statistic Query Time Last Command Last Executed Class Last Rsp Time Last Errnum Focus/ External IO CPU Time Memory Usage (KB) Explanation Indicates the last time that a request was made to the agent. This value is used to calculate the time an agent is idle, in cases where an idle agent limit was set. Indicates the first eight characters of the last instruction executed by the data access agent. Is the last java class executed. This includes explicit call java classes (such as CALLJAVA) and, implicitly, called classes (such as GRAPH FILE). The time from the moment the server receives the request (regardless of the requesting tool (that is, Web Console, Data Migrator, or WebFOCUS) until the request completes and the response is sent to the requestor. The last &RETCODE that is set upon procedure (FCOEXEC) completion. Zero (0) is normal; any other value indicates an abnormal completion. The first value is the number of FOCUS I/O operations performed by the agent. The second value is the number of External input operations performed by the agent. Total CPU time used by the agent, displayed as hours:minutes: seconds.milliseconds (for example, 0:00:00.000). Amount of memory, in KB, used by the agent. Reference: System-Specific Statistics for an Individual Agent Additional statistics appear when you click a row in the Agent Statistics pane, and select View Statistics from the menu. You will see the Process ID followed by system-specific statistics for the agent process, then additional statistics that are portable across all platforms, as described in the following chart. Statistic Number of Sessions Last Command Last Response Time Last Errnum Explanation Current number of sessions connected to the agent. Last instruction executed by the agent against the Server. Last registered response time. Last FOCUS error iway Software

395 Running and Monitoring Your Server Statistic Last Executed Class Last Master File Name Last Procedure Name Focus I/O External Database Input Number of Transactions or HLI Commands PageFaultCount PeakWorkingSetSize QuotaPeakPagedPool Usage Pagefile usage PeakPagefile Usage Total Execution Time Explanation Last executed class. Last Master File that was processed by the agent. The displayed name can be up to 64 characters. Last Procedure that was processed by the agent. The displayed name can be up to 64 characters. The first value is the latest number of FOCUS I/O (BASEIO) operations performed by the agent, as determined by the? STAT command. The second value is the latest number of External I/O (READ) operations performed by the agent, as determined by the? STAT command. These numbers can match the number of report lines in simple unsorted print requests, but can be affected by sorting, accumulations, and request screening, which may be passed to an underlying DBMS for optimization purposes. Number of External Database rows retrieved for a TABLE command, or FIXFORM data captures for a MODIFY command performed by the agent. Number of transactions performed by the agent. Standard Windows memory management statistics for the monitored process. Cumulative execution time of transactions performed by the agent. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-29

396 Monitoring Server Activity Procedure: How to Kill Agents To stop an individual agent, click the agent's row and choose Kill Agent from the menu. The running agent is terminated, invalidating any current connection to that agent. If a request is then issued from such a connection, an error message is returned. Stopping an agent is therefore an emergency administrative measure, as it disrupts the application. After an agent is terminated, the Agents pane refreshes automatically. The corresponding row of the terminated agent remains, and the State is listed as 'stopping' until the row eventually disappears. To stop an individual agent without permitting the DBMS to perform any cleanup tasks, choose Hard Kill from the menu. Note: This option should only be used when Kill Agent fails. For extreme situations in which you want to terminate all running agents, click the Kill All Agents button at the top of the pane. Procedure: How to Pre-Start Agents Use this method to start additional agents, even when there are agents already running. To pre-start new agents, type in the number of agents you wish to start, and click Start. Procedure: How to View Error Messages for Agents If a procedure generates an error, you can view an error message on the active agent. 1. From the Web Console menu bar, choose Workspace, Monitor, then Agents. The Agents pane opens. 2. In the Tscom ID column, click the number associated with an agent and choose View Error from the menu. The latest error is displayed in a separate window iway Software

397 Running and Monitoring Your Server Example: Viewing an Error Message for an Agent The following error was generated on an agent when a procedure was run against a file that could not be found. Clicking the number of the agent that ran the procedure produced the following message: (FOC205) THE DESCRIPTION CANNOT BE FOUND FOR FILE NAMED: XYZ BYPASSING TO END OF COMMAND Tip: The error message is also stored in the Session Log, where you can access it by choosing My Console, then Session Log. There you can click on the message to see expanded information, including troubleshooting suggestions. For example: (FOC205) THE DESCRIPTION CANNOT BE FOUND FOR FILE NAMED: No data description can be found for the file requested. Check the Master File Descriptions allocated or available, or the spelling of the file name. Procedure: How to View Service Properties From the Agents Pane Since agents are associated with services, you may wish to quickly view current service properties without accessing the Service Configuration pane. In the Agents pane, simply mouse over the service name to display the list of service settings. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-31

398 Monitoring Server Activity Monitoring Sessions How to: View Statistics for a Session Kill a Session Reference: Session Statistics The Sessions pane displays the statistics for the current list of sessions assigned to data access agents, enabling administrators to monitor and, if necessary, kill individual sessions. Procedure: How to View Statistics for a Session To view statistics for all sessions, choose Workspace, then Monitor, Sessions from the Web Console menu bar. The Session pane opens. Each session is represented as a separate row on the Sessions pane. For details, see Session Statistics on page Reference: Session Statistics The following table lists and explains the parameters that can appear on the Sessions pane. Statistic Tscom ID Session State User Explanation The agent to which the session is connected. Identification number associated with the session. Current state of the session. Possible values are active, suspended, or terminating. active is when the session is connected and active (not suspended). suspended is when the session is connected but suspended. terminating is a transitory state when the session is killed. User ID that connected the session iway Software

399 Running and Monitoring Your Server Statistic Last Query Last Command Last Errnum Code Page Connected From CPU Time Explanation Last time a request was made by the session. This value is used to calculate the time a session is idle, in cases where idle session limit was set. First eight characters of the last instruction executed by the session within its agent. Last error message that occurred during server communications. If all clients have disconnected, there will not be any statistics on this page. If no error has occurred, the value will be zero. Character code page used by the client connected to the session. For some protocols, indicates the localization of the client who connected the session by displaying its network address. For example, for TCP/IP, the client's IP address appears. Total CPU time, in seconds, used within the session. Procedure: How to Kill a Session To terminate a session, click the session's row and choose Kill Session from the menu. The session is forcefully disconnected from its agent. After a session is terminated, the Sessions pane refreshes automatically. The corresponding row of the terminated session remains, and the State is listed as terminating until the row eventually disappears. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-33

400 Monitoring Server Activity Monitoring Connections The Connections pane displays the statistics for the current list of connections, enabling administrators to monitor, and if necessary, cancel individual connections. A connection refers to a physical connection between Client and Server. There are two types of connections: active and queued. How to: View Statistics for a Connection Kill a Connection Reference: Connection Statistics An active connection is one that is assigned to a session in a data access agent. A queued connection is one for which there are no available agents for the requested service, and the service is configured with a queue. A queued connection waiting for an agent becomes active as soon as an agent is available. If the maximum time to wait in the queue is reached, the connection is automatically cancelled by the Workspace Manager. Procedure: How to View Statistics for a Connection To view statistics for all connections, from the Web Console menu bar select Workspace, Monitor, then Connections. The Connections pane opens. Each connection is represented as a separate row on the Connections pane. For details, see Connection Statistics on page iway Software

401 Reference: Connection Statistics Running and Monitoring Your Server The following table lists and explains the parameters that appear on the Connections pane. Statistic Type Status Session User Authenticati on Requester ID Time In Connected From Explanation Connection type, either connect or resume. Current status of the connection, either active or queued: Active indicates that there is a session associated with the connection. Queued indicates that there is no session yet because the connection is being queued. This is applicable only when queueing is set to On. Session associated with the connection, if any. User ID that connected the session. The type of authentication used to connect, either trusted, explicit, or IWA. Unique identifier for the network connection created by a listener. The time at which the connection was activated or queued. This is the time value used to decide when a queued connection times out. The network address of the connecting client. Procedure: How to Kill a Connection To cancel a connection, click the connection's row on the Connection pane, and choose Kill Connection from the menu. For an active connection, its session is forcefully disconnected from its agent. For a queued connection, it is simply cancelled and the client gets the same error that it would get if queueing was off and there were no available agents, or if the queue was full. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-35

402 Monitoring Server Activity Monitoring Java Services The Java Services pane displays statistics for Java Services monitored by the Workspace Manager. Multiple connections are supported, providing redundancy and load balancing capabilities, as well as the ability to refresh JSCOM3 instances after a specified number of connections, while ensuring that at least one connection is always available. Reference: Java Services Statistics The following table lists and explains the parameters that appear on the Java Services pane. Statistic Jscomid Port Status Process ID Connections Active Connections Last User Last Executed Class Free Memory (KB) Explanation Unique identification number assigned to each Java Service. You can Start and Kill JSCOM3 connections from the Java Services pane. Each started connection is issued a unique number. If you kill a connection, its number is retired. A new connection is assigned an entirely new jscomid. You can also control the time intervals at which information is refreshed on the Java Services pane. Port number for each Java service (numbering starts with a base number and increments by one for each active service). Current status of connection. Possible values are: starting, active, stopping, stopped. Operating-system specific process identification number associated with each Java Service. Total number of clients connected to JSCOM3 (both active and inactive). Active client connections to JSCOM3. Name of user that executed the class. Last executed Java class. This includes explicit call java classes (such as CALLJAVA) and, implicitly, called classes (such as GRAPH FILE). Amount of memory, in KB, available to the JVM (Java Virtual Machine) iway Software

403 Running and Monitoring Your Server A Process Monitor is available for individual client connections to JSCOM3. To access the Process Statistics pane, expand the Java Services folder, click a connection, and choose Statistics from the menu. Monitoring Special Services How to: Enable/Quiesce or Start/Stop Special Services Reference: Special Services Statistics Process Monitors for Special Services You can monitor statistics and processes for Special Services from the Workspace Configuration pane. You can also quiesce and enable some Special services. Reference: Special Services Statistics The statistics that appear for the Special Services are listed in the following chart. Statistic Name Status Process ID Port Number/Directory Number of Requests CPU Time Mem. Usage (K) Description Displays the type of the special service (for example, FDS, SCHEDULER, DFM.). Status of the special service. Possible values include: Active, Not Active, and Stopped. Operating-system specific process identification number associated with each special service running in a Workspace Manager address space. Port number or directory associated with the special service, if applicable (for example, FDS Port or DFM Directory). A list of standard Windows memory management statistics for the monitored process. Total CPU time used by the agent, displayed as hours:minutes: seconds.milliseconds (for example, 0:00:00.000). Amount of memory (in KB, used by the agent. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-37

404 Monitoring Server Activity Reference: Process Monitors for Special Services Process Monitors are available for FDS and DFM. The displayed information varies to suit each the service. For FDS the Process Monitor displays the following information: Name: FDS Number of connections: Number of FCB blocks: Last user: Last executed HLI command: For DFM the Process Monitor displays the following information: Name: DFM DFM_DIR available disk space (KB): Number of requests done since startup: Number of responses ready: Procedure: How to Enable/Quiesce or Start/Stop Special Services 1. From the Web Console menu bar, select Workspace, Configuration. 2. Expand the Special Services folder in the navigation pane. 3. Click a Special Service. Choose one of the following options: Quiesce/Enable or Start/Stop from the menu. The Special Services pane reflects the changed status: For Quiesce or Enable: active or not active. For Start or Stop: starting or stopping iway Software

405 Running and Monitoring Your Server Monitoring Deferred Requests How to: View Statistics for Deferred Requests Retrieve the Answer Set for a Deferred Request Delete a Request From the QueueTest a Request Test a Request Reference: Deferred List Statistics The Deferred List pane is used to view the current status of all deferred reports, to stop queuing or executing reports, and to remove reports from the queue. Procedure: How to View Statistics for Deferred Requests From the Web Console menu bar: 1. Choose Workspace, Monitor, Deferred List. The Deferred List pane opens. Each row displays statistics for a procedure that has been submitted for deferred execution. For details about these statistics, see Deferred List Statistics on page All deferred requests are displayed by default. However, you can filter the list by choosing one of the options listed on the following chart. Option All Ready Queuing Executing Agent crashed Connect failed Exceed limit Description Displays all deferred requests. Displays response files that are ready to be picked up. Displays requests that are waiting to be executed. Displays requests that are being executed. Displays agents that have crashed during execution (that is, incomplete response files). Displays requests that failed to connect to the server (that is, communication errors). Displays requests that exceeded the connection limit. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-39

406 Monitoring Server Activity Option Unknown Description Indicates failure to determine request status. These items required you to try again. Tip: To display the Deferred List pane with statistics for a specific procedure that has been run in deferred mode, choose Procedures on the Web Console menu bar, select the procedure from an application folder, then choose Deferred List from the menu. Reference: Deferred List Statistics The following table lists the parameters that appear on the Deferred List pane. Parameter Defer ID User ID Application Procedure Submitted Time Days Left Status Description Unique identifier that the server assigns to each deferred request submitted. ID of the user who requested deferred execution of the named procedure. Name of the application that contains the procedures being run in deferred mode. Name of the procedure being run in deferred mode. Time the request for deferred execution is submitted. Number of days the generated report will be kept on the server. Note: This value is based on the deferred configuration keyword dfm_maxage. For details, see How to Set Deferred Management Properties on page Can be one of the following: Ready, Queuing, Executing, Agent crashed, Connect failed, Exceed limit, or Unknown. Procedure: How to Retrieve the Answer Set for a Deferred Request From the Web Console menu bar: 1. Select Workspace, Monitor, Deferred List. The Deferred List pane opens. 2. Click anywhere in a request row whose status is Ready, and choose get to retrieve the answer set for the deferred request in that row. The output is a displayed in the right pane iway Software

407 Running and Monitoring Your Server Procedure: How to Delete a Request From the Queue From the Web Console menu bar: 1. Select Workspace, Monitor, then Deferred List. The Deferred List pane opens. 2. Click anywhere in a request row, choose Delete to remove the request from the queue. The status of the row in the Deferred List pane changes to Deleted. Tip: If you wish to delete multiple rows, either click the check box next to the rows you wish to delete or click the check box next to the column headings to select all rows. Then click the Delete Selected button. 3. Click the Refresh icon to update the list. Procedure: How to Test a Request From the Web Console menu bar: 1. Select Workspace, Monitor, then Deferred List. The Deferred List pane opens. 2. Click the check box next to a row you wish to test. 3. Click the Test Selected button to instantly update the status of the request(s). Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-41

408 Monitoring Server Activity Monitoring Listeners How to: Enable/Quiesce or Start/Stop Listeners Reference: Listeners Statistics You can monitor statistics for Listeners from the Workspace Configuration pane. You can also quiesce and enable some Listeners. Reference: Listeners Statistics The following table lists and describes the statistics that appear on the Listeners pane. Statistic Name Status Process ID Port Number/Name Remark Number of Requests CPU Time Mem. Usage (K) Description Identifies the type of listener by displaying its network protocol (for example, HTTP, TCP). Status of the listener. Possible values include: Active, Not Active, and Stopped. Operating-system specific process identification number associated with each listener running in a Workspace Manager address space. Port number or name associated with each listener. Event remarks. A list of standard Windows memory management statistics for the monitored process. Total CPU time used by the agent, displayed as hours:minutes: seconds.milliseconds (for example, 0:00:00.000). Amount of memory, in KD, used by the agent iway Software

409 Procedure: How to Enable/Quiesce or Start/Stop Listeners 1. From the Web Console menu bar, select Workspace, Configuration. 2. Expand the Listeners folder in the navigation pane. Running and Monitoring Your Server 3. Click a Listener. Choose one of the following options: Quiesce/Enable or Start/Stop from the menu. The Listener pane reflects the changed status: For Quiesce or Enable: active or not active. For Start or Stop: starting or stopping. Monitoring Web Sessions How to: View Statistics for a Session Reference: Web Session Statistics The Web Sessions pane displays the statistics associated with current web sessions. Procedure: How to View Statistics for a Web Session To view statistics for all Web sessions, from the Web Console menu bar select Workspace, Monitor, then Web Sessions. The Web Sessions pane opens. Each web session is represented as a separate row on the Web Sessions pane. For details, see Web Session Statistics on page To view statistics for all a single Web session, click a row and select View Statistics. The statistics are displayed in a separate windows, including the following additional information about the web session: Number of Requests Login Type HTTP User Agent URL Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 13-43

410 Migrating Your Server Reference: Web Session Statistics The following table lists the parameters that can appear on the Sessions pane. Parameter Web Session ID User Remote Address Login Time Last Access Time Authentication Console Message Count Explanation A unique number that the Server assigns to a specific user for the duration of that user's session. Every time you connect to the Web Console, a new session ID is assigned. The connected user. The IP address or machine where the web browser running Web Console resides. The time when the Web Session was originated. The last time the user was active in this web session. The mechanism that performs user authentication at the time the web session is created. The number of messages a user received in this session. Tip: To see the messages in the Session log, click a row and choose View Console Messages. Migrating Your Server It is recommended that you migrate configuration information from previous releases after you verify the proper basic installation of the new release. Procedure: How to Migrate Configuration Information To migrate from a previous release: 1. From the Web Console menu bar, select Workspace, Migrate. The Migrate pane opens. 2. Type the full path of the configuration instance directory (EDACONF). 3. Click the Migrate button iway Software

411 14 Managing Listeners and Special Services The following section describes how to manage listeners and special services. Topics: Using the Listeners and Special Services Configuration Panes

412 Using the Listeners and Special Services Configuration Panes Using the Listeners and Special Services Configuration Panes From the Web Console menu bar, click Workspace, Configuration, then expand the Listeners folder or the Special Services folder on the navigation pane. You can modify communication parameters of existing nodes, remove existing nodes, or add new nodes. Note: You must not delete the HTTP listener node. Without it you cannot start the Web Console after a server restart. Three major components must be set to establish communication between a client and a server: the Client, the Protocol, and the Server. A communication configuration file is broken down into blocks called NODEs. Each NODE is identified by name and represents one client, one server (a listener node), or one cluster, and is identified by the keyword CLASS. Each block also describes all parameters necessary for communication, security, and so on. Note: The client and agent must communicate using the same protocol iway Software

413 15 Troubleshooting The Web Console enables administrators to access several diagnostics tools that can be used to visualize different internal information. The following section describes the pages used to access such information to perform problem analysis tasks. Topics: Viewing Version Information Analyzing Server Activity Analyzing FOCUS Database Server Activity Tracing Server Activity z/os-specific Troubleshooting for the Unified Server z/os-specific Troubleshooting for USS/HFS Deployment Retrieving IBISNAP Output Recording and Reproducing User Actions Troubleshooting the Console Workspace Manager Safe Mode Server Processes Gathering Diagnostic Information for Customer Support

414 Viewing Version Information Viewing Version Information The Version information page displays the main identification parameters of the server configuration that was in effect when the server was started. Procedure: How to Access Version Information on the Web Console On the Web Console menu bar, click Help, then select Version. The Version pane opens. The following information is displayed: Parameter ConfigurationDate Build date, gen number, release, source date WF jar seq number WF jar release Build system Support System Host Name Server Name Maximum number of adapters Explanation Indicates the configuration date of the Server. Identifies the release and build dates of a running instance of the Server. Provides jar-related information. Build- and system-related information. Name of the machine where the server is installed. As defined in the configuration file. Note: Used on Windows platforms as the system service name for the Server. The maximum number of adapters is determined by the license code in effect iway Software

415 Troubleshooting Analyzing Server Activity How to: Access the edaprint.log File Control EDAPRINT History From the Web Console Reference: Controlling EDAPRINT History You can use the Server Log pane in the diagnostics section of the Web Console to view the current or prior server activity log (edaprint.log) from either a management perspective (Session and Connection activity) or a raw version of the log with or without filtering for certain components and IDs. The activity log chronologically records all server activity since the Workspace Manager was started; it contains basic activity information, as well as server start up information and IBISNAP and shutdown information. IBISNAP is a snapshot of the server environment showing various usage statistics, and listener and agent status. If an abend occurs, the snapshot contains additional debugger stack information that aids the Customer Support Services staff in determining the problem. You can view the first 50,000 lines of the log file from the Web Console. If you wish to view lines beyond 50,000, you can Open or Save the file in a text editor. Procedure: How to Access the edaprint.log File 1. From the Web Console menu bar, select Workspace, Diagnostics, then Server Log. The Server Log navigation pane displays folders for EDAPRINT and HLIPRINT log files. 2. If you wish to apply filtering to log files, click the Filter icon above the navigation pane. No Filtering is checked by default. If you wish to apply filtering, choose: Filtered to expose a list of filtering criteria. For any item, clicking the check box without an entry in the input box filters on all items of that type. If you also enter a specific value in the input box, that filter will be executed. (For example, you can request filtering on all users, which defaults to *, or an individual user.) You can combine items from the list, mixing all of items of a type with specific items, as needed. Advanced Filtered to expose a check box for sesid. Click the check box specify the session ID on which you want to filter in the input box. 3. If you wish to refresh the list of log files, click the Refresh icon. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-3

416 Analyzing Server Activity 4. When an agent crashes, relevant information about the crash is produced and moved into the edaprint.log at a regular interval. You can force this move to occur immediately by selecting Write IBISNAP Information to the Current Log from the menu bar. For details about IBISNAP, see Retrieving IBISNAP Output on page Expand the EDAPRINT folder and click an edaprint.log file to open a menu from which you can choose the following: Full Report. (You can open a second menu to Open, Open in New Window, or Open or Save.) Session Reports (in summary, detail, and graph formats). (You can open a second menu to Open or Open in New Window.) Connection Reports (in summary, detail, and graph formats). (You can open a second menu to Open or Open in New Window.) Page Hit Reports (in summary and detail formats). (You can open a second menu to Open or Open in New Window.) Procedure: How to Control EDAPRINT History From the Web Console 1. From the Web Console menu bar, choose Workspace, the Configuration. 2. The General Settings pane opens at the right. 3. Enter values for: edaprint_history Defines the number of saved edaprint.log files to keep. edaprint_max_lines Defines the maximum number of lines for each edaprint.log before it is archived and a new edaprint log is started. edaprint_max_days Defines the maximum number of days, starting from the time the server is started, for each edaprint.log before it is archived and a new edaprint log is started. Note that the new edaprint.log file will only be created after the edaprint_max_days value has been exceeded and a connection event has occurred (that is, if the server is idle, the new edaprint.log file will not be created until a connection request is received). For related information, see Controlling EDAPRINT History on page To register these settings, click Save iway Software

417 Reference: Controlling EDAPRINT History Troubleshooting The size of the server activity log, the number of files archived in the EDAPRINT history, and the maximum number of days each edaprint.log is maintained before it is archived and a new edaprint log is started are controlled by edaprint_max_lines, edaprint_history, and edaprint_max_days, respectively. Limit the size of each log file by setting the maximum number of lines to a value other than zero. There is no minimum, but the recommended value is at least 1000 lines. If the limit is too low and the system is too fast (such that two archived files can have the same file system time stamp to the same second), whichever of the archived files is deleted first is undefined. The first log file for each server start always contains more lines than the maximum because the count begins only after the edaplog process is created, thus it is larger by the size of the startup information. Each time the limit is reached, the current log file is archived and the new file starts with an additional identification line. This line indicates the rank of the file in the series of continuation files, and a reference to the archived name of the first file in the series (the one with the startup information), in a format similar to the following: continuation #n of edaprinn The number of files kept archived is determined by setting the edaprint_history parameter to the maximum number of edaprinn.log files. Each time the server is restarted or the current log reaches maximum size, the previous edaprint file is moved to edaprinn.log, and the maximum number of files is enforced by deleting the oldest files. The effective minimum number of files kept may be as high as 2 in addition to the current edaprint.log, even if edaprint_history was set to 0 or 1 because when files are split to respect edaprint_max_lines, the most recent file and the most recent file containing startup information are always preserved. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-5

418 Analyzing FOCUS Database Server Activity Analyzing FOCUS Database Server Activity In this section: Controlling the HLIPRINT Transaction Log Controlling HLIPRINT Output How to: Access the hliprint.log File Set Maximum Number of Lines for the HLIPRINT Log From the Web Console FOCUS Database Server (FDS) is a listener that enables multiple users (or multiple agents) to update central a FOCUS database simultaneously. Database transaction events are logged to the HLIPRINT log file (hliprint.log),which is created in the server directory. You can view the first 50,000 lines of the log file from the Web Console. If you wish to view lines beyond 50,000, you can Open or Save the file in a text editor. Procedure: How to Access the hliprint.log File 1. From the Web Console menu bar, select Workspace, Diagnostics, then Server Log. The Server Log navigation pane displays folders for EDAPRINT and HLIPRINT log files. 2. If you wish to apply filtering to log files, click the Filter icon above the navigation pane. No Filtering is checked by default. If you wish to apply filtering, choose: Filtered to expose a list of filtering criteria. For any item, clicking the check box without an entry in the input box filters on all items of that type. If you also enter a specific value in the input box, that filter will be executed. (For example, you can request filtering on all users, which defaults to *, or an individual user.) You can combine items from the list, mixing all of items of a type with specific items, as needed. Advanced Filtered to expose a check box for sesid. Click the check box specify the session ID on which you want to filter in the input box. 3. If you wish to refresh the list of log files, click the Refresh icon. 4. When an agent crashes, relevant information about the crash is produced and moved into the edaprint.log at a regular interval. You can force this move to occur immediately by clicking the Write IBISNAP Information to the Current Log button above the navigation pane. For details about IBISNAP, see Retrieving IBISNAP Output on page iway Software

419 Troubleshooting 5. Expand the HLIPRINT folder and click an hliprint.log file to open a menu from which you can choose the following: Full Report. (You can open a second menu to Open, Open in New Window, or Open or Save.) Session Reports (in summary, detail, and graph formats). (You can open a second menu to Open or Open in New Window.) Connection Reports (in summary, detail, and graph formats). (You can open a second menu to Open or Open in New Window.) Page Hit Reports (in summary and detail formats). (You can open a second menu to Open or Open in New Window.) Controlling the HLIPRINT Transaction Log You can control the size of the HLIPRINT transaction log by using the hliprint_max_lines parameter in the configuration file, edaserve.cfg. The parameter defines the maximum number of lines to be included in hliprint.log before it is archived and a new hliprint log is started. Each time the line limit is reached, the current HLIPRINT log file is archived to HLIPRI01 and the new file starts with an additional identification line. This line indicates that the file was truncated and looks like the following: continued from hlipri01 Archiving also takes place when the first time the FDS listener is activated and the HLIPRINT log from the previous run is found in the server directory. Procedure: How to Set Maximum Number of Lines for the HLIPRINT Log From the Web Console 1. From the Web Console menu bar, choose Workspace, then Configuration. 2. The General Settings pane opens at the right. 3. Enter a value for: max_lines Is the maximum number of lines to include in the hliprint.log before it is archived and a new hliprint log is started. You can limit the size of the log file by setting the maximum number of lines to a value other than zero. (0 means an unlimited number of lines can be included in the file.) There is no minimum, but the recommended value is at least 1000 lines. If the limit is too low, the FDS listener may experience performance problems due to excessive archiving. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-7

420 Tracing Server Activity 4. To register this setting, click Save. Controlling HLIPRINT Output The Server Administrator can control hliprint.log output by manually adding the EDAHLIP variable, with a value, to the edaserv.cfg file, in the form edahlip=value where valid values are: Setting none echo stat Description No hliprint.log is created. Turning logging off will increase performance, however, this is not recommended, because it makes it harder to diagnose problems. The hliprint.log is created and contains basic transaction information (one line per transaction; line length 80 characters). The hliprint.log is created and contains basic transaction plus timing information (one line per transaction; line length 133-characters). stat is the default value. Tracing Server Activity In this section: Filtering and Configuring Traces Customizing Trace Filters for Data Services Enabling and Viewing DBMS Traces Reference: SET TRACEUSER Commands You can activate traces at server startup or while the server is running. Information Builders recommends starting the server with traces active so that a full set of traces can be sent to Customer Support Services to help diagnose issues that arise. If you need to contact Customer Support Services for assistance, you can use a facility called savediag to expedite the transmission of server information.for details about using savediag, see Gathering Diagnostic Information for Customer Support on page Refer to the Installation manual for your platform for more information on starting the server with traces active. To activate traces for a running server, a server administrator can quickly enable or disable traces at any point in a work process by clicking Workspace, Enable (or Disable) Traces from the Web Console menu bar iway Software

421 Troubleshooting The server administrator can use the Web Console s Workspace, Diagnostics, Traces option to initiate and control a wide range of traces, and dynamically turn traces on or off for a running server. The Web Console displays the following list of traces as a tree structure in the Traces navigation pane: Workspace Manager, Data Services, Java Services, Special Services, Listeners. (The traces that are active varies depending on the types of requests that have been made against the server.) The icons above the navigation pane enable you to quickly: Icon Description Deletes all current traces. A confirmation box is displayed before the traces are deleted. A list of files, whether deleted or not, will be displayed. On Windows, only Traces that are not currently in use by a process will be deleted. Opens the Filter Traces pane, where you can select: No Filtering (the default) to display all trace information. Errors to display only the following trace information: errors, crashes, abort or fail conditions. For related information, see How to Filter Traces on page In addition, for Data Services Traces Filtering you can select Typical components or click the Custom button to access a more refined set of custom tracing options. For details, see Customizing Trace Filters for Data Services on page Opens the Traces Configuration pane, where you can choose which trace components to activate and set a trace size limit, if you wish. For details, see Filtering and Configuring Traces on page Refreshes all traces in the navigation pane. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-9

422 Tracing Server Activity If traces have been enabled, expanding a trace area in the tree structure shows individual trace files. Clicking a trace file displays the follow options: Open. Displays the trace in the right-hand browser pane. Open in New Window. Displays the trace in a new browser window. Open or Save. Enables you to open the trace in a local editor or to save it to a local disk. Delete. Enables you to delete the selected trace file. On Windows, a trace file cannot be deleted if it is still in use by a process. Note that the selected trace file is displayed with any active filtering applied. For related information, see Customizing Trace Filters for Data Services on page Once traces have been configured and turned on by a server administrator, they can be viewed from the Traces navigation pane by application administrators and server operators iway Software

423 Troubleshooting DBMS Traces. In addition to the traces available for viewing by authorized administrators from the Traces navigation pane, one type of trace is available to all users from the My Console option on the menu bar: Add DBMS Traces to the Log. This option traces activity between an adapter and an SQL data source. Being able to isolate this type of information from other types of trace information is particularly valuable for purposes of optimization. For details, see How to Enable DBMS Traces and View Trace Output in the Session Log on page Reference: SET TRACEUSER Commands If you want to turn dynamic traces on or off for one user, you can include the command SET TRACEUSER={ON OFF} in a user profile or in an individual procedure. You can also use the SET TRACEUSER=tracename command turn dynamic traces on and send the trace to a named file. The file must specify a.trc extension and use a full path name for server traces so the traces are retained after server execution. Filtering and Configuring Traces How to: Filter Traces Configure Traces Capture Traces in a Script File You can filter and configure your traces from the Web Console. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-11

424 Tracing Server Activity Procedure: How to Filter Traces If you wish to filter traces: 1. Click the Filter icon above the Traces navigation pane. The Traces Filter pane opens. 2. Select No Filtering (the default) to display all trace information. or Select Errors to display only the following trace information: errors, crashes, errno, abort or fail conditions. 3. Click the Set Filter button. The filters take affect when you enable and run traces. 4. For Data Services Traces Filtering, you can select Typical components or click the Custom button to access a more refined set of custom tracing options, which, when set, override Errors filtering. For details, see Customizing Trace Filters for Data Services on page iway Software

425 Troubleshooting Procedure: How to Configure Traces 1. From the Web Console menu bar, choose Workspace, then Diagnostics, Traces. The Trace navigation pane displays a list of traces as a tree structure. Icons above the navigation pane enable you to delete, filter, configure, and refresh the traces settings. 2. Click the Configuration icon. The Traces Configuration pane opens. 3. Optionally, set the trace size limit to a specific number of lines. After the limit is reached, trace data is dumped to an alternate file with the extension TRB. Logging continues into the trace file with extension TRC. For related information, see Limiting the Size of a Trace File on page A blank entry indicates no trace size limit. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-13

426 Tracing Server Activity 4. You can select tracing for a wide range of server components. Choose the Trace components you wish to activate. The selections you make here are written into a file called ibitrace.fex; the settings take effect on the next server start/restart. Note that Customer Support Services may request that you change from the default trace setting to a custom setting to facilitate their research. Component Description Default Components R1H QOPSYS PRH NWH NLS All Components All traceable server components. Typical Components CEH NWH2 PRH SQLAGGR STMTRACE iway Software

427 Troubleshooting Component Custom Components Description Click the Unselect All button if you wish to erase default settings or previously saved settings before you begin to specify custom components. Select components, categorized as follows (each category has a list of trace options within it): COMMAND PROCESSING COMMUNICATIONS and SYSTEMS COMMON ADAPTER LAYERS AND SERVICES SQL TRANSLATOR SQL DATA ADAPTERS OLAP DATA ADAPTERS NON-SQL DATA ADAPTERS LEGACY DATA ADAPTERS REPORT SERVICES NLS SERVICES ODIN INFORMATION SMART MODE MAINTAIN PROGRAMMER TRACES MAINTAIN INTERNAL SERVICES MISCELLANEOUS SERVICES IWAY TRANSACTION COORDINATOR XFOCUS USE-WHERE 5. Click the Save Setting button to activate your settings the next time the server is started. Tip: If you wish to restore default settings or choose typical settings, select these options, then click Save Settings. The selected group will be checked when you reopen the Custom Components list. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-15

428 Tracing Server Activity Reference: Limiting the Size of a Trace File You can use set the size limit of the trace files. The trace size limit specifies the maximum number of lines in the trace files. The value is written into the IBITRACE.FEX file as SET TRACESIZE = value and requires a server restart to activate. After the size limit is reached for a particular trace, the trace data is redirected to an alternate file with an extension of.trb. When the size limit is reached in the.trb version of the file then writing resumes with the.trc version of the file. A trace cycles between the two matched sets of files to alleviate maxing out a disk drive with large individual traces. Each cycle starts a fresh file (versus an append). If there are intermediate traces that need to be saved, it is up to the site to monitor and implement specific methods to save traces based on their needs and capabilities. For example, copying to an archive disk or secondary machine and possibly using compression. Procedure: How to Capture Traces in a Script File Capturing traces in a script file enables you to isolate server-side problems. Specifically, you can enable this type of custom trace, then reproduce the problem and capture the input commands issued from a front-end tool (such as WebFOCUS Developer Studio) to the server. Customer Support Services can then isolate debugging for the server only, instead of having to recreate a whole complex environment. You can accomplish this as follows: 1. From the Web Console menu bar, choose Workspace, then Diagnostics, Traces. The Trace navigation pane displays a list of traces as a tree structure. Icons above the navigation pane enable you to delete, filter, configure, and refresh the traces settings. 2. Click the Configuration icon. The Traces Configuration pane opens. 3. Select Custom Components. 4. Click the Unselect All button. 5. Choose NWHSIM/1 under Communications and Systems. 6. Select the Save Settings button. The trace setting will be active the next time the server is started iway Software

429 Troubleshooting Customizing Trace Filters for Data Services How to: Customize Traces for Data Services As an alternative to the error-based filtering that you can apply to any trace file, you can apply customized trace filtering for files that trace activity for Data Services agents.. When customized filtering is specified, any generic filtering in effect for other traces is overridden for the Data Services traces. Procedure: How to Customize Traces for Data Services If you wish to customize the view of trace files for Data Services:. 1. Click the Filter icon. The Traces Filter pane opens. 2. Under Data Services Traces Filtering, click the Custom button. The Custom Data Services Tracing pane opens. (If no traces are available a No Traces Available message is displayed.) 3. To customize the trace components, choose: All components to display information for all traceable server components. Typical Components (CEH, NWH2, PRH, SQLAGGR, STMTRACE). Custom Components. If you choose this option, an extensive list of components is displayed by category. Select the check boxes for components within any of the following categories: COMMAND PROCESSING Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-17

430 Tracing Server Activity COMMUNICATIONS and SYSTEMS COMMON ADAPTER LAYERS AND SERVICES SQL TRANSLATOR SQL DATA ADAPTERS OLAP DATA ADAPTERS NON-SQL DATA ADAPTERS LEGACY DATA ADAPTERS REPORT SERVICES NLS SERVICES ODIN INFORMATION SMART MODE MAINTAIN PROGRAMMER TRACES MAINTAIN INTERNAL SERVICES MISCELLANEOUS SERVICES IWAY TRANSACTION COORDINATOR XFOCUS USE-WHERE 4. Select a trace file from the Select File drop-down list, then click the Show the File button to see the selected trace in the right-hand pane. Enabling and Viewing DBMS Traces How to: Enable DBMS Traces and View Trace Output in the Session Log Example: Sample Session Log With Trace Output Both administrative and non-administrative users can choose options on the My Console menu to activate DBMS Traces and view them in the Session Log. These trace show activity between an adapter and an SQL data source. Note: On the z/os platform, you can also capture IMS adapter traces iway Software

431 Troubleshooting Procedure: How to Enable DBMS Traces and View Trace Output in the Session Log From the Web Console menu bar, choose My Console, then choose the following options: 1. Start Logging DBMS Traces. 2. View Session Log. Example: Sample Session Log With Trace Output 1. From the My Console option on the menu bar, select Start Logging DBMS Traces. 2. In the Procedures navigation pane, open an application, click a procedure and select Run from the menu. Output is displayed in the right pane. 3. From the My Console option on the menu bar, select View Session Log to review the trace output in the Session Log. 4. If you wish to toggle the time stamp on or off, click the Show Log Without/With Time button. 5. If you wish to clear the current message log of all entries, click the Clear Messages button. 6. If you wish to stop the logging of DBMS trace lines, click the Stop Logging DBMS Traces button. Server Administration for UNIX, Windows, OpenVMS, i5/os, and z/os 15-19