Question & Answer
What is the relationship between the Planning Store Database, the FileSys.ini file, and the LIBS.TAB file, and what are their roles in locating the IBM Cognos Planning Analyst library files?
IBM Cognos Planning comprises two main components; Analyst, which can operate as a completely independent entity in its own right; and Contributor, which, while separate from Analyst, depends on models that are created in Analyst in order to function. (a third component, IBM Cognos Planning Manager, is typically used as a user interface for Analyst).
Most of the time, these two components can be considered as completely separate software packages. In modern versions of Cognos, both rely to some degree on another component - the Cognos Platform - to provide services such as authentication, web gateway hosting, and integration with other IBM Cognos Software products, including IBM Cognos Business Intelligence.
The Cognos Platform uses the Content Store database to hold data about users and the objects that they are permitted to access; and it provides a gateway, via the Cognos Connection web pages, through which the various Client components can access the Server-side components.
IBM Cognos Contributor uses the Planning Store database to store meta-data about the Planning environment - basically, everything you see in Contributor Administration, above the Application level (eg macros and Admin Links), plus information about what application and publish databases are a part of the environment. Contributor has no connection to, nor interest in, Analyst, except in four situations - A<>C D-Links, which can be used to transfer small amounts of data between Analyst and Contributor; Application Creation and Synchronize, where Contributor launches a background instance of Analyst, and reads the structure of the Analyst model, which it uses to create/update a Contributor model; Deployment, where Analyst is launched in the background to allow the import or export of Analyst Libraries; and to provide a database location where the filesys.ini path can be recorded. It is this last relationship that is of importance in this case.
IBM Cognos Analyst uses Windows files and folders for data and metadata storage, and does not use external databases at all, other than to request the Filesys.ini path from Planning Store on launch. The Analyst models are stored in libraries, and the higher level structure identifying which libraries 'belong' to a given Analyst instance, and information on users and access levels, are stored in a set of higher level files (eg Libs.tab, UGR.tab, Logins.log, etc.). In order to determine which *.tab and *.log files describe the environment, Analyst uses the filesys.ini file, which defines the locations of those *.tab and *.log files.
NOTE - FILESYS.INI INDICATES TO ANALYST WHICH LIBS.TAB FILE TO USE. Filesys.ini does NOT itself contain information about the location of any libraries. The library locations are stored in LIBS.TAB.
Filesys.ini was, many versions ago, used to directly store data about the location of the sample libraries; however this information remains in that file only for backward compatibility reasons, and is not used by any recent versions of Analyst.
In a distributed environment, each instance of Analyst (eg Dev, Prod, UAT, etc.) should have its own UNC sharepoint. This is a Windows Share directory that contains three sub-directories - 'bin', 'samples', and vers. 'samples', as its name suggests, simply contains sample models and data; 'vers' contains version information used when installing/uninstalling or upgrading the environment; and 'bin' is where everything that defines the environment is to be found.
In the \\analystsharename\bin directory, you should find the Filesys.ini, LIBS.TAB, PADLOCKS.TAB and UGR.TAB, and the 'Locks' directory that contains logins.log and locks.log. This set of files defines an Analyst instance; An Analyst environment with multiple instances will have a separate share for each instance, each with its own set of Filesys.ini, LIBS.TAB, PADLOCKS.TAB and UGR.TAB, and a 'Locks' directory that contains logins.log and locks.log. (some .bak files may also be present; these are backups of their respective .tab files).
The actual file directories that contain the libraries themselves can be at any accessible shared location - they need not be in the same server, as long as Windows can resolve their UNC paths to an accessible location; The actual location of these library directories is stored in LIBS.TAB (in an encrypted format). In many environments these libraries are located, for convenience, under the same shared path as the UNC connection point, but this is not mandatory.
The location of the active Filesys.ini is defined in Contributor Administration; However this file is NOT used by Contributor itself. The ONLY reason that it is defined via the Contributor client is that if the active Filesys.ini becomes corrupted or is deleted, it is no longer possible to launch Analyst - and so it would be impossible to change the configuration to use a different filesys.ini if the setting was inside the Analyst user interface. As a result, the decision was made to store this one piece of Analyst data in the Planning Store database, which is otherwise only used by Contributor.
So when you want to switch from one Analyst instance to another, this is what happens:
1) The Administrator opens Planning Administrator (CAC), and logs in - the log in is mediated by the Cognos platform, using the Authentication provider(s) defined in Content Store database via Cognos Configuration and Cognos Connection; if so configured, it may be automatic, based on your Windows login.
2) The CAC opens and loads the local Contributor information (everything in the left-hand pane of CAC) from the Planning Store database.
3) The Administrator goes to Tools>Update FileSys.Ini options, and modifies the path to point to the filesys.ini that defines the instance of Analyst he now wishes to use.
4) CAC checks the filesys.ini, and will present an error message if one is not present at the defined location, or if it contains a 'Instancelock' row that indicates that the filesys.ini is already associated with a different IBM Cognos Planning environment. To connect to a filesys.ini that has previously been associated to a different Planning Store, it is necessary to first delete the 'instancelock' row from the filesys.ini file.
5) The new location for the active Filesys.ini is saved to the P_SYSTEMOPTIONS table in the Planning Store database; and a new 'instancelock' row is written to filesys.ini, locking it to the current Planning Store. Any user accessing Analyst on a machine where this Planning Store is defined in Cognos Configuration will now be directed to the new Analyst instance.
6) A user opens Analyst - Their machine interrogates Cognos Configuration to determine the location of, and credentials for, Planning Store, and reads the filesys.ini path from that database.
7) Analyst reads the filesys.ini to determine the location of LIBS.TAB
8) Analyst decrypts and reads LIBS.TAB, and uses the contents of that file (plus user data from UGR.TAB) to populate the 'Maintain Libraries and Users' dialog, and to link to the available Analyst libraries.
So, in order for users to see the expected set of libraries in Analyst, the Planning Store defined in Cognos Configuration needs to contain the correct filesys.ini path (this Planning Store entry can be viewed or updated via CAC, at: Tools>Update FileSys.Ini options); And the filesys.ini defined in Planning Store/CAC needs to point to the correct LIBS.TAB file, which in turn needs to contain the correct library location information.
Changes to library paths, and the adding or removal of a library from Analyst, are made in the 'File'>'Maintain Libraries and Users' dialog in Analyst, which writes these changes to the LIBS.TAB file at the location indicated in filesys.ini. Use of the 'File'>'Maintain Libraries and Users' dialog is the only supported way to modify LIBS.TAB.
A change to Cognos Configuration that results in a change to the Planning Store database may, therefore, result in a change in which instance of Analyst is in use; And you can also change which instance of Analyst is in use by updating the currently configured Planning Store to point to a different instance of filesys.ini.
13 February 2020