Example: Dynamic Mapping to Define User-Preferred Currency Options

Configuring and Managing the Oracle BI Presentation Catalog 17-3 Use care when building a catalog path. It is very common to see code that assumes the forward slash is always a path separator. Always verify your path code with an object name such as Profit Loss. ■ When you pass a catalog search filter using SOAP, you must escape the following characters: Forward slash Backward slash \ Tilde ~ Asterisk Question mark ? Caret Dollar sign ? The following search filters are all valid: Hello World Profit \ Loss Sales \ \ Cost \~\~ \ Expense\?

17.1.1.2 Attribute Files for Objects

Each object has a corresponding attribute file. For example, the analysis called Analysis1 would have a corresponding attribute file named Analysis1.atr. The attribute file contains the objects full name, access control list ACL, description, and so on. To access an object in the catalog, users must have appropriate ACL entries for that object. All objects in the catalog use ACL entries.

17.1.1.3 Lock Files for Objects

To guarantee that only one user can write to a file at one time, a lock file is created when an object is being written to. On rare occasions for example, after a power outage, temporary lock files in the catalog might not be removed completely. If Presentation Services reports of such a lock file, then you must delete it manually.

17.1.2 Locations for the Catalog

The following list provides the default locations for the directory that holds catalog files: ■ On Windows systems: ORACLE_ INSTANCE\bifoundation\OracleBIPresentationServicesComponent\coreapplicati on_obipsn\catalog ■ On UNIX systems: ORACLE_ INSTANCEbifoundationOracleBIPresentationServicesComponentcoreapplicati on_obipsncatalog You are not required to store the catalog in its default location. You can store the catalog in other locations. When you work in a cluster configuration, you store the catalog on a shared file system that all nodes in the cluster can access. For information, see Section 5.4.2, Sharing the Oracle BI Presentation Catalog. See Section 17.1.3.3, Handling Catalog Files on Various Platforms for more information on catalog directory names. 17-4 System Administrators Guide for Oracle Business Intelligence Enterprise Edition

17.1.3 File System Guidelines for Catalogs

This section describes the following guidelines for working with objects in catalogs in file systems: ■ Section 17.1.3.1, Handling Users of the Catalog ■ Section 17.1.3.2, Handling Heterogeneous Nodes ■ Section 17.1.3.3, Handling Catalog Files on Various Platforms ■ Section 17.1.3.4, Known Issues with Catalog Files

17.1.3.1 Handling Users of the Catalog

The catalog is designed to scale to thousands of concurrent users. To achieve this scaling, the catalog adheres to the following guidelines: ■ The average user typically only reads from the catalog and rarely, if ever, writes to it. In Release 11g, each user is constantly and automatically updating his or her Most Recently Used file, but each users read operations still far outweigh the users writes operations. Therefore, the read-to-write ratio is typically at least 100 to 1. ■ While a locking mechanism guarantees that only one user can write to an object at a time, it is rare for multiple users to attempt to write simultaneously to the same object. A feature called lazy locking allows users to continue reading an object even when another user is updating that object. ■ Modern file systems cache small files directly inside the directory record, such that reading any information on a directory simultaneously loads all small files directly into the operating systems memory cache. Therefore, it is good practice to keep files in the catalog small, especially the frequently read .atr metadata files. When these metadata files remain small, then all the .atr files in a directory are loaded into memory with one physical hard disk read. Every file that exceeds the small threshold adds another physical hard disk read, which can cause a 100 degradation for each large file. In other words, use care when considering storing arbitrary Properties in .atr files. ■ Reading an objects .atr metadata file using NFS is far slower than reading it directly from a local disk. For this reason, Presentation Services additionally caches all .atr files internally. This cache can become briefly stale when another node in the cluster writes data to the file that is newer than the data that is cached by the current node. Therefore, all nodes are refreshed according to the MaxAgeMinutes element in the instanceconfig.xml, whose default for a cluster is 5 minutes. This default setting commonly achieves the best trade-off between the possibility of stale data and the known performance impact. The default for an environment without clusters is 60 minutes. You can modify the MaxAgeMinutes element for your system. Its parent elements are Cache and CatalogAttributes. Before you modify the element, ensure that you are familiar with the information in Section 3.4, Using a Text Editor to Update Configuration Settings.

17.1.3.2 Handling Heterogeneous Nodes

