Readme: FileNet Content Services (CS) Toolkit ================================================================== Please read this file before attempting to use the Content Services (CS) Application Program Interface (API) contained on the Content Services Toolkit CD. DISCLAIMER: FileNet provides programming examples in the CS Toolkit for illustration only, without warranty either expressed or implied, including, but not limited to, the implied warranties of merchantability and/or fitness for a particular purpose. The samples assume that you are familiar with the programming language being demonstrated and the tools used to create and debug procedures. SUPPORTED PLATFORMS AND COMPILERS ================================= The CS Toolkit is available for 32-bit Windows, HP-UX, and Sun Solaris platforms. The following platforms and compilers are certified for the CS Toolkit. Platform Compiler -------- -------- HP-UX 11i HP-UX Sun Solaris 9.0 Sun Solaris Windows 2000 (Intel) Microsoft Visual C++ 6.0x and higher Windows 2003 (Intel) Microsoft Visual C++ 6.0x and higher Windows XP (Intel) Microsoft Visual C++ 6.0x and higher Compiler Notes: * If your HP-UX products must run against the Oracle Edition of CS, they must run on HP-UX 11i. * If your Sun Solaris products must run against the Oracle Edition of CS, they must run on Sun Solaris 9. * For development with Visual C++, verify the following: - The srs_mapi.lib file must be in the Options, Project, Linker, and Input libraries. - The srsdevenv_msc and Windows defines must exist in the Project options. - The Options, Directories, Include, and Library file paths must point to the location of the CS Toolkit directory. - The spi.h, spi_sts.h, spi_obj.h, and spi_attr.h header files must be listed as include files. * CS clients are certified for Windows XP, Windows 2000 and Windows 2003. * If you use another compiler, you must use a WINDOWS (#) define. Make sure you compile on byte-aligned boundaries when using the CS include files. Search data structures, especially, are expected to be aligned on byte boundaries. CS TOOLKIT DIRECTORY AND FOLDER STRUCTURES BY PLATFORM ========================================================= -------------------------------------- Windows CS Toolkit Folder Structure -------------------------------------- For Windows, the CS Toolkit CD contains the following folders: \docs Contains CS Toolkit documentation. \include Contains the FileNet header files. \lib Contains the FileNet library files. \source Contains the sample code files and the batch file or makefile necessary to build them. --------------------------------------- HP-UX CS Toolkit Directory Structure --------------------------------------- For HP-UX, the CS Toolkit CD contains the following directories: /docs CS Toolkit documentation. /examples Contains the sample code files and the makefile necessary to build them. /include Contains the FileNet header files. /lib Contains the FileNet library files. ------------------------------------------ Sun Solaris CS Toolkit Directory Structure ------------------------------------------ For Sun Solaris, the CS Toolkit CD contains the following directories: /docs CS Toolkit documentation. /examples Contains the sample code files and the makefile necessary to build them. /include Contains the FileNet header files. /lib Contains the FileNet library files. CS TOOLKIT INSTALLATION INSTRUCTIONS ======================================= Copy the CS Toolkit install files from the CD to a particular build location. Notes for All Platforms ======================= Programs written to use the CS API must take into account the following: * Custom applications written to both the SPI SDK and Desktop/Web Services Toolkit must be compiled with the following compatible versions: - SPI SDK v.5.2.0 and Desktop/Web Services Toolkit v.3.2.0 - SPI SDK v.5.3.0 and Desktop/Web Services Toolkit v.3.3.0 - SPI SDK v.5.4.0 and Desktop/Web Services Toolkit v.3.3.0 - SPI SDK v.5.5.0 and Desktop/Web Services Toolkit v.4.0.0 * The Content Services API needs at least a 32K stack in addition to program requirements. * After installing the CS Toolkit, edit the makefile as follows: - Set the appropriate variable to point to the correct location of the C include files and the CS Toolkit include files. - Set the appropriate variable to point to the correct location of the FileNet libraries and compiler libraries for the appropriate compiler. - If not already set in the make file, set the appropriate compiler, link, and debug flags. * The Content Services API Manual now documents case-insensitive relational operators. Because Microsoft SQL Server must be configured as case-insensitive, the case-insensitive operators will have no affect on these databases. However, under Oracle (which is case-sensitive), using the case-insensitive operators will allow your applications to behave the same regardless of the database type. If you want your application to support case-sensitive relational search operators under Oracle, you can use the case-sensitive operators listed below. Remember, if you use these operators, your application will behave differently when searching a library system that uses a Microsoft SQL Server database. - SPI_RELOP_EQ - SPI_RELOP_GT - SPI_RELOP_LT - SPI_RELOP_NE - SPI_RELOP_GE - SPI_RELOP_LE - SPI_RELOP_LK - SPI_RELOP_NL * SPI_SYS_ITEM_DEL_ACCESS should not be set to anything other than SPI_ACCESS_OWNER_S, SPI_ACCESS_ADMIN_S, SPI_ITEM_DEL_ACCESS_DEFAULT_S, or blank. Otherwise, it will return SPI_STS_BAD_PARAMETER. Platform-specific Notes ======================= The following subtopics provide platform-specific information. Refer to the Content Services API Manual for further information. ---------------------------------------- Windows Notes ---------------------------------------- The CS Toolkit for Windows supports 32-bit Windows only, not 16-bit. Windows 95 is no longer supported. You must use the Microsoft Visual C++ 6.0 or higher compiler; previous versions are not supported. The 32-bit Windows CS Client Library Files are required to build applications using the CS Toolkit for Windows. For details about certified database client software required (e.g., ODBC, MDAC, etc.), see the CS server documentation in the \documentation directory on the Content Services Admin Tools CD. To install the CS Client Library Files: 1. Insert the FileNet Content Services Admin Tools CD into a drive on the application development client. 2. Run the following setup program: :\Client.Lib\Win32\English\Setup.exe Windows programs written to use the CS API must take into account the following: * For console-mode applications: Each Win32 console-mode application must call SetFileApisToOEM() as an indicator to the CS API that data will be in the OEM code page and must be converted to ANSI. If you want to handle translation, you need not call this but ALL data passed to the CS API must be in ANSI. Windows-based applications do not need to do this, as Win32 file APIs use the ANSI codepage by default. Microsoft offers Win32 developers three new functions to control this: SetFileApisToOEM, SetFileApisToANSI and AreFileApisANSI. You must add the following lines to console-mode applications: #include #include and once, before any file API functions are used: SetFileApisToOEM(); -------------------------------------------------------------------- HP-UX Specific Notes -------------------------------------------------------------------- The CS Client Library Files for HP-UX are required to build applications using the CS Toolkit for HP-UX. To install them: 1. Insert the FileNet Content Services Admin Tools CD into a drive on the application development client. 2. Run the following install program: /Client.Lib/HPUX/install For the client programs you build, make sure the following is true for the runtime environment: [Oracle databases]: * All client machines must have a tnsnames.ora file. The tnsnames.ora file must reflect the HP-UX server platform. You can copy (and edit) the tnsnames.ora file to the client machine from a library system server (any additional Storage Manager server) or use the Net8 Easy Config tool on a Windows PC and then FTP the file to the $ORACLE_HOME/network/admin directory on the UNIX client. (In an X-Windows UNIX environment, you can also use the netasst utility for this task.) To access library systems from your client applications, you must do the following: a.) Install the Oracle client software for UNIX. See the Oracle edition of the Content Services Installation Guide for the HP-UX platform. b.) Create a "filenet" user on each of the client machines. See the Content Services Installation documentation. The tnsnames.ora file on the library system servers is located in the /network/admin directory. All clients must have Read permissions to this tnsnames.ora file, and at least Execute permissions on the "filenet" user's home directory. c.) Set the ORACLE environment variables necessary on the clients, as described in the Content Services Installation documentation. * The SHLIB_PATH environment variable must be set to the directory containing the CS Client Library Files that you installed. * Make sure the following are appended to your $SHLIB_PATH environment variable: - The $ORACLE_HOME/lib directory (install location of your Oracle libraries directory). * To compile the Toolkit example, you must set the $LPATH environment variable to: /usr/lib:$SHLIB_PATH -------------------------------------------------------------------- Sun Solaris Specific Notes -------------------------------------------------------------------- The CS Client Library Files for Sun Solaris are required to build applications using the CS Toolkit for Sun Solaris. To install them: 1. Insert the FileNet Content Services Admin Tools CD into a drive on the application development client. 2. Run the following install program: /Client.Lib/SOL/install For the client programs you build, make sure the following is true for the runtime environment: [Oracle databases]: * All client machines must have a tnsnames.ora file. The tnsnames.ora file must reflect the Sun Solaris server platform. You can copy (and edit) the tnsnames.ora file to the client machine from a library system server (any additional Storage Manager server) or use the Net8 Easy Config tool on a Windows PC and then FTP the file to the $ORACLE_HOME/network/admin directory on the UNIX client. (In an X-Windows UNIX environment, you can also use the netasst utility for this task.) To access library systems from your client applications, you must do the following: a.) Install the Oracle client software for UNIX. See the Oracle edition of the Content Services Installation Guide for the Sun Solaris platform. b.) Create a "filenet" user on each of the client machines. See the Content Services Installation documentation. The tnsnames.ora file on the library system servers is located in the /network/admin directory. All clients must have Read permissions to this tnsnames.ora file, and at least Execute permissions on the "filenet" user's home directory. c.) Set the ORACLE environment variables necessary on the clients, as described in the Content Services Installation documentation. * The LD_LIBRARY_PATH environment variable must be set to the directory containing the CS Client Library Files that you installed. * Make sure the following are appended to your $LD_LIBRARY_PATH environment variable: - The $ORACLE_HOME/lib directory (install location of your Oracle libraries directory). NEW FEATURES ============ * For new general features, see the "CS 5.5.0 Release Notes" available on the FileNet Worldwide Customer Support web site, http://www.css.filenet.com. FIXES SINCE CS 5.4.0 ========================= * For general fixes, see the "CS Release Notes" available on the FileNet Worldwide Customer Support web site, http://www.css.filenet.com. FIXES SINCE CS 5.3.0 ========================= * For general fixes, see the "CS Release Notes" available on the FileNet Worldwide Customer Support web site, http://www.css.filenet.com. FIXES SINCE CS 5.2.0 ========================= * As of the Content Services 5.2 Hot Fix Pack 3 release, the SPI_USER_DIR_SYNC and SPI_GROUP_DIR_SYNC properties have a tool type of 7 (index). FIXES SINCE IDMDS 5.1.x ========================= * For general fixes, see the "CS Release Notes" available on the FileNet Worldwide Customer Support web site, http://www.css.filenet.com. FIXES SINCE IDMDS 5.0 FCS ========================= The following have been fixed since the initial 5.0 FCS release of the IDMDS Toolkit: * If a query contains a TEXT property (such as the Comment properties SPI_ITEM_COMMENT or SPI_CA_COMMENT), and the search criteria contain multivalue custom properties used with any search operators other than SPI_RELOP_EQI (=), the TEXT field will be blank in each row of the search results. (FR11018) * If a query contains a multivalue custom property (MVCP) in the search criteria and it's used with the SPI_RELOP_NEI (not equal) relational operator, the search, as expected, will return objects with MVCP values that are not equal to the value searched on. However, the search fails to return expected objects that have blank values for the MVCP. (FR 11269) * If a non-administrative user attempts to add an "ownerless" or insufficiently "owned" generic Relationship object, the user will get a 16403 error (insufficient access) when spiObjectAdd is called on the object to add it to the library system. Administrators are exempt from the access check and so can add generic objects of any form, even "ownerless" objects. This may cause a relational integrity issue. (FR7191) FIXES SINCE IDMDS 4.3 ===================== The following have been fixed since the initial 4.3 release of the IDMDS Toolkit: * When you delete documents, the Storage Manager process is not releasing a small amount of memory back to the system. After 4000 deletes, we have found that approximately .5 Mb had not been released. (PER 973070008) * When you call spiObjectGet on the Version Checkout object, the API checks the User object's Access Level property for the user who checked out the document. If the access level is None, then an "insufficient access level" message is returned. In your application, you may wish to ignore the error return code. (973350009) * The join query feature for combined Item and Version searches does not return correct search results in content-only searches on Version objects (i.e., when there are no Version object properties specified in the Query structure). (PER 980060077) * The SPI_QRY_CSOPT_THESAURUS and SPI_QRY_CSOPT_VARIANT flags in the content search query structure are being ignored. Content searches will always use the thesaurus and variants file if they are present. (PER 971040019) * Performance of spiQueryCard calls against Keywords and multivalue custom properties has been significantly improved by reducing the number of associated database queries required. * In the MS SQL Server 7.0 environment, the IDMDS API now supports full 256-byte VARCHAR fields for item and version file names instead of the TEXT columns that were required previously. Therefore, you no longer have to use truncated file names for searching in this database environment. (This change will not affect Oracle databases, which already support searches on full 256-byte file names.) CURRENT NOTICES =============== For known problems or issues in CS 5.5.0, including those in the Toolkit, see the "CS 5.5.0 Release Notes" available on the FileNet Worldwide Customer Support web site, http://www.css.filenet.com.