To allow heterogeneous nodes in a cluster, the catalog adheres to the following guidelines: ■ The maximum length for the name of an object on disk is 256 bytes, which is 64 Unicode characters. The logical name is restricted to 256 Unicode characters. To adhere to this restriction, logical names greater than 32 characters are hashed. Configuring and Managing the Oracle BI Presentation Catalog 17-5 ■ The maximum length for the name of a path on disk is 32KB, which is 8000 Unicode characters. The logical path is restricted to 16000 Unicode characters. ■ All path names on disk are all lowercase. The logical path name allows mixed case, but is still case-insensitive. ■ Certain characters are not allowed for path names on disk, while the logical path name allows all characters. For example, Windows systems disallow certain characters such as the colon :, so those characters are mapped using standard HTML escape sequences. For example, the period character . becomes 2e. ■ Certain file names are not allowed on disk, while the logical object name has no restrictions. For example, Windows systems disallow certain file names such as COM, so those names are mapped using standard HTML escape sequences. For example, com becomes co6d.

17.1.3.3 Handling Catalog Files on Various Platforms

Keep the following points in mind when handling catalog files on various platforms: ■ For UNIX Platforms: UNIX kernels must commonly be configured to allow more than 4000 subdirectories per directory. See Section 17.2.1, Manually Changing Additional Configuration Settings for the Catalog for information on the HashUserHomeDirectories element. ■ For Windows Platforms: When users want to navigate catalog files using a tool such as Microsoft Windows Explorer, then they want the catalog structure based on a short path name such as c:obidemo, rather than the long default path name. Note that such navigation is not recommended. – FAT is not supported, and NTFS is required. – Performance on Windows platforms degrades noticeably when more than 8000 files exist in a single directory. Because each catalog object has two files the data file and the .atr metadata file, it is strongly recommended that you not store more than 4000 catalog objects in a single directory. See Section 17.2.1, Manually Changing Additional Configuration Settings for the Catalog for information on the HashUserHomeDirectories element. – Windows Explorer does not handle long path names properly, and it is recommended to not use Windows Explorer to navigate the internal structure of the catalog. While the file system can handle path names as large as 32KB and Presentation Services is not negatively affected, you cannot use Windows Explorer with any path name that is longer than approximately 2KB. Because a single Unicode character can require as many as 4 bytes, you might be unable to use Windows Explorer with path names of only 500 Unicode characters. This limitation does not affect Presentation Services. Because of this limitation, place the catalog in a top-level directory, such as c:\mycatalog\sales.

17.1.3.4 Known Issues with Catalog Files

The following issues are known when working with catalog files: ■ Locking across NFS systems is difficult, but Presentation Services provides an effective locking mechanism in recent patches. Obtain key patches to update older versions of Oracle BI EE as necessary. For more information, see Section 17.2.4, Validating the Catalog. 17-6 System Administrators Guide for Oracle Business Intelligence Enterprise Edition ■ Various third-party FTP programs have issues handling escape sequences, which often results in a renamed file that is doubly escaped. For example, a file that is named sa2epaint whose logical name is SA.Paint is incorrectly renamed to sa252epaint whose logical name is SA2ePaint. Avoid using an FTP program directly against a catalog. Instead, download and use the 7-Zip utility to compress the catalog files, then use an FTP program to transfer the resulting compressed file.

17.2 Maintaining the Oracle BI Presentation Catalog

This section contains the following topics on maintaining a catalog: ■ Section 17.2.1, Manually Changing Additional Configuration Settings for the Catalog ■ Section 17.2.2, Manually Creating a New Oracle BI Presentation Catalog ■ Section 17.2.3, Deploying Catalogs and Objects to Production ■ Section 17.2.4, Validating the Catalog

17.2.1 Manually Changing Additional Configuration Settings for the Catalog

In addition to the presentation settings that you can change in Fusion Middleware Control, you can modify other settings manually. Use various elements in the instanceconfig.xml file to change these settings. Before you begin this procedure, ensure that you are familiar with the information in Section 3.4, Using a Text Editor to Update Configuration Settings . To manually change additional configuration settings for the catalog: 1. Open the instanceconfig.xml file for editing as described in Section 3.6, Where Are Configuration Files Located?

2. Locate the Catalog section in which you must add the following element:

■ HashUserHomeDirectories : Specifies the hashing of directories. If you have more than 4000 catalog users or if you intend to have more than 4000 catalog users in the future, then you must turn on the hashing of users home directories to address a file system limitation. To do so, set the HashUserHomeDirectories element to 2 from its default value of 0. When this element is turned on, for example, the default name for user Steves home directory would become usersststeve.

3. Include the element and its ancestor element as appropriate, as shown in the

following example: ServerInstance ps:Catalog xmlns:ps=oracle.bi.presentation.servicesconfigv1.1 Caution: Keep the following points in mind: ■ The HashUserHomeDirectories element must be set immediately after installing Oracle BI EE to be effective. ■ Include only one Catalog element in the instanceconfig.xml file or unexpected results might occur. Unless expressly noted, include most nodes in an XML document only once.