ENOVIA Live
Collaboration™
V6R2011x
Installation Guide
Copyright and Trademark Information
©
Dassault Systèmes, 1994 - 2010
All rights reserved.
PROPRIETARY RIGHTS NOTICE: This documentation is proprietary property of Dassault Systèmes and its subsidiaries. This documentation shall be treated as confidential information and may only be used by employees or contractors with the Customer in accordance with the applicable Software
License Agreement.
Adaplet®, Compliance Connect®, DesignSync®, ENOVIA®, MatrixOne®, ProjectSync®, Synchronicity®, and Team Central® are registered trademarks of Dassault Systèmes.
ENOVIA Live Collaboration, ENOVIA Live Collaboration Business Process Services, ENOVIA Live Collaboration Server, ENOVIA Studio Modeling Platform, ENOVIA Studio Federation Toolkit, ENOVIA Studio Customization Toolkit, ENOVIA 3D Live, ENOVIA Engineering Central, ENOVIA
Library Central, ENOVIA Materials Compliance Central, ENOVIA Program Central, ENOVIA Sourcing Central, ENOVIA Specification Central, ENOVIA Supplier Central, ENOVIA Designer Central, ENOVIA Collaborative Interference Management, ENOVIA Semiconductor Accelerator for Team
Compliance, ENOVIA Aerospace and Defense Accelerator for Program Management, ENOVIA Apparel Accelerator for Design and Development, ENOVIA X-BOM Cost Analytics, ENOVIA X-BOM Manufacturing, ENOVIA Variant Configuration Central, ENOVIA Synchronicity DesignSync Data
Manager, IconMail, ImageIcon and Star Browser are trademarks of Dassault Systèmes.
Oracle® is a registered trademark of Oracle Corporation, Redwood City, California. DB2, AIX, and WebSphere are registered trademarks of IBM Corporation. WebLogic is a registered trademark of BEA Systems, Inc. Solaris, UltraSPARC, Java, JavaServer Pages, JDBC, and J2EE are registered
trademarks of Sun Microsystems, Inc. Windows XP and Internet Explorer are registered trademarks of Microsoft Corp. HP and HP-UX are registered trademarks of HP. All other product names and services identified throughout this book are recognized as trademarks, registered trademarks, or service
marks of their respective companies.
The documentation that accompanies ENOVIA products describes the applications as delivered by Dassault Systèmes. This documentation includes readme files, online help, user guides, and administrator guides. If changes are made to an application or to the underlying framework, Dassault Systèmes
cannot ensure the accuracy of this documentation. These changes include but are not limited to: changing onscreen text, adding or removing fields on a page, making changes to the administrative objects in the schema, adding new JSPs or changing existing JSPs, changing trigger programs, changing the
installation or login process, or changing the values in any properties file. For instructions on customizing the provided documentation, see the Business Process Services Administrator’s Guide.
Dassault Systèmes Enovia Corp.
900 Chelmsford Street
Lowell, MA 01851
Telephone 978.442.2500
Email: enovia.info@3ds.com
http://www.3ds.com
Additional Components
This product also includes additional components copyrighted by other third parties. The sections that follow provide license and copyright notices of these software components.
Apache
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative
Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity
authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control
systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense,
and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise
transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation
against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such
litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The
contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot
be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work
otherwise complies with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein
shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without
limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of
permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct,
indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or
losses), even if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such
obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting
any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend
that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations
under the License.
Apache Ant
=========================================================================
NOTICE file corresponding to the section 4 d of the Apache License, Version 2.0, in this case for the Apache Ant distribution.
=========================================================================
This product includes software developed by The Apache Software Foundation (http://www.apache.org/).
This product includes also software developed by :
- the W3C consortium (http://www.w3c.org) ,
- the SAX project (http://www.saxproject.org)
Please read the different LICENSE files present in the root directory of this distribution. [BELOW]
This license came from:
http://www.w3.org/Consortium/Legal/copyright-software-19980720
W3C® SOFTWARE NOTICE AND LICENSE
Copyright © 1994-2001 World Wide Web Consortium, <a href="http://www.w3.org/">World Wide Web Consortium</a>, (<a href= "http://www.lcs.mit.edu/">Massachusetts Institute of Technology</a>, <a href="http://www.inria.fr/">Institut National de Recherche en Informatique et en Automatique</
a>, <a href= "http://www.keio.ac.jp/">Keio University</a>). All Rights Reserved.
http://www.w3.org/Consortium/Legal/
This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, modify, and distribute this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including
modifications, that you make:
The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, a short notice of the following form (hypertext is preferred, text is permitted) should be used within the body of any redistributed or derivative code:
"Copyright © 1999-2004 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/"
Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT,
SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
This license came from: http://www.megginson.com/SAX/copying.html. However please note future versions of SAX may be covered under http://saxproject.org/?selected=pd
This page is now out of date -- see the new SAX site at http://www.saxproject.org/ for more up-to-date releases and other information. Please change your bookmarks.
SAX2 is Free!
I hereby abandon any property rights to SAX 2.0 (the Simple API for XML), and release all of the SAX 2.0 source code, compiled code, and documentation contained in this distribution into the Public Domain. SAX comes with NO WARRANTY or guarantee of fitness for any purpose.
David Megginson, david@megginson.com
Apache Axis
=========================================================================
NOTICE file corresponding to section 4(d) of the Apache License, Version 2.0, in this case for the Apache Axis distribution.
=========================================================================
This product includes software developed by The Apache Software Foundation (http://www.apache.org/).
Apache Tomcat
[under Apache License, Version 2.0 above]
Apache Servlet-API
[under Apache License, Version 2.0 above]
FTP
Copyright (c) 1983, 1985, 1989, 1993, 1994
The Regents of the University of California. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1.
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3.
All advertising materials mentioning features or use of this software must display the following acknowledgement:
This product includes software developed by the University of California, Berkeley and its contributors.
4.
Neither the name of the University nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAYOUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Copyright (c) 1997-1999 The Stanford SRP Authentication Project
All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
IN NO EVENT SHALL STANFORD BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER
Copyright 1990 by the Massachusetts Institute of Technology.
All Rights Reserved.
Export of this software from the United States of America may require a specific license from the United States Government. It is the responsibility of any person or organization contemplating export to obtain such a license before exporting.
WITHIN THAT CONSTRAINT, permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in
supporting documentation, and that the name of M.I.T. not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T. makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or
implied warranty.
Getline
Copyright (C) 1991, 1992, 1993 by Chris Thewalt (thewalt@ce.berkeley.edu)
Permission to use, copy, modify, and distribute this software for any purpose and without fee is hereby granted, provided that the above copyright notices appear in all copies and that both the copyright notice and this permission notice appear in supporting documentation. This software is provided "as is"
without express or implied warranty.
GifEncoder
GifEncoder - write out an image as a GIF
Transparency handling and variable bit size courtesy of Jack Palevich.
Copyright (C)1996,1998 by Jef Poskanzer <jef@acme.com>. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1.
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
ImageEncoder
ImageEncoder - abstract class for writing out an image
Copyright (C) 1996 by Jef Poskanzer <jef@acme.com>. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1.
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY
WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
JavaMail
Sun Microsystems, Inc.
Binary Code License Agreement
READ THE TERMS OF THIS AGREEMENT AND ANY PROVIDED SUPPLEMENTAL LICENSE TERMS (COLLECTIVELY "AGREEMENT") CAREFULLY BEFORE OPENING THE SOFTWARE MEDIA PACKAGE. BY OPENING THE SOFTWARE MEDIA PACKAGE, YOU AGREE TO
THE TERMS OF THIS AGREEMENT. IF YOU ARE ACCESSING THE SOFTWARE ELECTRONICALLY, INDICATE YOUR ACCEPTANCE OF THESE TERMS BY SELECTING THE "ACCEPT" BUTTON AT THE END OF THIS AGREEMENT. IF YOU DO NOT AGREE TO ALL THESE
TERMS, PROMPTLY RETURN THE UNUSED SOFTWARE TO YOUR PLACE OF PURCHASE FOR A REFUND OR, IF THE SOFTWARE IS ACCESSED ELECTRONICALLY, SELECT THE "DECLINE" BUTTON AT THE END OF THIS AGREEMENT.
1. LICENSE TO USE. Sun grants you a non-exclusive and non-transferable license for the internal use only of the accompanying software and documentation and any error corrections provided by Sun (collectively "Software"), by the number of users and the class of computer hardware for which the
corresponding fee has been paid.
2. RESTRICTIONS. Software is confidential and copyrighted. Title to Software and all associated intellectual property rights is retained by Sun and/or its licensors. Except as specifically authorized in any Supplemental License Terms, you may not make copies of Software, other than a single copy of
Software for archival purposes. Unless enforcement is prohibited by applicable law, you may not modify, decompile, or reverse engineer Software. You acknowledge that Software is not designed, licensed or intended for use in the design, construction, operation or maintenance of any nuclear facility. Sun
disclaims any express or implied warranty of fitness for such uses. No right, title or interest in or to any trademark, service mark, logo or trade name of Sun or its licensors is granted under this Agreement.
3. LIMITED WARRANTY. Sun warrants to you that for a period of ninety (90) days from the date of purchase, as evidenced by a copy of the receipt, the media on which Software is furnished (if any) will be free of defects in materials and workmanship under normal use. Except for the foregoing,
Software is provided "AS IS". Your exclusive remedy and Sun's entire liability under this limited warranty will be at Sun's option to replace Software media or refund the fee paid for Software.
4. DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
5. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES,
HOWEVER CAUSED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event will Sun's liability to you,
whether in contract, tort (including negligence), or otherwise, exceed the amount paid by you for Software under this Agreement. The foregoing limitations will apply even if the above stated warranty fails of its essential purpose.
6. Termination. This Agreement is effective until terminated. You may terminate this Agreement at any time by destroying all copies of Software. This Agreement will terminate immediately without notice from Sun if you fail to comply with any provision of this Agreement. Upon Termination, you
must destroy all copies of Software.
7. Export Regulations. All Software and technical data delivered under this Agreement are subject to US export control laws and may be subject to export or import regulations in other countries. You agree to comply strictly with all such laws and regulations and acknowledge that you have the
responsibility to obtain such licenses to export, re-export, or import as may be required after delivery to you.
8. U.S. Government Restricted Rights. If Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in Software and accompanying documentation will be only as set forth in this Agreement;
this is in accordance with 48 CFR 227.7201 through 227.7202-4 (for Department of Defense (DOD) acquisitions) and with 48 CFR 2.101 and 12.212 (for non-DOD acquisitions).
9. Governing Law. Any action related to this Agreement will be governed by California law and controlling U.S. federal law. No choice of law rules of any jurisdiction will apply.
10. Severability. If any provision of this Agreement is held to be unenforceable, this Agreement will remain in effect with the provision omitted, unless omission would frustrate the intent of the parties, in which case this Agreement will immediately terminate.
11. Integration. This Agreement is the entire agreement between you and Sun relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, representations and warranties and prevails over any conflicting or additional terms of any quote, order,
acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification of this Agreement will be binding, unless in writing and signed by an authorized representative of each party.
JAVAMAILTM, VERSION 1.3.1
SUPPLEMENTAL LICENSE TERMS
These supplemental license terms ("Supplemental Terms") add to or modify the terms of the Binary Code License Agreement (collectively, the "Agreement"). Capitalized terms not defined in these Supplemental Terms shall have the same meanings ascribed to them in the Agreement. These Supplemental
Terms shall supersede any inconsistent or conflicting terms in the Agreement, or in any license contained within the Software.
1. Software Internal Use and Development License Grant. Subject to the terms and conditions of this Agreement, including, but not limited to Section 3 (Java(TM) Technology Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable, limited license to reproduce
internally and use internally the binary form of the Software, complete and unmodified, for the sole purpose of designing, developing and testing your Java applets and applications ("Programs").
2. License to Distribute Software.* Subject to the terms and conditions of this Agreement, including, but not limited to Section 3 (Java (TM) Technology Restrictions) of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable, limited license to reproduce and distribute the Software
in binary code form only, provided that (i) you distribute the Software complete and unmodified and only bundled as part of, and for the sole purpose of running, your Java applets or applications ("Programs"), (ii) the Programs add significant and primary functionality to the Software, (iii) you do not
distribute additional software intended to replace any component(s) of the Software, (iv) you do not remove or alter any proprietary legends or notices contained in the Software, (v) you only distribute the Software subject to a license agreement that protects Sun's interests consistent with the terms
contained in this Agreement, and (vi) you agree to defend and indemnify Sun and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results
from the use or distribution of any and all Programs and/or Software.
3. Java Technology Restrictions.* You may not modify the Java Platform Interface ("JPI", identified as classes contained within the "java" package or any subpackages of the "java" package), by creating additional classes within the JPI or otherwise causing the addition to or modification of the classes in
the JPI. In the event that you create an additional class and associated API(s) which (i) extends the functionality of the Java platform, and (ii) is exposed to third party software developers for the purpose of developing additional software which invokes such additional API, you must promptly publish
broadly an accurate specification for such API for free use by all developers. You may not create, or authorize your licensees to create additional classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun" or similar convention as specified by Sun in any naming convention
designation.
4. Trademarks and Logos. You acknowledge and agree as between you and Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, STAROFFICE, STARPORTAL and iPLANET-related
trademarks, service marks, logos and other brand designations ("Sun Marks"), and you agree to comply with the Sun Trademark and Logo Usage Requirements currently located at http://www.sun.com/policies/trademarks. Any use you make of the Sun Marks inures to Sun's benefit.
5. Source Code. Software may contain source code that is provided solely for reference purposes pursuant to the terms of this Agreement. Source code may not be redistributed unless expressly provided for in this Agreement.
6. Termination for Infringement. Either party may terminate this Agreement immediately should any Software become, or in either party's opinion be likely to become, the subject of a claim of infringement of any intellectual property right.
For inquiries please contact: Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A
/(LFI#132726/Form ID#011801)/
Jakarta POI
[under Apache License, Version 2.0 above]
JDK
Sun Microsystems, Inc. Binary Code License Agreement
for the JAVA 2 PLATFORM STANDARD EDITION DEVELOPMENT KIT 5.0
SUN MICROSYSTEMS, INC. ("SUN") IS WILLING TO LICENSE THE SOFTWARE IDENTIFIED BELOW TO YOU ONLY UPON THE CONDITION THAT YOU ACCEPT ALL OF THE TERMS CONTAINED IN THIS BINARY CODE LICENSE AGREEMENT AND SUPPLEMENTAL
LICENSE TERMS (COLLECTIVELY "AGREEMENT"). PLEASE READ THE AGREEMENT CAREFULLY. BY DOWNLOADING OR INSTALLING THIS SOFTWARE, YOU ACCEPT THE TERMS OF THE AGREEMENT. INDICATE ACCEPTANCE BY SELECTING THE "ACCEPT"
BUTTON AT THE BOTTOM OF THE AGREEMENT. IF YOU ARE NOT WILLING TO BE BOUND BY ALL THE TERMS, SELECT THE "DECLINE" BUTTON AT THE BOTTOM OF THE AGREEMENT AND THE DOWNLOAD OR INSTALL PROCESS WILL NOT CONTINUE.
1. DEFINITIONS. "Software" means the identified above in binary form, any other machine readable materials (including, but not limited to, libraries, source files, header files, and data files), any updates or error corrections provided by Sun, and any user manuals, programming guides and other
documentation provided to you by Sun under this Agreement. "Programs" mean Java applets and applications intended to run on the Java 2 Platform Standard Edition (J2SE platform) platform on Java-enabled general purpose desktop computers and servers.
2. LICENSE TO USE. Subject to the terms and conditions of this Agreement, including, but not limited to the Java Technology Restrictions of the Supplemental License Terms, Sun grants you a non-exclusive, non-transferable, limited license without license fees to reproduce and use internally Software
complete and unmodified for the sole purpose of running Programs. Additional licenses for developers and/or publishers are granted in the Supplemental License Terms.
3. RESTRICTIONS. Software is confidential and copyrighted. Title to Software and all associated intellectual property rights is retained by Sun and/or its licensors. Unless enforcement is prohibited by applicable law, you may not modify, decompile, or reverse engineer Software. You acknowledge that
Licensed Software is not designed or intended for use in the design, construction, operation or maintenance of any nuclear facility. Sun Microsystems, Inc. disclaims any express or implied warranty of fitness for such uses. No right, title or interest in or to any trademark, service mark, logo or trade name
of Sun or its licensors is granted under this Agreement. Additional restrictions for developers and/or publishers licenses are set forth in the Supplemental License Terms.
4. LIMITED WARRANTY. Sun warrants to you that for a period of ninety (90) days from the date of purchase, as evidenced by a copy of the receipt, the media on which Software is furnished (if any) will be free of defects in materials and workmanship under normal use. Except for the foregoing,
Software is provided "AS IS". Your exclusive remedy and Sun's entire liability under this limited warranty will be at Sun's option to replace Software media or refund the fee paid for Software. Any implied warranties on the Software are limited to 90 days. Some states do not allow limitations on duration
of an implied warranty, so the above may not apply to you. This limited warranty gives you specific legal rights. You may have others, which vary from state to state.
5. DISCLAIMER OF WARRANTY. UNLESS SPECIFIED IN THIS AGREEMENT, ALL EXPRESS OR IMPLIED CONDITIONS, REPRESENTATIONS AND WARRANTIES, INCLUDING ANY IMPLIED WARRANTY OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR
NON-INFRINGEMENT ARE DISCLAIMED, EXCEPT TO THE EXTENT THAT THESE DISCLAIMERS ARE HELD TO BE LEGALLY INVALID.
6. LIMITATION OF LIABILITY. TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL SUN OR ITS LICENSORS BE LIABLE FOR ANY LOST REVENUE, PROFIT OR DATA, OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL OR PUNITIVE DAMAGES,
HOWEVER CAUSED REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF OR RELATED TO THE USE OF OR INABILITY TO USE SOFTWARE, EVEN IF SUN HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In no event will Sun's liability to you,
whether in contract, tort (including negligence), or otherwise, exceed the amount paid by you for Software under this Agreement. The foregoing limitations will apply even if the above stated warranty fails of its essential purpose. Some states do not allow the exclusion of incidental or consequential
damages, so some of the terms above may not be applicable to you.
7. TERMINATION. This Agreement is effective until terminated. You may terminate this Agreement at any time by destroying all copies of Software. This Agreement will terminate immediately without notice from Sun if you fail to comply with any provision of this Agreement. Either party may
terminate this Agreement immediately should any Software become, or in either party's opinion be likely to become, the subject of a claim of infringement of any intellectual property right. Upon Termination, you must destroy all copies of Software.
8. EXPORT REGULATIONS. All Software and technical data delivered under this Agreement are subject to US export control laws and may be subject to export or import regulations in other countries. You agree to comply strictly with all such laws and regulations and acknowledge that you have the
responsibility to obtain such licenses to export, re-export, or import as may be required after delivery to you.
9. TRADEMARKS AND LOGOS. You acknowledge and agree as between you and Sun that Sun owns the SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANET trademarks and all SUN, SOLARIS, JAVA, JINI, FORTE, and iPLANET-related trademarks, service marks, logos and other brand designations
("Sun Marks"), and you agree to comply with the Sun Trademark and Logo Usage Requirements currently located at http://www.sun.com/policies/trademarks. Any use you make of the Sun Marks inures to Sun's benefit.
10. U.S. GOVERNMENT RESTRICTED RIGHTS. If Software is being acquired by or on behalf of the U.S. Government or by a U.S. Government prime contractor or subcontractor (at any tier), then the Government's rights in Software and accompanying documentation will be only as set forth in this
Agreement; this is in accordance with 48 CFR 227.7201 through 227.7202-4 (for Department of Defense (DOD) acquisitions) and with 48 CFR 2.101 and 12.212 (for non-DOD acquisitions).
11. GOVERNING LAW. Any action related to this Agreement will be governed by California law and controlling U.S. federal law. No choice of law rules of any jurisdiction will apply.
12. SEVERABILITY. If any provision of this Agreement is held to be unenforceable, this Agreement will remain in effect with the provision omitted, unless omission would frustrate the intent of the parties, in which case this Agreement will immediately terminate.
13. INTEGRATION. This Agreement is the entire agreement between you and Sun relating to its subject matter. It supersedes all prior or contemporaneous oral or written communications, proposals, representations and warranties and prevails over any conflicting or additional terms of any quote, order,
acknowledgment, or other communication between the parties relating to its subject matter during the term of this Agreement. No modification of this Agreement will be binding, unless in writing and signed by an authorized representative of each party.
SUPPLEMENTAL LICENSE TERMS
These Supplemental License Terms add to or modify the terms of the Binary Code License Agreement. Capitalized terms not defined in these Supplemental Terms shall have the same meanings ascribed to them in the Binary Code License Agreement . These Supplemental Terms shall supersede any
inconsistent or conflicting terms in the Binary Code License Agreement, or in any license contained within the Software.
A. Software Internal Use and Development License Grant. Subject to the terms and conditions of this Agreement and restrictions and exceptions set forth in the Software "README" file, including, but not limited to the Java Technology Restrictions of these Supplemental Terms, Sun grants you a
non-exclusive, non-transferable, limited license without fees to reproduce internally and use internally the Software complete and unmodified for the purpose of designing, developing, and testing your Programs.
B. License to Distribute Software. Subject to the terms and conditions of this Agreement and restrictions and exceptions set forth in the Software README file, including, but not limited to the Java Technology Restrictions of these Supplemental Terms, Sun grants you a non-exclusive, non-transferable,
limited license without fees to reproduce and distribute the Software, provided that (i) you distribute the Software complete and unmodified and only bundled as part of, and for the sole purpose of running, your Programs, (ii) the Programs add significant and primary functionality to the Software, (iii) you
do not distribute additional software intended to replace any component(s) of the Software, (iv) you do not remove or alter any proprietary legends or notices contained in the Software, (v) you only distribute the Software subject to a license agreement that protects Sun's interests consistent with the terms
contained in this Agreement, and (vi) you agree to defend and indemnify Sun and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results
from the use or distribution of any and all Programs and/or Software.
C. License to Distribute Redistributables. Subject to the terms and conditions of this Agreement and restrictions and exceptions set forth in the Software README file, including but not limited to the Java Technology Restrictions of these Supplemental Terms, Sun grants you a non-exclusive,
non-transferable, limited license without fees to reproduce and distribute those files specifically identified as redistributable in the Software "README" file ("Redistributables") provided that: (i) you distribute the Redistributables complete and unmodified, and only bundled as part of Programs, (ii) the
Programs add significant and primary functionality to the Redistributables, (iii) you do not distribute additional software intended to supersede any component(s) of the Redistributables (unless otherwise specified in the applicable README file), (iv) you do not remove or alter any proprietary legends or
notices contained in or on the Redistributables, (v) you only distribute the Redistributables pursuant to a license agreement that protects Sun's interests consistent with the terms contained in the Agreement, (vi) you agree to defend and indemnify Sun and its licensors from and against any damages, costs,
liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of any and all Programs and/or Software.
D. Java Technology Restrictions. You may not create, modify, or change the behavior of, or authorize your licensees to create, modify, or change the behavior of, classes, interfaces, or subpackages that are in any way identified as "java", "javax", "sun" or similar convention as specified by Sun in any
naming convention designation.
E. Distribution by Publishers. This section pertains to your distribution of the Software with your printed book or magazine (as those terms are commonly used in the industry) relating to Java technology ("Publication"). Subject to and conditioned upon your compliance with the restrictions and obligations
contained in the Agreement, in addition to the license granted in Paragraph 1 above, Sun hereby grants to you a non-exclusive, nontransferable limited right to reproduce complete and unmodified copies of the Software on electronic media (the "Media") for the sole purpose of inclusion and distribution
with your Publication(s), subject to the following terms: (i) You may not distribute the Software on a stand-alone basis; it must be distributed with your Publication(s); (ii) You are responsible for downloading the Software from the applicable Sun web site; (iii) You must refer to the Software as JavaTM 2
Platform Standard Edition Development Kit 5.0; (iv) The Software must be reproduced in its entirety and without any modification whatsoever (including, without limitation, the Binary Code License and Supplemental License Terms accompanying the Software and proprietary rights notices contained in
the Software); (v) The Media label shall include the following information: Copyright 2004, Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Sun, Sun Microsystems, the Sun logo, Solaris, Java, the Java Coffee Cup logo, J2SE , and all trademarks and logos based on Java are
trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. This information must be placed on the Media label in such a manner as to only apply to the Sun Software; (vi) You must clearly identify the Software as Sun's product on the Media holder or Media label, and
you may not state or imply that Sun is responsible for any third-party software contained on the Media; (vii) You may not include any third party software on the Media which is intended to be a replacement or substitute for the Software; (viii) You shall indemnify Sun for all damages arising from your
failure to comply with the requirements of this Agreement. In addition, you shall defend, at your expense, any and all claims brought against Sun by third parties, and shall pay all damages awarded by a court of competent jurisdiction, or such settlement amount negotiated by you, arising out of or in
connection with your use, reproduction or distribution of the Software and/or the Publication. Your obligation to provide indemnification under this section shall arise provided that Sun: (i) provides you prompt notice of the claim; (ii) gives you sole control of the defense and settlement of the claim; (iii)
provides you, at your expense, with all available information, assistance and authority to defend; and (iv) has not compromised or settled such claim without your prior written consent; and (ix) You shall provide Sun with a written notice for each Publication; such notice shall include the following
information: (1) title of Publication, (2) author(s), (3) date of Publication, and (4) ISBN or ISSN numbers. Such notice shall be sent to Sun Microsystems, Inc., 4150 Network Circle, M/S USCA12-110, Santa Clara, California 95054, U.S.A , Attention: Contracts Administration.
F. Source Code. Software may contain source code that, unless expressly licensed for other purposes, is provided solely for reference purposes pursuant to the terms of this Agreement. Source code may not be redistributed unless expressly provided for in this Agreement.
G. Third Party Code. Additional copyright notices and license terms applicable to portions of the Software are set forth in the THIRDPARTYLICENSEREADME.txt file. In addition to any terms and conditions of any third party opensource/freeware license identified in the
THIRDPARTYLICENSEREADME.txt file, the disclaimer of warranty and limitation of liability provisions in paragraphs 5 and 6 of the Binary Code License Agreement shall apply to all Software in this distribution.
For inquiries please contact: Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A.
(LFI#141623/Form ID#011801)
DO NOT TRANSLATE OR LOCALIZE.
The following software may be included in this product: CS CodeViewer v1.0;
Use of any of this software is governed by the terms of the license below:
Copyright 1999 by CoolServlets.com.
Any errors or suggested improvements to this class can be reported as instructed on CoolServlets.com. We hope you enjoy this program... your comments will encourage further development!
This software is distributed under the terms of the BSD License. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither name of CoolServlets.com nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY COOLSERVLETS.COM AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE."
The following software may be included in this product: Crimson v1.1.1 ; Use of any of this software is governed by the terms of the license below:
The Apache Software License, Version 1.1
Copyright (c) 1999-2000 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and
wherever such third-party acknowledgments normally appear.
4. The names "Crimson" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
====================================================================
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation,
please see <http://www.apache.org/>.
The following software may be included in this product: Xalan J2;
Use of any of this software is governed by the terms of the license below:
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
1. Definitions.
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by
contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
"Source" form shall mean the preferred form for making modifications,including but not limited to software source code, documentation source, and configuration files.
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative
Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity
authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control
systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense,
and distribute the Work and such Derivative Works in Source or Object form.
3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise
transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation
against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such
litigation is filed.
4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
(a) You must give any other recipients of the Work or Derivative Works a copy of this License; and
(b) You must cause any modified files to carry prominent notices stating that You changed the files; and
(c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
(d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one
of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The
contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot
be construed as modifying the License.
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work
otherwise complies with the conditions stated in this License.
5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein
shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without
limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of
permissions under this License.
8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct,
indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or
losses), even if such Contributor has been advised of the possibility of such damages.
9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such
obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting
any such warranty or additional liability.
END OF TERMS AND CONDITIONS
APPENDIX: How to apply the Apache License to your work.
To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend
that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives.
Copyright [yyyy] [name of copyright owner]
Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations
under the License.
The following software may be included in this product: NSIS 1.0j; Use of any of this software is governed by the terms of the license below:
Copyright (C) 1999-2000 Nullsoft, Inc.
This software is provided 'as-is', without any express or implied warranty. In no event will the authors be held liable for any damages arising from the use of this software. Permission is granted to anyone to use this software for any purpose, including commercial applications, and to alter it and redistribute
it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not claim that you wrote the original software. If you use this software in a product, an acknowledgment in the product documentation would be appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.Justin Frankel justin@nullsoft.com"
Some Portions licensed from IBM are available at: http://oss.software.ibm.com/icu4j/
Portions Copyright Eastman Kodak Company 1992
Lucida is a registered trademark or trademark of Bigelow & Holmes in the U.S. and other countries.
Portions licensed from Taligent, Inc.
The following software may be included in this product:IAIK PKCS Wrapper; Use of any of this software is governed by the terms of the license below:
Copyright (c) 2002 Graz University of Technology. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:
"This product includes software developed by IAIK of Graz University of Technology."
Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
4. The names "Graz University of Technology" and "IAIK of Graz University of Technology" must not be used to endorse or promote products derived from this software without prior written permission.
5. Products derived from this software may not be called "IAIK PKCS Wrapper", nor may "IAIK" appear in their name, without prior written permission of Graz University of Technology.
THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE LICENSOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The following software may be included in this product: Document Object Model (DOM) v. Level 3; Use of any of this software is governed by the terms of the license below:
W3Cýý SOFTWARE NOTICE AND LICENSE
http://www.w3.org/Consortium/Legal/2002/copyright-software-20021231
This work (and included software, documentation such as READMEs, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following
terms and conditions.
Permission to copy, modify, and distribute this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including modifications:
1.The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
2.Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, the W3C Software Short Notice should be included (hypertext is preferred, text is permitted) within the body of any redistributed or derivative code.
3.Notice of any changes or modifications to the files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
This formulation of W3C's notice and license became active on December 31 2002.
This version removes the copyright ownership notice such that this license can be used with materials other than those owned by the W3C, reflects that ERCIM is now a host of the W3C, includes references to this specific dated version of the license, and removes the ambiguous grant of "use". Otherwise,
this version is the same as the previous version and is written so as to preserve the Free Software Foundation's assessment of GPL compatibility and OSI's certification under the Open Source Definition. Please see our Copyright FAQ for common questions about using materials from our site, including
specific terms and conditions for packages like libwww, Amaya, and Jigsaw. Other questions about this notice can be directed to site-policy@w3.org.
The following software may be included in this product: Xalan, Xerces; Use of any of this software is governed by the terms of the license below:
The Apache Software License, Version 1.1
Copyright (c) 1999-2003 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and
wherever such third-party acknowledgments normally appear.
4. The names "Xerces" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
====================================================================
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 1999, International Business Machines, Inc., http://www.ibm.com. For more information on the Apache Software Foundation,
please see <http://www.apache.org/>.
The following software may be included in this product: W3C XML Conformance Test Suites v. 20020606; Use of any of this software is governed by the terms of the license below:
W3Cýý SOFTWARE NOTICE AND LICENSE
Copyright ýý 1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/
This W3C work (including software, documents, or other related items) is being provided by the copyright holders under the following license. By obtaining, using and/or copying this work, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, modify, and distribute this software and its documentation, with or without modification, for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the software and documentation or portions thereof, including
modifications, that you make:
1. The full text of this NOTICE in a location viewable to users of the redistributed or derivative work.
2. Any pre-existing intellectual property disclaimers, notices, or terms and conditions. If none exist, a short notice of the following form (hypertext is preferred, text is permitted) should be used within the body of any redistributed or derivative code: "Copyright ýý [$date-of-software] World Wide Web
Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved. http://www.w3.org/Consortium/Legal/"
3. Notice of any changes or modifications to the W3C files, including the date changes were made. (We recommend you provide URIs to the location from which the code is derived.)
THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY
PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to the software without specific, written prior permission. Title to copyright in this software and any associated documentation will at all times remain with copyright holders.
This formulation of W3C's notice and license became active on August 14 1998 so as to improve compatibility with GPL. This version ensures that W3C software licensing terms are no more restrictive than GPL and consequently W3C software may be distributed in GPL packages. See the older
formulation for the policy prior to this date. Please see our Copyright FAQ for common questions about using materials from our site, including specific terms and conditions for packages like libwww, Amaya, and Jigsaw. Other questions about this notice can be directed to site-policy@w3.org.
The following software may be included in this product: W3C XML Schema Test Collection v. 1.16.2; Use of any of this software is governed by the terms of the license below:
W3Cýýýý DOCUMENT NOTICE AND LICENSE
Copyright ýýýý 1994-2002 World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights Reserved.
http://www.w3.org/Consortium/Legal/
Public documents on the W3C site are provided by the copyright holders under the following license. The software or Document Type Definitions (DTDs) associated with W3C specifications are governed by the Software Notice. By using and/or copying this document, or the W3C document from which
this statement is linked, you (the licensee) agree that you have read, understood, and will comply with the following terms and conditions:
Permission to use, copy, and distribute the contents of this document, or the W3C document from which this statement is linked, in any medium for any purpose and without fee or royalty is hereby granted, provided that you include the following on ALL copies of the document, or portions thereof, that
you use:
1. A link or URL to the original W3C document.
2. The pre-existing copyright notice of the original author, or if it doesn't exist, a notice of the form: "Copyright ýýýý [$date-of-document] World Wide Web Consortium, (Massachusetts Institute of Technology, Institut National de Recherche en Informatique et en Automatique, Keio University). All Rights
Reserved. http://www.w3.org/Consortium/Legal/" (Hypertext is preferred, but a textual representation is permitted.)
3. If it exists, the STATUS of the W3C document.
When space permits, inclusion of the full text of this NOTICE should be provided. We request that authorship attribution be provided in any software, documents, or other items or products that you create pursuant to the implementation of the contents of this document, or any portion thereof.
No right to create modifications or derivatives of W3C documents is granted pursuant to this license. However, if additional requirements (documented in the Copyright FAQ) are satisfied, the right to create modifications or derivatives is sometimes granted by the W3C to individuals complying with those
requirements.
THIS DOCUMENT IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE,
NON-INFRINGEMENT, OR TITLE; THAT THE CONTENTS OF THE DOCUMENT ARE SUITABLE FOR ANY PURPOSE; NOR THAT THE IMPLEMENTATION OF SUCH CONTENTS WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER
RIGHTS.
COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE DOCUMENT OR THE PERFORMANCE OR IMPLEMENTATION OF THE CONTENTS THEREOF.
The name and trademarks of copyright holders may NOT be used in advertising or publicity pertaining to this document or its contents without specific, written prior permission. Title to copyright in this document will at all times remain with copyright holders.
---------------------------------------------------------------------------This formulation of W3C's notice and license became active on April 05 1999 so as to account for the treatment of DTDs, schema's and bindings. See the older formulation for the policy prior to this date. Please see our Copyright FAQ for common questions about using materials from our site, including
specific terms and conditions for packages like libwww, Amaya, and Jigsaw. Other questions about this notice can be directed to site-policy@w3.org. webmaster (last updated by reagle on 1999/04/99.)
The following software may be included in this product: Mesa 3-D graphics library v. 5; Use of any of this software is governed by the terms of the license below:
core Mesa code include/GL/gl.h
GLX driver
include/GL/glx.h
Ext registry
include/GL/glext.h
Brian Paul
Brian Paul
SGI
Mesa
Mesa
SGI Free B
include/GL/glxext.h
Mesa license:
The Mesa distribution consists of several components. Different copyrights and licenses apply to different components. For example, GLUT is copyrighted by Mark Kilgard, some demo programs are copyrighted by SGI, some of the Mesa device drivers are copyrighted by their authors. See below for a list
of Mesa's components and the copyright/license for each.
The core Mesa library is licensed according to the terms of the XFree86 copyright (an MIT-style license). This allows integration with the XFree86/DRI project. Unless otherwise stated, the Mesa source code and documentation is licensed as follows:
Copyright (C) 1999-2003 Brian Paul All Rights Reserved.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT
SHALL BRIAN PAUL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
SGI Free Software Licence B:
, or is under common control with Recipient. For purposes of this definition, "control" of an entity means (a) the power, direct or indirect, to direct or manage such entity, or (b) ownership of fifty percent (50%) or more of the outstanding shares or beneficial ownership of such entity.
1.12."Recipient Patents" means patent claims Licensable by a Recipient that are infringed by the use or sale of Original Code or any Modifications provided by SGI, or any combination thereof.
1.13."SGI" means Silicon Graphics, Inc.
1.14."SGI Patents" means patent claims Licensable by SGI other than the Licensed Patents.
2.License Grant and Restrictions.
2.1.SGI License Grant. Subject to the terms of this License and any third party intellectual property claims, for the duration of intellectual property protections inherent in the Original Code, SGI hereby grants Recipient a worldwide, royalty-free, non-exclusive license, to do the following: (i) under
copyrights Licensable by SGI, to reproduce, distribute, create derivative
The following software may be included in this product: Byte Code Engineering Library (BCEL) v. 5; Use of any of this software is governed by the terms of the license below:
Apache Software License
The Apache Software License, Version 1.1
Copyright (c) 2001 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment: "This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and
wherever such third-party acknowledgments normally appear.
4. The names "Apache" and "Apache Software Foundation" and "Apache BCEL" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
5. Products derived from this software may not be called "Apache", "Apache BCEL", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see <http://www.apache.org/>.
The following software may be included in this product: Regexp, Regular Expression Package v. 1.2; Use of any of this software is governed by the terms of the license below:
The Apache Software License, Version 1.1
Copyright (c) 2001 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the
distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:
"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and wherever such third-party acknowledgments normally appear.
4. The names "Apache" and "Apache Software Foundation" and "Apache Turbine" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
5. Products derived from this software may not be called "Apache", "Apache Turbine", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation. For more information on the Apache Software Foundation, please see http://www.apache.org.
The following software may be included in this product: JLex: A Lexical Analyzer Generator for Java v. 1.2.5; Use of any of this software is governed by the terms of the license below:
JLEX COPYRIGHT NOTICE, LICENSE AND DISCLAIMER.
Copyright 1996-2003 by Elliot Joel Berk and C. Scott Ananian
Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both the copyright notice and this permission notice and warranty disclaimer appear in supporting
documentation, and that the name of the authors or their employers not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission.
The authors and their employers disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness. In no event shall the authors or their employers be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss
of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.
Java is a trademark of Sun Microsystems, Inc. References to the Java programming language in relation to JLex are not meant to imply that Sun endorses this product.
The following software may be included in this product: SAX v. 2.0.1; Use of any of this software is governed by the terms of the license below:
Copyright Status
SAX is free!
In fact, it's not possible to own a license to SAX, since it's been placed in the public domain.
No Warranty
Because SAX is released to the public domain, there is no warranty for the design or for the software implementation, to the extent permitted by applicable law. Except when otherwise stated in writing the copyright holders and/or other parties provide SAX "as is" without warranty of any kind, either
expressed or implied, including, but not limited to, the implied warranties of merchantability and fitness for a particular purpose. The entire risk as to the quality and performance of SAX is with you.
Should SAX prove defective, you assume the cost of all necessary servicing, repair or correction.
In no event unless required by applicable law or agreed to in writing will any copyright holder, or any other party who may modify and/or redistribute SAX, be liable to you for damages, including any general, special, incidental or consequential damages arising out of the use or inability to use SAX
(including but not limited to loss of data or data being rendered inaccurate or losses sustained by you or third parties or a failure of the SAX to operate with any other programs), even if such holder or other party has been advised of the possibility of such damages.
Copyright Disclaimers
This page includes statements to that effect by David Megginson, who would have been able to claim copyright for the original work.
SAX 1.0
Version 1.0 of the Simple API for XML (SAX), created collectively by the membership of the XML-DEV mailing list, is hereby released into the public domain.
No one owns SAX: you may use it freely in both commercial and non-commercial applications, bundle it with your software distribution, include it on a CD-ROM, list the source code in a book, mirror the documentation at your own web site, or use it in any other way you see fit.
David Megginson, sax@megginson.com 1998-05-11
SAX 2.0
I hereby abandon any property rights to SAX 2.0 (the Simple API for XML), and release all of the SAX 2.0 source code, compiled code, and documentation contained in this distribution into the Public Domain. SAX comes with NO WARRANTY or guarantee of fitness for any purpose.
David Megginson, david@megginson.com
2000-05-05
The following software may be included in this product: Cryptix;
Use of any of this software is governed by the terms of the license below:
Cryptix General License
Copyright © 1995-2003 The Cryptix Foundation Limited. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1.Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.
2.Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE CRYPTIX FOUNDATION LIMITED AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE CRYPTIX FOUNDATION LIMITED OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
EXERPT FROM JavaTM 2 Platform Standard Edition Development Kit 5.0 README
You can freely redistribute the J2SE Runtime Environment with your application, according to the terms of the Runtime Environment's license. Once you have developed your application using the JDK, you can ship it with the Runtime Environment so your end-users will have a Java platform on which
to run your software.
Redistribution
-------------------------------------------------------------------------------NOTE - The license for this software does not allow the redistribution of beta and other pre-release versions.
-------------------------------------------------------------------------------Subject to the terms and conditions of the Software License Agreement and the obligations, restrictions, and exceptions set forth below, You may reproduce and distribute the Software (and also portions of Software identified below as Redistributable), provided that:
you distribute the Software complete and unmodified and only bundled as part of Your applets and applications ("Programs"),
your Programs add significant and primary functionality to the Software,
your Programs are only intended to run on Java-enabled general purpose desktop computers and servers,
you distribute Software for the sole purpose of running your Programs,
you do not distribute additional software intended to replace any component(s) of the Software,
you do not remove or alter any proprietary legends or notices contained in or on the Software,
you only distribute the Software subject to a license agreement that protects Sun's interests consistent with the terms contained in this Agreement, and
you agree to defend and indemnify Sun and its licensors from and against any damages, costs, liabilities, settlement amounts and/or expenses (including attorneys' fees) incurred in connection with any claim, lawsuit or action by any third party that arises or results from the use or distribution of any and all
Programs and/or Software.
The term "vendors" used here refers to licensees, developers, and independent software vendors (ISVs) who license and distribute the J2SE Development Kit with their programs.
Vendors must follow the terms of the J2SE Development Kit Binary Code License agreement.
Required vs. Optional Files
The files that make up the J2SE Development Kit are divided into two categories: required and optional. Optional files may be excluded from redistributions of the JDK at the vendor's discretion.
The following section contains a list of the files and directories that may optionally be omitted from redistributions of the JDK. All files not in these lists of optional files must be included in redistributions of the JDK.
Optional Files and Directories
The following files may be optionally excluded from redistributions. These files are located in the jdk1.5.0_<version> directory, where <version> is the update version number. Solaris and Linux filenames and separators are shown. Windows executables have the ".exe" suffix. Corresponding files with _g
in name can also be excluded.
jre/lib/charsets.jar
Character conversion classes
jre/lib/ext/
sunjce_provider.jar - the SunJCE provider for Java Cryptography APIs
localedata.jar - contains many of the resources needed for non US English locales
ldapsec.jar - contains security features supported by the LDAP service provider
dnsns.jar - for the InetAddress wrapper of JNDI DNS provider
bin/rmid and jre/bin/rmid
Java RMI Activation System Daemon
bin/rmiregistry and jre/bin/rmiregistry
Java Remote Object Registry
bin/tnameserv and jre/bin/tnameserv
Java IDL Name Server
bin/keytool and jre/bin/keytool
Key and Certificate Management Tool
bin/kinit and jre/bin/kinit
Used to obtain and cache Kerberos ticket-granting tickets
bin/klist and jre/bin/klist
Kerberos display entries in credentials cache and keytab
bin/ktab and jre/bin/ktab
Kerberos key table manager
bin/policytool and jre/bin/policytool
Policy File Creation and Management Tool
bin/orbd and jre/bin/orbd
Object Request Broker Daemon
bin/servertool and jre/bin/servertool
Java IDL Server Tool
bin/javaws, jre/bin/javaws, jre/lib/javaws/ and jre/lib/javaws.jar
Java Web Start
src.zip
Archive of source files
Redistributable JDK Files
The limited set of files from the JDK listed below may be included in vendor redistributions of the J2SE Runtime Environment. They cannot be redistributed separately, and must accompany a JRE distribution. All paths are relative to the top-level directory of the JDK.
jre/lib/cmm/PYCC.pf
Color profile. This file is required only if one wishes to convert between the PYCC color space and another color space.
All .ttf font files in the jre/lib/fonts directory.
Note that the LucidaSansRegular.ttf font is already contained in the J2SE Runtime Environment, so there is no need to bring that file over from the JDK.
jre/lib/audio/soundbank.gm
This MIDI soundbank is present in the JDK, but it has been removed from the J2SE Runtime Environment in order to reduce the size of the Runtime Environment's download bundle. However, a soundbank file is necessary for MIDI playback, and therefore the JDK's soundbank.gm file may be included
in redistributions of the Runtime Environment at the vendor's discretion. Several versions of enhanced MIDI soundbanks are available from the Java Sound web site: http://java.sun.com/products/java-media/sound/. These alternative soundbanks may be included in redistributions of the J2SE Runtime
Environment.
The javac bytecode compiler, consisting of the following files:
bin/javac [Solaris(TM) Operating System and Linux]
bin/sparcv9/javac [Solaris Operating System (SPARC(R) Platform Edition)]
bin/amd64/javac [Solaris Operating System (AMD)]
bin/javac.exe [Microsoft Windows]
lib/tools.jar [All platforms]
The Annotation Processing Tool, consisting of the following files:
bin/apt [Solaris(TM) Operating System and Linux]
bin/sparcv9/apt [Solaris Operating System (SPARC(R) Platform Edition)]
bin/amd64/apt [Solaris Operating System (AMD)]
bin/apt.exe [Microsoft Windows]
jre\bin\server\
On Microsoft Windows platforms, the JDK includes both the Java HotSpot Server VM and Java HotSpot Client VM. However, the J2SE Runtime Environment for Microsoft Windows platforms includes only the Java HotSpot Client VM. Those wishing to use the Java HotSpot Server VM with the J2SE
Runtime Environment may copy the JDK's jre\bin\server folder to a bin\server directory in the J2SE Runtime Environment. Software vendors may redistribute the Java HotSpot Server VM with their redistributions of the J2SE Runtime Environment.
Unlimited Strength Java Cryptography Extension
Due to import control restrictions for some countries, the Java Cryptography Extension (JCE) policy files shipped with the J2SE Development Kit and the J2SE Runtime Environment allow strong but limited cryptography to be used. These files are located at
<java-home>/lib/security/local_policy.jar
<java-home>/lib/security/US_export_policy.jar
where <java-home> is the jre directory of the JDK or the top-level directory of the J2SE Runtime Environment.
An unlimited strength version of these files indicating no restrictions on cryptographic strengths is available on the JDK web site for those living in eligible countries. Those living in eligible countries may download the unlimited strength version and replace the strong cryptography jar files with the
unlimited strength files.
jconsole
jconsole.jar
jconsole may be redistributed outside the JDK but only with Sun's JRE.
Endorsed Standards Override Mechanism
An endorsed standard is a Java API defined through a standards process other than the Java Community ProcessSM (JCPSM). Because endorsed standards are defined outside the JCP, it is anticipated that such standards will be revised between releases of the Java 2 Platform. In order to take advantage of
new revisions to endorsed standards, developers and software vendors may use the Endorsed Standards Override Mechanism to provide newer versions of an endorsed standard than those included in the Java 2 Platform as released by Sun Microsystems.
For more information on the Endorsed Standards Override Mechanism, including the list of platform packages that it may be used to override, see
http://java.sun.com/j2se/1.5.0/docs/guide/standards/
Classes in the packages listed on that web page may be replaced only by classes implementing a more recent version of the API as defined by the appropriate standards body.
In addition to the packages listed in the document at the above URL, which are part of the Java 2 Platform Standard Edition (J2SETM) specification, redistributors of Sun's J2SE Reference Implementation are allowed to override classes whose sole purpose is to implement the functionality provided by
public APIs defined in these Endorsed Standards packages. Redistributors may also override classes in the org.w3c.dom.* packages, or other classes whose sole purpose is to implement these APIs.
The cacerts Certificates File
Root CA certificates may be added to or removed from the J2SE certificate file located at <java-home>/lib/security/cacerts. For more information, see The cacerts Certificates File section in the keytool documentation.
Web Pages
For additional information, refer to these Sun Microsystems pages on the World Wide Web:
http://java.sun.com/
The Java Software web site, with the latest information on Java technology, product information, news, and features.
http://java.sun.com/docs
Java Platform Documentation provides access to white papers, the Java Tutorial and other documents.
http://developer.java.sun.com
Developer Services web site. (Free registration required.) Additional technical information, news, and features; user forums; support information, and much more.
http://java.sun.com/products/
Java Technology Products & API
-------------------------------------------------------------------------------The J2SE Development Kit is a product of Sun MicrosystemsTM, Inc.
Copyright 2005 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A.
All rights reserved.
JDOM
Copyright (C) 2000-2004 Jason Hunter & Brett McLaughlin.
All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions, and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions, and the disclaimer that follows these conditions in the documentation and/or other materials provided with the distribution.
3. The name "JDOM" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact <request_AT_jdom_DOT_org>.
4. Products derived from this software may not be called "JDOM", nor may "JDOM" appear in their name, without prior written permission from the JDOM Project Management <request_AT_jdom_DOT_org>.
In addition, we request (but do not require) that you include in the end-user documentation provided with the redistribution and/or in the software itself an acknowledgement equivalent to the following:
"This product includes software developed by the JDOM Project (http://www.jdom.org/)."
Alternatively, the acknowledgment may be graphical using the logos available at http://www.jdom.org/images/logos.
THIS SOFTWARE IS PROVIDED ''AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL
THE JDOM AUTHORS OR THE PROJECT CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of the JDOM Project and was originally created by Jason Hunter <jhunter_AT_jdom_DOT_org> and Brett McLaughlin <brett_AT_jdom_DOT_org>. For more information on the JDOM Project, please see <http://
www.jdom.org/>.
Krypto
Copyright (c) 1997 Stanford University
Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notices and this permission notice appear in all copies of the software and related documentation.
THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
IN NO EVENT SHALL STANFORD BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE
POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
Copyright (C) 1995-1997 Eric Young (eay@mincom.oz.au)
All rights reserved.
This package is an SSL implementation written by Eric Young (eay@mincom.oz.au). The implementation was written so as to conform with Netscapes SSL.
This library is free for commercial and non-commercial use as long as the following conditions are aheared to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution
is covered by the same copyright terms except that the holder is Tim Hudson (tjh@mincom.oz.au).
Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation
(online or textual) provided with the package.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgement:
"This product includes cryptographic software written by Eric Young (eay@mincom.oz.au)"
The word 'cryptographic' can be left out if the routines from the library being used are not cryptographic related .
4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement:
"This product includes software written by Tim Hudson (tjh@mincom.oz.au)"
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The licence and distribution terms for any publically available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution licence [including the GNU Public Licence.]
OpenLDAP
Public License for 2.3.34
The OpenLDAP Public License
Version 2.8, 17 August 2003
Redistribution and use of this software and associated documentation ("Software"), with or without modification, are permitted provided that the following conditions are met:
1. Redistributions in source form must retain copyright statements and notices,
2. Redistributions in binary form must reproduce applicable copyright statements and notices, this list of conditions, and the following disclaimer in the documentation and/or other materials provided with the distribution, and
3. Redistributions must contain a verbatim copy of this document.
The OpenLDAP Foundation may revise this license from time to time. Each revision is distinguished by a version number. You may use this Software under terms of this license revision or under the terms of any subsequent revision of the license.
THIS SOFTWARE IS PROVIDED BY THE OPENLDAP FOUNDATION AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OPENLDAP FOUNDATION, ITS CONTRIBUTORS, OR THE AUTHOR(S) OR OWNER(S) OF THE SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The names of the authors and copyright holders must not be used in advertising or otherwise to promote the sale, use or other dealing in this Software without specific, written prior permission. Title to copyright in this Software shall at all times remain with copyright holders.
OpenLDAP is a registered trademark of the OpenLDAP Foundation.
Copyright 1999-2003 The OpenLDAP Foundation, Redwood City, California, USA. All Rights Reserved. Permission to copy and distribute verbatim copies of this document is granted.
OpenSSL
License
The OpenSSL toolkit stays under a dual license, i.e. both the conditions of the OpenSSL License and the original SSLeay license apply to the toolkit. See below for the actual license texts. Actually both licenses are BSD-style Open Source licenses. In case of any license issues related to OpenSSL please
contact openssl-core@openssl.org.
OpenSSL License
Copyright (c) 1998-2007 The OpenSSL Project. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgment:
"This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact openssl-core@openssl.org.
5. Products derived from this software may not be called "OpenSSL" nor may "OpenSSL" appear in their names without prior written permission of the OpenSSL Project.
6. Redistributions of any form whatsoever must retain the following acknowledgment:
"This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)"
THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This product includes cryptographic software written by Eric Young (eay@cryptsoft.com). This product includes software written by Tim Hudson (tjh@cryptsoft.com).
Original SSLeay License
Copyright (C) 1995-1998 Eric Young (eay@cryptsoft.com)
All rights reserved.
This package is an SSL implementation written by Eric Young (eay@cryptsoft.com). The implementation was written so as to conform with Netscapes SSL.
This library is free for commercial and non-commercial use as long as the following conditions are aheared to. The following conditions apply to all code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not just the SSL code. The SSL documentation included with this distribution
is covered by the same copyright terms except that the holder is Tim Hudson (tjh@cryptsoft.com).
Copyright remains Eric Young's, and as such any Copyright notices in the code are not to be removed. If this package is used in a product, Eric Young should be given attribution as the author of the parts of the library used. This can be in the form of a textual message at program startup or in documentation
(online or textual) provided with the package.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. All advertising materials mentioning features or use of this software must display the following acknowledgement:
"This product includes cryptographic software written by Eric Young (eay@cryptsoft.com)"
The word 'cryptographic' can be left out if the rouines from the library being used are not cryptographic related :-).
4. If you include any Windows specific code (or a derivative thereof) from the apps directory (application code) you must include an acknowledgement: "This product includes software written by Tim Hudson (tjh@cryptsoft.com)"
THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
The license and distribution terms for any publically available version or derivative of this code cannot be changed. i.e. this code cannot simply be copied and put under another distribution license [including the GNU Public License.]
Oracle
*****************************************************************
Oracle Instant client
End user license agreement ("Agreement")
*****************************************************************
MatrixOne Inc., ("MatrixOne") as licensor, has been given the right by Oracle Corporation (Oracle") to distribute the Oracle Instant Client software ("Program(s)") to you, an end user. Each end user hereby agrees: (1) to restrict its use of the Programs to its internal business operations; (2) that it is
prohibited from (a) assigning, giving, or transferring the Programs or an interest in them to another individual or entity (and if it grants a security interest in the Programs, the secured party has no right to use or transfer the Programs); (b) making the Programs available in any manner to any third party for
use in the third party's business operations (unless such access is expressly permitted for the specific program license or materials from the services acquired); and (3) that title to the Programs does not pass to the end user or any other party; (4) that reverse engineering is prohibited (unless required by law
for interoperability), (5) disassembly or decompilation of the Programs are prohibited; (6) duplication of the Programs is prohibited except for a sufficient number of copies of each Program for the end user's licensed use and one copy of each Program media; (7) that, to the extent permitted by applicable
law, liability of Oracle and MatrixOne for any damages, whether direct, indirect, incidental, or consequential, arising from the use of the Programs is disclaimed; (8) at the termination of the Agreement, to discontinue use and destroy or return to MatrixOne all copies of the Programs and documentation;
(9) not to publish any results of benchmark tests run on the Programs; (10) to comply fully with all relevant export laws and regulations of the United States and other applicable export and import laws to assure that neither the Programs, nor any direct product thereof, are exported, directly or indirectly,
in violation of applicable laws and are not used for any purpose prohibited by these laws including, without limitation, nuclear, chemical or biological weapons proliferation; (11) that Oracle is not required to perform any obligations or incur any liability not previously agreed to; (12) to permit MatrixOne
to audit its use of the Programs or to assign such audit right to Oracle; (13) that Oracle is a third party beneficiary of this end user license agreement; (14) that the application of the Uniform Computer Information Transactions Act is excluded.
Disclaimer of Warranty and Exclusive Remedies
THE PROGRAMS ARE PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MATRIXONE AND ORACLE FURTHER DISCLAIM ALL WARRANTIES, EXPRESS AND IMPLIED, INCLUDING WITHOUT LIMITATION, ANY IMPLIED WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT.
IN NO EVENT SHALL MATRIXONE OR ORACLE BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, PUNITIVE OR CONSEQUENTIAL DAMAGES, OR DAMAGES FOR LOSS OF PROFITS, REVENUE, DATA OR DATA USE, INCURRED BY YOU OR ANY THIRD PARTY,
WHETHER IN AN ACTION IN CONTRACT OR TORT, EVEN IF MATRIXONE OR ORACLE HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. MATRIXONE'S AND ORACLE'S ENTIRE LIABILITY FOR DAMAGES HEREUNDER SHALL IN NO EVENT EXCEED
ONE THOUSAND DOLLARS (U.S. $1,000).
No Technical Support
Oracle and MatrixOne technical support organizations will not provide technical support, phone support, or updates to end users for the Programs licensed under this agreement.
Restricted Rights
For United States government end users, the Programs, including documentation, shall be considered commercial computer software and the following applies:
NOTICE OF RESTRICTED RIGHTS
"Programs delivered subject to the DOD FAR Supplement are 'commercial computer software' and use, duplication, and disclosure of the programs, including documentation, shall be subject to the licensing restrictions set forth in the applicable Oracle license agreement. Otherwise, programs delivered
subject to the Federal Acquisition Regulations are 'restricted computer software' and use, duplication, and disclosure of the programs, including documentation, shall be subject to the restrictions in FAR 52.227-19, Commercial Computer Software-Restricted Rights (June 1987). Oracle Corporation, 500
Oracle Parkway, Redwood City, CA 94065."
End of Agreement
The end user may terminate this Agreement by destroying all copies of the Programs. MatrixOne and Oracle each have the right to terminate the end user's right to use the Programs if the end user fails to comply with any of the terms of this Agreement, in which case the end user shall destroy all copies
of the Programs.
Relationship Between the Parties
The relationship between the end user and MatrixOne and Oracle is that the end user is licensee, MatrixOne is distributor/licensor and Oracle is licensor. No party will represent that it has any authority to assume or create any obligation, express or implied, on behalf of any other party, nor to represent the
other party as agent, employee, franchisee, or in any other capacity. Nothing in this Agreement shall be construed to limit any party's right to independently develop or distribute software that is functionally similar to the other party's products, so long as proprietary information of the other party is not
included in such software.
Open Source
"Open Source" software - software available without charge for use, modification and distribution - is often licensed under terms that require the user to make the user's modifications to the Open Source software or any software that the user 'combines' with the Open Source software freely available in
source code form. If you as end user use Open Source software in conjunction with the Programs, you must ensure that your use does not: (i) create, or purport to create, obligations of MatrixOne or Oracle with respect to the Oracle Programs; or (ii) grant, or purport to grant, to any third party any rights
to or immunities under intellectual property or proprietary rights in the Oracle Programs. For example, you may not develop a software program using an Oracle Program and an Open Source program where such use results in a program file(s) that contains code from both the Oracle Program and the Open
Source program (including without limitation libraries) if the Open Source program is licensed under a license that requires any "modifications" be made freely available. You also may not combine the Oracle Program with programs licensed under the GNU General Public License ("GPL") in any manner
that could cause, or could be interpreted or asserted to cause, the Oracle Program or any modifications thereto to become subject to the terms of the GPL.
SSLUtils
The Apache Software License, Version 1.1
Copyright (c) 2000 The Apache Software Foundation. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. The end-user documentation included with the redistribution, if any, must include the following acknowledgment:
wherever such third-party acknowledgments normally appear.
"This product includes software developed by the Apache Software Foundation (http://www.apache.org/)." Alternately, this acknowledgment may appear in the software itself, if and
4. The names "SOAP" and "Apache Software Foundation" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact apache@apache.org.
5. Products derived from this software may not be called "Apache", nor may "Apache" appear in their name, without prior written permission of the Apache Software Foundation.
THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OFUSE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUTOF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This software consists of voluntary contributions made by many individuals on behalf of the Apache Software Foundation and was originally based on software copyright (c) 2000, International Business Machines, Inc., http://www.apache.org. For more information on the Apache Software Foundation,
please see <http://www.apache.org/>.
Sun RPC
Sun RPC is a product of Sun Microsystems, Inc. and is provided for unrestricted use provided that this legend is included on all tape media and as a part of the software program in whole or part. Users may copy or modify Sun RPC without charge, but are not authorized to license or distribute it to anyone
else except as part of a product or program developed by the user.
SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.
Sun RPC is provided with no support and without any obligation on the part of Sun Microsystems, Inc. to assist in its use, correction, modification or enhancement.
SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY SUN RPC OR ANY PART THEREOF.
In no event will Sun Microsystems, Inc. be liable for any lost revenue or profits or other special, indirect and consequential damages, even if Sun has been advised of the possibility of such damages.
Sun Microsystems, Inc.
2550 Garcia Avenue
Mountain View, California 94043
Tcl
This software is copyrighted by the Regents of the University of California, Sun Microsystems, Inc., Scriptics Corporation, and other parties. The following terms apply to all files associated with the software unless explicitly disclaimed in individual files.
The authors hereby grant permission to use, copy, modify, distribute, and license this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. No written agreement, license, or royalty fee
is required for any of the authorized uses. Modifications to this software may be copyrighted by their authors and need not follow the licensing terms described here, provided that the new terms are clearly indicated on the first page of each file where they apply.
IN NO EVENT SHALL THE AUTHORS OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES
THEREOF, EVEN IF THE AUTHORS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE AUTHORS AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS
PROVIDED ON AN "AS IS" BASIS, AND THE AUTHORS AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
GOVERNMENT USE: If you are acquiring this software on behalf of the U.S. government, the Government shall have only "Restricted Rights" in the software and related documentation as defined in the Federal Acquisition Regulations (FARs) in Clause 52.227.19 (c) (2). If you are acquiring the
software on behalf of the Department of Defense, the software shall be classified as "Commercial Computer Software" and the Government shall have only "Restricted Rights" as defined in Clause 252.227-7013 (c) (1) of DFARs. Notwithstanding the foregoing, the authors grant the U.S. Government and
others acting in its behalf permission to use and distribute the software in accordance with the terms specified in this license.
Xalan
[under Apache License, Version 2.0 above]
Xerces
[under Apache License, Version 2.0 above]
Xerces2
[under Apache License, Version 2.0 above]
Table of Contents
Chapter 1.
Overview.............................................................................................. 21
Overview of ENOVIA Live Collaboration ................................................................. 21
What Needs to be Installed? ............................................................................ 23
Tcl Support....................................................................................................... 25
Chapter 2.
Language Support.............................................................................. 27
Overview of Language ............................................................................................ 27
Supported Language Configurations ............................................................... 28
Multiple Language Support .............................................................................. 30
Chapter 3.
Installing an Oracle Database............................................................ 31
Installing the Database Software ............................................................................ 31
Installing the Oracle Server..................................................................................... 32
Configuring the Oracle Server for Use with ENOVIA Live Collaboration ................ 33
Designing the Database ......................................................................................... 34
Control Files..................................................................................................... 34
Redo Logs........................................................................................................ 34
Tablespaces and Datafiles ............................................................................... 35
Rollback Segments .......................................................................................... 36
Indexing............................................................................................................ 37
Oracle Parameter File: init<SID>.ora ............................................................... 38
Creating the Database ..................................................................................... 43
Oracle 10G....................................................................................................... 47
Configuring Oracle for Non-English Languages ..................................................... 49
Disk Layout Suggestions ........................................................................................ 52
4 to 7 Disk System ........................................................................................... 53
RAID Technology ............................................................................................. 54
Other Disk Solutions ........................................................................................ 57
Reconfiguring Oracle .............................................................................................. 58
Rebuilding the Control File............................................................................... 58
Rebuilding Redo Logs...................................................................................... 59
Tuning and Statistics ............................................................................................... 61
Oracle Initialization Parameters ....................................................................... 61
A note about scalability and performance ........................................................ 69
Chapter 4.
Installing a DB2 Database.................................................................. 71
Installing the Database Software ............................................................................ 71
Installing the DB2 Server ........................................................................................ 72
Code Set and Language Settings ........................................................................... 73
DB2 Database Client Configuration ................................................................. 73
Using DB2 with ENOVIA Products.......................................................................... 74
DB2 and ENOVIA Products ............................................................................. 74
Configuring DB2 ..................................................................................................... 78
Currently Committed Mode .............................................................................. 78
Table of Contents
11
Configuration Parameters ................................................................................ 79
CLOB Datatypes .............................................................................................. 81
Additional Performance Related Tasks ................................................................... 82
SQL0429N LOB locator limit ............................................................................ 82
AIX Environment .............................................................................................. 83
Sample DB2 Database Creation Script................................................................... 84
Chapter 5.
Installing an SQL Server Database ................................................... 89
Installing the Database Software ............................................................................ 89
Installing SQL Server .............................................................................................. 90
Setting up SQL Server for Use with ENOVIA Live Collaboration ............................ 91
Configuring SQL Server.......................................................................................... 97
Minimizing Deadlock Potential.......................................................................... 97
Using Indexes with SQL Server ....................................................................... 97
Case Sensitivity................................................................................................ 97
Maintaining the Database ................................................................................ 97
Configuring Disk Layout .......................................................................................... 99
Selecting and Formatting Drives ...................................................................... 99
Performance and Scalability............................................................................. 99
General Index Recommendations......................................................................... 100
Configuring Table Statistics ............................................................................ 100
Limiting Physical I/O....................................................................................... 100
SQL Server Limitations with ENOVIA Live Collaboration...................................... 101
SQL Server concurrency................................................................................ 101
Localization Support ............................................................................................. 102
Chapter 6.
Installing a MySQL Database........................................................... 103
Installing the Database Software .......................................................................... 103
Installing MySQL Server ....................................................................................... 104
Setting up MySQL Server for Use with ENOVIA Live Collaboration ..................... 105
Windows Configuration .................................................................................. 105
Linux Configuration ........................................................................................ 106
Configuring MySQL Server ................................................................................... 108
Important MySQL Server Parameters ............................................................ 108
MySQL Server with Linux Environments........................................................ 108
Maintaining the Database .............................................................................. 108
Case Sensitivity.............................................................................................. 108
Configuring Disk Layout ........................................................................................ 109
Selecting and Formatting Drives .................................................................... 109
MySQL Server Limitations with ENOVIA Live Collaboration................................. 110
Difference in Configuration............................................................................. 110
Localization Support ............................................................................................. 111
Chapter 7.
Installing the Studio Modeling Platform ......................................... 113
Overview ............................................................................................................... 113
Installing ENOVIA Studio Modeling Platform on UNIX/Linux ................................ 114
Installing ENOVIA Studio Modeling Platform on Windows.................................... 129
Exiting Setup......................................................................................................... 142
Installing a New Version of Studio Modeling Platform........................................... 143
Using Lower Version Software after Upgrading the Database ....................... 143
12
ENOVIA Live Collaboration Installation Guide
Upgrade Analysis ........................................................................................... 143
Oracle Configuration ...................................................................................... 145
Running the Upgrade ..................................................................................... 146
After the Upgrade........................................................................................... 147
Uninstalling ENOVIA Studio Modeling Platform on UNIX/Linux............................ 148
Uninstalling ENOVIA Studio Modeling Platform on Windows ............................... 148
Chapter 8.
Installing the Live Collaboration Server......................................... 149
Overview ............................................................................................................... 149
Web or Application Server ............................................................................. 149
Live Collaboration Kernel ............................................................................... 150
Java/RMI Server ............................................................................................ 150
RIP: RMI In-process....................................................................................... 151
RMI Gateway ................................................................................................. 151
Installing a Web or Application Server .................................................................. 153
Java Development Kit .................................................................................... 154
Installing a WebLogic Server ......................................................................... 156
Installing WebSphere ..................................................................................... 157
Installing the Sun Java System Application Server ........................................ 158
Installing Tomcat ............................................................................................ 159
Optional Static Content Server ...................................................................... 160
Using a UNIX or Linux Live Collaboration Server without a Monitor..................... 161
Preparing to Install the ENOVIA Live Collaboration Server .................................. 162
General Installation for ENOVIA Live Collaboration Server ........................... 162
Before Installing ENOVIA Live Collaboration Server...................................... 163
Installing ENOVIA Live Collaboration Server on UNIX/Linux................................ 164
Installing ENOVIA Live Collaboration Server on Windows ................................... 186
Installing a Live Collaboration Server Service Pack.............................................. 206
Configuring the ENOVIA Live Collaboration Server.............................................. 212
Reconfiguring the ENOVIA Live Collaboration Server Windows Service ...... 212
Reconfiguring the ENOVIA Live Collaboration Server on UNIX..................... 215
Reconfiguring ENOVIA Live Collaboration Server Port Numbers .................. 216
Implementing the Security Wrapper on RMI Gateway ................................... 217
ENOVIA Live Collaboration Server Environment Settings .................................... 219
Optional Settings............................................................................................ 220
Time Zones through ENOVIA Live Collaboration Server ............................... 222
UTF-8 Settings...................................................................................................... 223
Automated UTF-8 Settings............................................................................. 223
Additional Manual UTF-8 Settings ................................................................. 225
Additional Manual UTF-8 Settings for AIX ..................................................... 226
File Collaboration Server ...................................................................................... 229
Setting Up the FCS Synchronization Server.................................................. 229
Running the FCS Synchronization Server ..................................................... 234
Validating and Debugging an FCS ................................................................. 236
Installing Multiple ENOVIA Live Collaboration Servers (RIP only)........................ 237
Interface for Downstream Installers, E4All, and other Automated Installers ......... 238
Internal Directory Structure Defined in enovia.install ..................................... 238
Example enovia.install Files........................................................................... 238
Matrix.ini and eMatrix.ini File Dependency Removed .................................... 239
Studio Version of MQL Command Removed ................................................. 239
Table of Contents
13
Uninstalling ENOVIA Live Collaboration Server on UNIX/Linux............................ 239
Uninstalling ENOVIA Live Collaboration Server on Windows ............................... 240
Chapter 9.
Configuring ENOVIA Live Collaboration ........................................ 241
Configuring ENOVIA Live Collaboration................................................................ 241
Command Line Options ................................................................................. 242
The Initialization File/Startup Scripts.............................................................. 242
Setting Personal Preferences......................................................................... 245
MatrixIniDefaults ............................................................................................ 245
Matrix System Defaults Program.................................................................... 246
ENOVIA Live Collaboration Settings ..................................................................... 251
Typical Environment Variables ....................................................................... 251
Optional Variables .......................................................................................... 254
Dynamically Updated Variables...................................................................... 261
Configuring Help ............................................................................................ 263
Font and Color Variables................................................................................ 263
LDAP Variables .............................................................................................. 264
Configuring Date and Time Formats..................................................................... 265
Localizing ENOVIA Live Collaboration .................................................................. 270
Studio Modeling Platform ............................................................................... 271
ENOVIA applications...................................................................................... 272
Web Navigator................................................................................................ 273
Chapter 10.
Deploying J2EE................................................................................. 275
J2EE Deployment Overview ................................................................................. 275
Modifying J2EE Settings ....................................................................................... 283
Web.xml ......................................................................................................... 283
ematrix.xml..................................................................................................... 294
Framework.properties .................................................................................... 295
Application Server Files ................................................................................. 295
Building the J2EE Archive File .............................................................................. 297
Running the WAR Utility on UNIX or Linux .................................................... 297
Running the WAR utility on Windows ............................................................. 297
Deploying the J2EE Archive File ........................................................................... 299
Deploying on WebSphere .............................................................................. 299
Deploying on WebLogic ................................................................................. 300
Deploying on Sun Java System Application Server ....................................... 301
Deploying on Tomcat...................................................................................... 302
Starting the ENOVIA Live Collaboration Server.................................................... 303
Chapter 11.
Installing the Documentation .......................................................... 305
ENOVIA Live Collaboration Documentation.......................................................... 305
Installing the PDF Files .................................................................................. 305
Uninstalling the Online Help Files .................................................................. 306
Customizing Help .................................................................................................. 307
Adding Custom Help Files.............................................................................. 308
Chapter 12.
Installing Matrix Web Navigator ...................................................... 309
Web Navigator Installation .................................................................................... 309
Installing Web Navigator on UNIX.................................................................. 309
14
ENOVIA Live Collaboration Installation Guide
Installing Web Navigator on Windows............................................................ 310
Setting up for Web Navigator Access ................................................................... 311
Configuring for download of Sun JVM............................................................ 311
Installing the Public Security Key ................................................................... 312
Configuring Web Navigator ............................................................................ 312
Defining Default Fonts on the Web ................................................................ 315
User Startup.......................................................................................................... 317
Removing Web Navigator ..................................................................................... 318
The Server’s Directory Structure .......................................................................... 319
Chapter 13.
Integrating with LDAP and External Authentication Tools ........... 321
Internal vs. External Authentication ...................................................................... 321
Login Behavior When External Authentication is Used.................................. 322
Enabling External Authentication ................................................................... 323
Using the Authentication Classes .................................................................. 324
Using LDAP with ENOVIA Live Collaboration ....................................................... 327
Limitations ...................................................................................................... 327
Behaviors to Note........................................................................................... 327
LDAP Integration Works for both Types of Authentication.............................. 327
Information Retrieved from LDAP .................................................................. 328
Overview of LDAP Connection Process......................................................... 330
Types of Binding............................................................................................. 331
Integrating ENOVIA Live Collaboration with LDAP ........................................ 332
Support for TLS/SSL...................................................................................... 339
Encrypting the Bind Password ....................................................................... 339
Using Password Triggers with LDAP .............................................................. 339
Retrieving LDAP Data Using Selects ............................................................. 340
LDAP Sample Settings................................................................................... 340
Tomcat LDAP Authentication ................................................................................ 346
Changes to server.xml ................................................................................... 346
Changes to web.xml....................................................................................... 346
Additions to enovia.ini .................................................................................... 347
Changes to WEB-INF\classes ....................................................................... 347
Chapter 14.
Installing Business Process Services™ ........................................ 349
Overview ............................................................................................................... 349
Important Installation Considerations............................................................. 350
Preparing to Install to a Production Environment........................................... 350
Reviewing Changes that an Installation Makes.............................................. 351
Before Installing ............................................................................................. 352
Installing ENOVIA Live Collaboration Business Process Services ....................... 354
Installing Business Process Services on UNIX.............................................. 354
Installing Business Process Services on Windows........................................ 356
Adding Sample Users .................................................................................... 357
Schema Installer ................................................................................................... 358
Schema XML Files ......................................................................................... 358
Adding Custom Schema ................................................................................ 359
Installing Schema with the Schema Installer ................................................. 363
Installing to Large Databases ............................................................................... 368
About the Script ............................................................................................. 368
Before Running the Script .............................................................................. 369
Table of Contents
15
Running the Script.......................................................................................... 370
Database Considerations ............................................................................... 371
The Installation Process........................................................................................ 373
Installing to a Populated Database (Released Versions Only) ....................... 373
MatrixIniDefaults Program.............................................................................. 373
Business Process Services Version Must Be Correct for Applications .......... 374
Preventing Custom Pages from Being Overwritten During Upgrades ............ 374
How the Installation Manages Previous Versions........................................... 376
How the Installation Handles Schema Similarities ......................................... 378
Installation Log File ........................................................................................ 380
Directory Structure ......................................................................................... 383
J2EE Implementation ..................................................................................... 385
File Naming Conventions ............................................................................... 386
Chapter 15.
Installing the 3DVIA Viewer.............................................................. 389
Overview ............................................................................................................... 389
3DVIA Viewer Live Collaboration Server Installation............................................. 391
Prerequisites for Installing the 3DVIA Viewer on the Live Collaboration Server...
391
Installing the 3DVIA Viewer on Windows ....................................................... 392
Installing the 3DVIA Viewer on UNIX ............................................................. 392
Upgrading the 3DVIA Viewer.......................................................................... 393
Chapter 16.
Installing ENOVIA Products............................................................. 395
Overview ............................................................................................................... 395
Before Installing the applications.................................................................... 395
Installing a Service Pack ................................................................................ 396
Installing an Application on UNIX................................................................... 396
Installing an Application on Windows ............................................................ 398
Upgrading ENOVIA Products ................................................................................ 402
Installation Troubleshooting................................................................................... 403
User Access to ENOVIA products......................................................................... 405
Compile JSPs and JPOs................................................................................ 405
File Text Searches.......................................................................................... 405
Time/Date Format .......................................................................................... 405
Configuring File Download for Multi-Byte Filenames on IE ............................ 405
Browser Screen Resolution and DPI settings ................................................ 406
Accessing ENOVIA products.......................................................................... 406
Installing the ENOVIA Semiconductor Accelerators ............................................. 407
Installing DesignSync Central ........................................................................ 407
Installing the Design to Manufacture Accelerator........................................... 412
Installing the Enterprise Project Management Accelerator ............................ 416
Installing the IP Management Accelerator ..................................................... 423
Uninstalling an Application, Service Pack or Hot Fix ............................................ 429
Uninstalling an Application using Uninstall Program ...................................... 429
Uninstalling an Application using the Add or Remove Programs Option on
Windows......................................................................................................... 430
Tracking Customizations ................................................................................ 430
Chapter 17.
Installing the ENOVIA Studio Federation Toolkit........................... 431
ENOVIA Studio Federation Toolkit Installation ...................................................... 431
16
ENOVIA Live Collaboration Installation Guide
lnstalling the Studio Federation Toolkit on UNIX ............................................ 431
Installing the Studio Federation Toolkit on Windows ...................................... 432
Installation Results................................................................................................ 433
Chapter 18.
Installing the Studio Customization Toolkit ................................... 435
Studio Customization Toolkit Installation............................................................... 435
Installing the Studio Customization Toolkit on UNIX ...................................... 435
Installing the Studio Customization Toolkit on Windows ................................ 436
The Server’s Directory Structure .......................................................................... 438
Chapter 19.
Configuring a Japanese Web Environment.................................... 439
Overview ............................................................................................................... 439
Configuring the ENOVIA Live Collaboration Server for use in Japanese.............. 440
On UNIX......................................................................................................... 440
On Windows................................................................................................... 441
Tomcat Language Settings ............................................................................ 442
Configuring Additional Settings for Japanese ....................................................... 443
Displaying Japanese using KavaChart .......................................................... 443
Creating EBOM Markups ............................................................................... 443
NLS_LANG setting in the Matrix client........................................................... 444
Configuring the Application Server for use in Japanese ....................................... 445
WebLogic Servers.......................................................................................... 445
WebSphere Servers....................................................................................... 446
Modifying J2EE Settings for the Japanese Language .......................................... 447
In web.xml ...................................................................................................... 447
Content Type Setting...................................................................................... 447
Style Sheet Settings....................................................................................... 447
Building the J2EE Archive File in Japanese ......................................................... 449
Running the war utility on UNIX ..................................................................... 449
Running the WAR utility on Windows............................................................. 449
Deploying the J2EE Archive File in Japanese ...................................................... 450
Deploying on WebLogic ................................................................................. 450
Deploying on WebSphere .............................................................................. 451
Deploying on Tomcat...................................................................................... 451
Chapter 20.
Troubleshooting ENOVIA Live Collaboration................................. 453
Troubleshooting Topics ......................................................................................... 453
Server Startup Configuration Checker .................................................................. 454
mxAudit.log File.............................................................................................. 455
Evaluation Details .......................................................................................... 457
Additional ENOVIA Live Collaboration Server Configuration Troubleshooting...... 469
Checking Disk Space ..................................................................................... 470
Checking Memory Usage............................................................................... 470
Checking for Other Running Processes......................................................... 471
Reviewing Other Configuration Issues ........................................................... 471
Collecting Logs and Core Files ...................................................................... 475
Java Activation Error on the ENOVIA Live Collaboration Server ................... 476
mx_err_pid.log for Windows........................................................................... 476
ENOVIA Studio Modeling Platform Stability Troubleshooting ............................... 478
Stack Traces................................................................................................... 478
Table of Contents
17
Studio Customization Toolkit Origin Tracing ................................................... 478
Memory Pools ................................................................................................ 478
Memory Management .................................................................................... 479
Memory Troubleshooting Procedures ............................................................ 479
Implementation Troubleshooting ........................................................................... 482
Web Navigator Troubleshooting ............................................................................ 483
Set Context Problems .................................................................................... 483
Installation on UNIX ....................................................................................... 483
Look and Feel................................................................................................. 483
ENOVIA Studio Modeling Platform Troubleshooting ............................................. 485
Accessing Remote File Systems.................................................................... 485
Crash on Checkin........................................................................................... 485
Errors during Administration........................................................................... 486
Installation on UNIX ....................................................................................... 486
Localized Character display ........................................................................... 486
Localized Decimal Character Settings ........................................................... 487
.Rollback Segment Error ................................................................................ 488
Color Mapping................................................................................................ 489
Launching Applications in Windows ............................................................... 490
Miscellaneous Troubleshooting ............................................................................. 491
FTP Connection Timeouts ............................................................................. 491
Laptop Performance....................................................................................... 492
Session Timed Out Error................................................................................ 492
Tar Error When Unpacking Distributions ........................................................ 492
Problems with JSP Path for ENOVIA products............................................... 492
Chapter 21.
Server Diagnostics ........................................................................... 493
Overview ............................................................................................................... 493
Monitoring the Live Collaboration Server using the Monitoring Agent .................. 494
Setting up the Monitoring Agent..................................................................... 494
Creating a keystore File ................................................................................. 494
Configuring and Starting the Monitoring Agent .............................................. 495
Starting and Stopping the Monitoring Agent .................................................. 497
Description of Event Objects .......................................................................... 497
Monitoring Agent Events ................................................................................ 498
DS License Server Events ............................................................................. 499
MCS Events ................................................................................................... 500
Tracing Types ........................................................................................................ 505
Configuring Server Diagnostics with .ini File......................................................... 507
Considerations ............................................................................................... 508
Studio Customization Toolkit Origin Trace Facility................................................. 511
Enabling the Studio Customization Toolkit Client ........................................... 511
Enabling the Web/Application Server............................................................. 512
Enabling the Live Collaboration Kernel .......................................................... 512
Studio Customization Toolkit Origin Trace Output .......................................... 513
Memory Management ........................................................................................... 515
Configuring Memory Manager ....................................................................... 515
Load Runner Example ................................................................................... 517
Error and Log Messages................................................................................ 519
Gateway Debug Trace........................................................................................... 521
18
ENOVIA Live Collaboration Installation Guide
Index ............................................................................................................................ 523
Table of Contents
19
20
ENOVIA Live Collaboration Installation Guide
1
Overview
Overview of ENOVIA Live Collaboration
ENOVIA Live Collaboration™ is a standards-based, open and scalable system able to
support the largest, most complex, product lifecycle management deployments. It provides
the flexibility to easily configure business processes, user interfaces, and infrastructure
options to ensure that they meet your organization’s needs. The system enables you to
continually drive business process improvements to operate more efficiently using
pre-built metrics reports, while virtual workplace capabilities enable ad-hoc collaboration
for cross-functional and geographically dispersed teams to securely share product content.
All product development content can be routed for review and managed in repeatable
workflow business process.
ENOVIA Live Collaboration (CPF) provides the backbone for product lifecycle
management activies within a workgroup, enterprise, or extended enterprise, depending on
the organization’s needs. ENOVIA Live Collaboration is the underlying support for all
ENOVIA products and other Dassault Systèmes products for Product Lifecycle
Management, which include products from CATIA, 3DLive, SIMULIA, and DELMIA
product lines. It is comprised of the following end-user software components:
•
ENOVIA Matrix Navigator, which is the tool for searching the data objects based on
the data model. This application, or its Web-based version (MXW), is required to
administer triggers and other configuration objects for pre-V6 legacy clients. Both the
Rich client and Web version Navigator products are included with CPF. The rich
client is installed as part of the ENOVIA Studio Modeling Platform Rich Clients
21
distribution for ease of installation. The CPF license entitles your use of this
component of ENOVIA Studio Modeling Platform only. The rich client or the Web
version of Matrix Navigator can be installed from CD 1: ENOVIA Live Collaboration
- Navigator and Administrative Clients.
•
ENOVIA Live Collaboration Server, which is a Java/RMI-based business object
server. The MQL command line executable is included with the server for the purpose
of system installation and data/file storage setup functions only. If any other schema
configurations are needed, ENOVIA Studio Modeling Platform (DTE) must be
licensed. Note that if distributed file stores are created with Sites and Locations, one
or more ENOVIA File Collaboration Server licenses may also be needed. This is
installed from CD 2: ENOVIA Live Collaboration - Web Server.
•
ENOVIA Live Collaboration Business Process Services, include the capabilities from
the Application Exchange Framework, Common Components, Team Central, and
Business Process Metrics applications. This is installed from CD 3: ENOVIA Live
Collaboration - Business Process Services.
The following administrative add-ons are also available:
•
•
22
ENOVIA Studio Modeling Platform (DTE) provides the development tools for a
company to define and test configurations that are needed in their production
ENOVIA system. While ENOVIA offers PLM products that cover many product
development business processes, the need for companies to tailor or extend ENOVIA
products to meet their specific needs is inevitable, since a company's competitive
advantage often requires a unique product development process compared to how
other companies execute. Therefore, in order to deploy the ENOVIA system,
companies may need to set up an environment that allows them to develop changes to
the standard ENOVIA products and test them in conditions that duplicate the actual or
projected network and server performance. ENOVIA Studio Modeling Platform is
required in order to tailor and configure the production ENOVIA system.
The users of ENOVIA Studio Modeling Platform must be valid licensees of the
products that are configured and tested. However, a user's production license can also
be used with the system installed for ENOVIA Studio Modeling Platform. The
ENOVIA Studio Modeling Platform includes the following primary tools:
•
MQL - the command line interface tool for executing commands and scripts.
•
System Administration - the tool for managing and configuring data and file
storage vaults.
•
Business Modeler - the tool for managing the data model and its associated
business processes including types, attributes, relationships, and the web user
interface design.
•
Matrix Navigator - the tool for searching the data objects based on the data
model. This application is required to administer triggers and other configuration
objects.While the Matrix Navigator is installed as part of ENOVIA Studio
Modeling Platform for ease of installation, this application license is included in
both CPF and DTE. For legacy customers that are still based on thick client
deployments vs. Web, the CPF license entitles users to use Matrix Navigator.
ENOVIA Studio Federation Toolkit (ADT), which provides documentation and
examples for writing custom programs that use the Adaplet libraries available in
ENOVIA Live Collaboration.The ENOVIA Studio Federation Toolkit must be
licensed for each ENOVIA Studio Modeling Platform environment that requires
development of custom connectors with the Adaplet APIs.
ENOVIA Live Collaboration Installation Guide
What Needs to be
Installed?
•
ENOVIA Studio Customization Toolkit (ADV), which provides documentation and
examples for writing custom programs and support web services client development.
The ENOVIA Studio Customization Toolkit must be licensed for each ENOVIA
Studio Modeling Platform environment that requires development of custom
programming to change or extend standard ENOVIA capabilities.
•
ENOVIA File Collaboration Server (FCS), which enables administrators to distribute
file data across the enterprise for optimal upload and download performance. A
system license is required for each physical site that requires remote file storage.
There is no limit to the number of users that can use the ENOVIA File Collaboration
Server at a given licensed site, however, all of these users must be licensed to use
ENOVIA Live Collaboration, which is the prerequisite.
Depending on the options you purchased, you can:
•
Install the ENOVIA Live Collaboration components and prerequisites separately.
This option allows flexibility in choice of third party database and application server.
For enterprise and extended enterprise level use, you should evaluate the supported
database and application server choices and install the ones that best suit your needs.
The following table lists the order in which the components should be installed for the
primary architectures and lists the section of this guide that describes each installation.
Before beginning any installation, make sure you check its requirements in this chapter.
This
architecture
Needs these components installed in
this order
For instructions, see:
Client/server
(desktop or thick
client)
1. A supported database server on database
server machine, as listed in the
“Prerequisites” in the Program Directory
for the given release.
Chapter 3, Installing an Oracle
Database, Chapter 4, Installing
a DB2 Database, Chapter 5,
Installing an SQL Server
Database, or Chapter 6,
Installing a MySQL Database
2. ENOVIA Studio Modeling Platform on each
supported client machine, including a
connection (bootstrap) file.
Chapter 7, Installing the Studio
Modeling Platform
If required due to resource availability, the
ENOVIA Studio Modeling Platform software
may be installed before the database software,
but it will not run until the database
installations are complete.
Chapter 1: Overview
23
This
architecture
Needs these components installed in
this order
For instructions, see:
Any Web Access
1. The components listed for the client/server
architecture
Application server installation
guides
2. A supported Web or application server, such
as WebLogic or WebSphere, as shown in
“Prerequisites” in the Program Directory
for the given release
The Dassault Systemes License
Server Installation and
Configuration Guide
3. The Dassault Systemes License Server
4. The ENOVIA Live Collaboration Server.
For production use, it is recommended that
this is not installed on the same machine as
the database server. A JDK is required for
the ENOVIA Live Collaboration Server.
5. The ENOVIA Live Collaboration Business
Process Services
6. An application that end users will use to
connect to the database.
Chapter 8, Installing the Live
Collaboration Server
Chapter 14, Installing Business
Process Services™
Chapter 12, Installing Matrix
Web Navigator
Chapter 16, Installing ENOVIA
Products
Application Administration
Guides
Integration Administration
Guides
Before You Begin
You should review the Program Directory. Each version of ENOVIA Live Collaboration
comes with media that includes the program directory for that release. The program
directory is a website that organizes all the release information for all Dassault Systèmes
products for a given release. It contains information about prerequisites, installation,
licensing, product enhancements, general issues, open issues, documentation addenda, and
closed issues.
Conventions
When the UNIX installation procedure asks for input, it provides the default value in
brackets []. Default values for directory paths are based on the environment, so the
examples in this book show empty brackets. To use the default, simply press Enter.
Throughout this guide, certain words appear in capital letters, which indicates that you
need to enter specific information for your environment. Below is a description of some of
the abbreviations that are used in this manner.
•
24
INSTALL_PATH: directory in which to install the software. Once installed, this may
be referred to as one of:
•
ENOVIAHOME (UNIX) or ENOVIA_INSTALL (Windows) for
ENOVIA Studio Modeling Platform
•
SERVERHOME (UNIX) or SERVER_INSTALL (Windows) for
ENOVIA Live Collaboration Server
•
PLATFORM: local platform architecture. Must be from the appropriate list in
“Prerequisites” in the Program Directory for the given release.
•
HOSTNAME: name of the machine that applies to the current question.
ENOVIA Live Collaboration Installation Guide
Published examples in this document, including but not limited to scripts, programs, and
related items, are intended to provide some assistance to customers by example. They are
for demonstration purposes only. It does not imply an obligation for ENOVIA to provide
examples for every published platform, or for every potential permutation of platforms/
products/versions/etc.
Directory Naming Conventions
For ENOVIA Live Collaboration Business Process Services installation, the name of the
directory containing mql.exe CANNOT include any spaces.
For ENOVIA Studio Modeling Platform and Live Collaboration server installation, you
can use spaces in the name of the directory containing the JDK.
Tcl Support
The Tcl 8.5.7 library is installed and configured as the default version of Tcl with
installation of the desktop applications. On Windows, in order to load the tk libraries, it is
necessary to modify the system “path” environment variable to point to the path
containing the tk85.dll library, which will be under
SERVER_INSTALL\intel_a\code\bin\).
To Configure ENOVIA Live Collaboration for use with Tk 8.5.7
1. Install ENOVIA Live Collaboration.
2. In Control Panel, System, Environment Variables (on XP it’s on the Advanced Tab),
add the tcl directory to the end of the Path variable. For example:
e:\enoviav6r2011x\server\intel_a\code\bin
3. Save the setting and close Control Panel.
The Tcl/Tk 8.0 and 8.3.3 libraries are also included for cases where an implementation
requires the older version. If you have used Tcl 8.0 (the default before version 10.x) and
use locale specific tcl commands, such as those dealing with number formats, the default
ENOVIA Live Collaboration setup will behave differently. For example, in tcl mode of
MQL, if you enter the following on a machine set up with a European locale such as
de_DE:
format "%f" 3,45
With tcl 8.0, the returned value is:
3,450000
But with tcl 8.3.3, the value is:
3,45
You may need to rewrite code that depends on the 8.0 format. Until you have the time to
rewrite all applicable code, you can reconfigure ENOVIA Live Collaboration to use Tcl
8.0 as described below. The configuration is done via .ini files, so older version software
will not run with new .ini files, unless updates are made.
The MX_TCL_SHLIB variable sets the path to the TCL library you want to use, and
defaults to the 8.5.7 directory structure, so you’ll need to add this setting in order to use
the version 8.0 files. You must also reset the default TCL_LIBRARY and TK_LIBRARY
settings to the paths of the initialization files. Make these changes in the .ini files for
Windows, Studio Modeling Platform startup files for UNIX desktop, and mxEnv.sh for the
ENOVIA Live Collaboration Server on UNIX.
Chapter 1: Overview
25
If implementations rely on TCL_LIBRARY or TK_LIBRARY settings to find files under that
directory, you will need to move those files to the Tcl 8.5.7 directory structure. For
example, the Solutions Library depends on these entries being set in the environment to
find files under a sub-directory called mxTclDev.
Floating Point Calculations
The out of the box Tcl 8.5.7 performs floating point calculations at a higher precision than
the previously incorporated Tcl 8.3.3 which defaulted to precision=12. This can affect
some floating point calculations using 'expr'. For example:
% expr 1.23 + 4.56
5.789999999999999
If this is a problem, the workaround is to add the following line to <installdir>/tcl85/lib/
tcl8.5/init.tcl:
set tcl_precision 12
Adding this line will give you the same results as in Tcl 8.3.3:
% expr 1.23 + 4.56
5.79
Default Clock Command Output
When using Tcl 8.5.7 or Tcl 8.3.3, the “millis” subcommand should be used with the clock
command. The “clicks” subcommand is unreliable and should not be used.
Incorrect Syntax in the Catch Command
Please be aware that in Tcl versions before Tcl 8.5.7, Tcl was more lenient with the syntax
used in the catch command. The correct syntax is “catch BLOCK1 BLOCK2,” where
BLOCK1 and BLOCK2 are bracketed with “{}” and not “[].” The “[]” brackets force
evaluation prior to entering the catch command, which makes the command useless. Tcl
8.5.7 will enforce the use of “{}.”
26
ENOVIA Live Collaboration Installation Guide
2
Language Support
Overview of Language
The following languages are provided and supported on ENOVIA Live
Collaboration-supported Windows and UNIX (including Linux) platforms for both Studio
Modeling Platform and Web Navigator client menus, errors, and dialogs:
•
English
•
French
•
German
•
Italian
•
Japanese
The Studio Modeling Platform and Web Navigator are also provided and supported in the
following languages on ENOVIA Live Collaboration-supported Windows platforms only.
(Web Navigator is supported in these languages on correctly configured ENOVIA Live
Collaboration-supported Windows servers):
•
Korean
•
Traditional Chinese
•
Simplified Chinese
27
For other ENOVIA products, with the server appropriately configured, the following
languages are provided and supported on ENOVIA Live Collaboration supported
Windows and UNIX (including Linux) platforms:
•
English
•
French
•
German
•
Italian
•
Japanese
The appropriate configurations are shown in the tables below.
Supported
Language
Configurations
Note that the database and Application servers must be correctly configured to handle
UTF8 encoding.
French
Component
Live Collaboration Kernel
Lang Setting
Platform
Studio Modeling Platform
LANG = FR
Windows/UNIX
Web Navigator
LANG = C if supporting more
than 2 non-English languages
Or
LANG = FR
Windows/UNIX
ENOVIA I-PLM Business
Process applications
LANG = C with OS-level
Parameter UTF-8
Windows/UNIX
Component
Live Collaboration Kernel
Lang Setting
Platform
Studio Modeling Platform
LANG = IT
Windows/UNIX
Web Navigator
LANG = C if supporting more
than 2 non-English languages
Or
LANG = IT
Windows/UNIX
ENOVIA I-PLM Business
Process applications
LANG = C with OS-level
Parameter UTF-8
Windows/UNIX
Italian
28
ENOVIA Live Collaboration Installation Guide
German
Component
Live Collaboration Kernel
Lang Setting
Platform
Studio Modeling Platform
LANG = DE
Windows/UNIX
Web Navigator
LANG = C if supporting more
than 2 non-English languages
Or
LANG = DE
Windows/UNIX
ENOVIA I-PLM Business
Process applications
LANG = C with OS-level
Parameter UTF-8
Windows/UNIX
Japanese
Component
Live Collaboration Kernel
Lang Setting
Platform
Studio Modeling Platform
LANG = JA
Windows/UNIX
Web Navigator
LANG = C if supporting more than
2 non-English languages
Or
LANG = JA
Windows/UNIX
ENOVIA I-PLM Business
Process applications
LANG = C with OS-level
Parameter Shift_JIS on Windows
and UTF-8/EUC on UNIX
Before you configure and deploy
the ENOVIA Live Collaboration
Server in Japanese, please see
Windows/UNIX
Configuring a Japanese Web
Environment in Chapter 19.
Korean
Chapter 2: Language Support
Component
Live Collaboration Kernel
Lang Setting
Platform
Studio Modeling Platform
LANG = KO
Windows
Web Navigator
LANG = C
Windows
ENOVIA I-PLM Business
Process applications
Not Supported
Not Supported
29
Simplified Chinese
Component
Live Collaboration Kernel
Lang Setting
Platform
Studio Modeling Platform
LANG = ZH_CN
Windows
Web Navigator
LANG = C
Windows
ENOVIA I-PLM Business
Process applications
Not Supported
Not Supported
Component
Live Collaboration Kernel
Lang Setting
Platform
Studio Modeling Platform
LANG = ZH_TW
Windows
Web Navigator
LANG = C
Windows
ENOVIA I-PLM Business
Process applications
Not Supported
Not Supported
Traditional Chinese
Multiple Language
Support
If you must support more than 2 non-English languages, you must use the LANG=C
setting. In addition, your database (Oracle or DB2) and application/collaboration server
must be configured for UTF8. If your data will be in multiple languages, your browser
must have the appropriate language support.
Refer to Localizing ENOVIA Live Collaboration in Chapter 9 for additional information.
30
ENOVIA Live Collaboration Installation Guide
3
Installing an Oracle
Database
Installing the Database Software
This chapter describes setup requirements and guidelines for configuring Oracle for use
with ENOVIA Live Collaboration. You have three choices when installing Oracle and
ENOVIA Live Collaboration, you can install:
•
As a stand-alone system, where the client and server machines are the same. In this
case, the Oracle server software is installed.
•
In a networked environment, with a database server and multiple clients. You must
install the Oracle server software on the central server, if its a networked installation.
•
In a distributed environment, with multiple database servers accessed by clients in
several locations. The Oracle server software may be installed on multiple servers in
this configuration.
OracleInstantClient is included when ENOVIA Live Collaboration or the Live
Collaboration server are installed.
If you are upgrading from a prior version of ENOVIA Live Collaboration, refer to
Installing a New Version of Studio Modeling Platform in Chapter 7 for details. Oracle
settings may require temporary adjustments while upgrading the schema.
31
Installing the Oracle Server
Before installing the Oracle Enterprise server software, read this chapter in its entirety.
Then use the guidelines provided here in conjunction with the instructions provided by
Oracle. Supported platforms and software versions are shown in the Program Directory for
the given release.
Since Oracle is a very complex product, do NOT attempt to install it without the
appropriate installation guides, which are available from Oracle. In UNIX environments in
particular, variations in hardware and software require different approaches to be taken,
and these caveats have been the topic of many Oracle documents. However, some
important configuration guidelines are included in this chapter, some of which are not
platform specific. Also, for UNIX servers that must support non-English languages,
localization tips are provided in the section, Configuring Oracle for Non-English
Languages. Setup procedures for installations that will require support for non-English
languages must be executed during initial installation.
32
ENOVIA Live Collaboration Installation Guide
Configuring the Oracle Server for Use with
ENOVIA Live Collaboration
Once the Oracle Server software is installed, the database must be created and configured
to run effectively with ENOVIA Live Collaboration software. Since every installation is
different, it is difficult to provide an exhaustive list of specific changes that must be made.
We recommend that you consult an Oracle-trained DBA who has experience in Oracle
tuning to properly configure and tune large databases. However, certain adjustments are
universal and some of these adjustments are listed in the sections that follow.
An overview of creating an Oracle database for ENOVIA Live Collaboration purposes
involves:
1. Deciding which files go on which disk, and configuring the init<SID>.ora file
accordingly. Refer to Disk Layout Suggestions for recommendations.
2. Creating the base database using the settings in init<SID>.ora, defining a
character set, and establishing realistic values for MAXDATAFILES and
MAXLOGFILES.
3. Creating a default rollback segment which belongs to the system tablespace.
4. Creating the system/sys database views and tables.
5. Creating tablespaces and rollback segments.
6. Creating the user with appropriate rights.
Configuration procedures are provided in the sections that follow.
Chapter 3: Installing an Oracle Database
33
Designing the Database
ENOVIA Live Collaboration is a client of an Oracle database. The “ENOVIA database”
is a set of tables, constraints, indexes and database links owned by one Oracle user only.
This may also be referred to as the “ENOVIA Schema.”
First, create a very simple Oracle database comprised of a system tablespace, control files,
and redo logs. The control file holds the database limits, and so these must be established
when the database is first defined. So, before you create the ENOVIA database you must
decide the following:
•
The location and size of the system datafile.
•
The character set. This is covered in Configuring Oracle for Non-English Languages.
•
The location of the control files.
•
The location, number, and size of the redo logs. Redo logs are created with the
database, but may easily be dropped and recreated as required. Refer to Rebuilding
Redo Logs
Once the base database is established, you can configure, create and make adjustments to
tablespaces, datafiles, redo logs and rollback segments.
Control Files
Control files are created when the database is defined. These files control the physical
structure and status of the database. The CONTROL_FILES parameter in the
init<SID>.ora file establishes their location. Control files are like a master index of all the
redo logs and datafiles with status information. Each control file is a replica of the
other(s), providing crucial data redundancy in the event of disk failure. Configure a
minimum of three control files on separate disks, if disk mirroring is not being used.
Redo Logs
Redo logs record all transactions made to the database for recovery purposes. They are
essentially a transactional history log of all actions taken. The maxlogfiles setting
determines the maximum number of redo log files (or groups, if redundancy is used) that
may be defined. Redo logs are updated sequentially, with 3 to 5 typically existing at one
time. For example, first the system writes to log1, then to log2, log3... and then to log1
again. If archive logging is enabled, (recommended) the redo log file is copied off as an
“archive log” once it has reached its maximum size, or if some other event triggers a log
switch. This lets you restore a database from the last full backup to the present, essentially
“replaying” all the database transactions that have occurred. Redo logs are not tablespaces,
but rather are separate O/S level log files.
Redo log files may be duplicated on separate disks for data redundancy. The original and
all copies are known as a logfile group. The number of redo logs in a group is defined with
the maxlogmembers value which defaults to 2 during database creation. Most DBAs
will set 3 members to each group (each on a different disk if possible) for safety. However,
O/S and RAID mirroring may be used instead. Refer to the Oracle Server Administrator’s
Guide and the Oracle DBA Handbook for more information.
The maxlogfiles and maxlogmembers values must be set during database creation.
However the actual number of log files is determined by the log_files setting in the
init<SID>.ora file. If this setting exceeds the maximum value, only the specified
34
ENOVIA Live Collaboration Installation Guide
maximum number are allocated. If it becomes necessary to increase the maximum values,
the control file must be rebuilt. Refer to Rebuilding the Control File for more information.
If many transactions are to be performed, such as during dataloading, the size of the redo
logs should be adjusted. A default size might be10 MB, but this should be increased to
250 MB for certain circumstances which demand aggressive Oracle transactional
activities, such as when upgrading very large (1,000,000 object) databases. The rate of
switching between the redo logs can determine how much space to allocate for them. If
switching is very frequent the size should be increased so that they don’t switch more than
every 20 to 30 minutes. Refer to Installing a New Version of Studio Modeling Platform in
Chapter 7 for upgrade recommendations and procedures.
Tablespaces and
Datafiles
Oracle stores data in tables that are allocated to tablespaces. Each tablespace contains at
least one datafile. Several tablespaces are part of an ENOVIA Live Collaboration/Oracle
database:
•
SYSTEM - When Oracle is installed, this tablespace is created. It contains the catalog
information for all the schemas (or Users) within the database. The size of this
tablespace depends on if Oracle is used solely for ENOVIA, or if other applications
are also using the instance. To allow for upgrades to Oracle we suggest a size of
75 MB.
•
TEMP - Oracle requires a temporary workspace tablespace for performing functions
such as re-indexing a vault and performing certain queries. Also, Oracle sorts or joins
make use of this tablespace. ENOVIA Live Collaboration may perform joins, if a
foreign vault is in place (utilizing an Adaplet to another database).
•
ENOVIA - When the Enovia user is created, a tablespace is assigned to hold the
schema definitions defined by the Business Administrator. This is the tablespace
assigned to the Administration vault.
•
ROLLBACK - A tablespace that is dedicated to holding rollback segments should be
created.
•
VAULTS - Two tablespaces may be assigned during creation of each vault—one to
hold the index information and one to hold the data tables. If the tablespaces are not
specified in the definition, the user’s default tablespace is used. We recommend that
unique data and index tablespaces are assigned. These datafiles should be on separate
disk spindles, if in a non-raid system. While large vaults should have tablespaces
defined specifically for them, smaller vaults may share tablespaces with other smaller
vaults, but keeping the index and data of each vault separate.
Tablespaces are configured using SQL or Storage Manager with parameters that include
the initial size and the size to which they can grow.
Datafile Sizing
To determine datafile sizes for the vault tablespaces, consider the following:
•
How many business objects will this vault contain within one year? two years?
•
For the most commonly-used type, how may attributes, how large a description field,
and how much history will be retained per business object?
After large scale data loading, data to index size ratios are 1 to 1.5, but a vault re-index
will most likely make this ratio more of the order of 1 to 1.
Chapter 3: Installing an Oracle Database
35
With this in mind, our example scripts (shown in step 5 of the Creating the Database
procedure) presume that vault Vault1, which uses vault1-ts for data and
vault1-Its for index, will have 300,000 business objects after two years of dataload/
production usage. Assume the average business object takes 2 KB of data and 3 KB of
index space, so data files are created of size 600 MB for data and 900 MB for index.
Tablespace Extent Sizing
When ENOVIA Live Collaboration schema is first created, MX tables are created in
Oracle. MX tables derive their default storage size settings from the tablespace values.
Once in production, these tables probably will not grow large in size. Depending on the
number of program objects, and the complexity of the schema, the default ENOVIA Live
Collaboration User tablespace is not likely to exceed 60 MB.
When a vault is created, LX tables are created and their default storage values are also
derived from the tablespace values. Theses vault tables may experience dramatic growth.
You can run the validate upgrade command to determine how many of each type of table
exists in any version. It will output a list of all tables.
Oracle Corporation’s Tuning white papers offer some suggestions concerning extent
sizings:
1. Use initial and next size of 160k, 5120k, or 160m.
2. Use pct-increase of 0.
3. Ideally, no tables should have a very large number of extents.
One recommendation is that there should never be more than 10 extents per table.
So, initial = next = 160k is set for all tablespaces. However, examination of the LX tables
indicates that certain tables, such as LXOID (the master index of all vault OIDS), LXBO
(business object definition table), LXSTRING (string attributes), LXHIST (history table),
and possibly LXDESC, LXRO, LXFILE (description, relationship, and attached file
reference tables) experience growth. So for vaults which anticipate more than 10,000
business objects, ENOVIA suggests a next extent size of 5120k.
If a database has hundreds or thousands of extents per table, performance will be slow. An
Oracle export followed by a database re-creation (import) will help. Contact ENOVIA
Technical Support or the ENOVIA Infrastructure Team for advice.
Rollback
Segments
Rollback segments allow transactions to fail in such a manner that the database can be
restored to a condition it was in before the transaction was attempted. When a transaction
fails, the data contained in the rollback segment is re-inserted back into the database, thus
restoring its integrity. Once the transaction is “committed” or restored, the rollback
segment is flushed clean. Rollback segments are created in a tablespace dedicated for
them.
Since most ENOVIA Live Collaboration transactions are small, a segment size of 64 k will
cover most of them. The recommended extent size is 128k with a minimum of 10 extents.
However, there are some conditions, such as during ENOVIA Live Collaboration upgrades
or a business definition modification that is widely referenced, that may require a large
rollback segment.
36
ENOVIA Live Collaboration Installation Guide
A rule of thumb is that there should be one rollback segment for every ten concurrent
users. Either the “Storage Manager” or “SQL*Plus” may be used for this purpose. Once
created, all new rollback segments must be identified in init<SID>.ora, as described
below.
For large scale concurrent systems (500+processes) rollback segments might be spread
across multiple tablespaces on different spindles. This is known as striping the rollback
segments.
Indexing
The section contains general information about Oracle indexing in an ENOVIA Live
Collaboration environment.
B-Tree Indexes
ENOVIA Live Collaboration only uses B-tree indexes, which ensure that read
performance does not degrade as the base table grows. B-tree indexes expand and balance
very well over time, although deletions result in “browning” the index.
To maintain B-tree indexes:
•
Keep nesting levels to a minimum.
•
Perform regular maintenance operations to keep the indexes performing optimally.
Index Monitoring
Using the dynamic schema model feature, ENOVIA Live Collaboration has many indexes
for all possible schema configurations. Too many indexes will degrade write performance.
A better solution is to only operate with the actual indexes that are used.
To activate an index, use:
Alter index XXXX MONITORING USAGE
To de-activate an index, use:
Alter index XXXX NOMONITORING USAGE
To see whether the index has been used (selected in a parse tree) since the last ALTER
INDEX ... MONITORING USAGE statement was issued, query the USED column of the
V$OBJECT_USAGE dynamic performance view, for example:
select used from v$object_usage;
The exp/imp utility with the “indexfile” feature can be used to generate the entire index
schema DDL. Indexes can then be dropped, if they are not required and only recreated for
actual upgrades.
Index Rebuilding
To rebuild an index from an index, use the following dynamic SQL script. It can be safely
completed using the “online” option; any failures will not invalidate the existing index:
select 'alter index '||owner||'.'||index_name||' rebuild
tablespace'||tablespace_name||' online ;'
from dba_indexes
where owner = 'MATRIX_SCHEMA‘
Chapter 3: Installing an Oracle Database
37
Oracle Parameter
File: init<SID>.ora
The parameter file is a small text file that defines the Oracle instance. It contains a list of
Oracle instance configuration parameters, including database and instance defaults,
database limits, and the size of the System Global Area (SGA). The init<SID>.ora file also
specifies control files, archived log files, and trace files settings. The parameter file is only
read during instance startup, and the database does not write to it. If the file is modified,
the instance must be shut down and restarted to make the new version of the parameter file
effective.
Several initial settings in the Oracle init<SID>.ora file must be adjusted. The file is located
in the ORACLE_HOME/dbs directory. ORACLE_HOME is the path where Oracle was
installed, and <SID> is the server instance IDentification. For example, for a SID named
“orcl.” it would be called initorcl.ora. Notice that several options are provided for many
settings, with all but one “commented out” with a pound sign, “#.”
The sections that follow describe recommended settings. A sample file is shown at the end
of these sections.
If making changes using the Windows Instance Manager, be sure to right-click and choose
Export to File from the Stored Configurations menu or changes may not be written to the
O/S level file.
System Global Area
The System Global Area (SGA) is defined by three settings in the init<SID>.ora file:
•
DB_BLOCK_BUFFERS
•
SHARED_POOL_SIZE
•
LOG_BUFFERS
The SGA should be configured to use no more than 40% of the available RAM on a server
that is dedicated to the ENOVIA Live Collaboration/Oracle instance.The first setting is the
most important for ENOVIA Live Collaboration.
The DB_BUFFER area, defined by the product of DB_BLOCK_SIZE and
DB_BLOCK_BUFFERS is the key memory buffering cache for database transaction
activity. If you specify too small a value it will impact performance. The Oracle default of
200 is inadequate. A larger cache reduces the number of disk writes of modified data.
DB_BLOCK_SIZE should be set to match the system’s O/S block size value.
Considerable performance improvements have been noted when, for instance, Solaris
machines used 8k instead of 2k, and AIX used a DB_BLOCK_SIZE size of 4k to match
the O/S default of 4k.
Oracle should never use swap, otherwise performance will degrade. Too large a
DB_BLOCK_BUFFER value could induce memory paging or swapping.
SHARED_POOL_SIZE is the data dictionary library cache. A value of 9000000 is
suggested, but larger databases may want to use 15m.
So, for example, if a server for a large database had 256k of RAM, you could configure it
as follows:
db_block_buffers = 20000 (20000 x 4k = 80mb. Note that this is assuming a block
size of 4k at database creation.)
38
ENOVIA Live Collaboration Installation Guide
shared_pool_size = 9000000
log_buffers = 16384000
If this server will also run the Live Collaboration server, use a smaller SGA, reducing the
size of DB_BLOCK_BUFFERS only.
Identifying Rollback segments
All new rollback segments should be identified with the rollback_segments setting.
For example:
rollback_segments = r01, r02, r03, r04 (and so on...)
Rollback segments must first be created with the “Storage Manager” or SQL*Plus
applications.
You may also need to specify the maximum transactions per rollback segment. For Oracle
Version 10.x, use the following parameter:
transactions_per_rollback_segment = 32 (at a maximum)
Configuring for Concurrent Users
Adjustments should be made to the number of processes, open cursors, and dml locks
based on the number of concurrent users. Use these formulas as a guide for configuring:
processes= should be 5 times the number of concurrent users.
open_cursors sets the number of open cursors per process. 200 is suggested, but may be
scaled up as necessary.
dml_locks = should be 10 times the number of concurrent users
The number of threads in the Live Collaboration server should be included in the
“concurrent user” count for all settings.
Increasing the number of processes may require more semaphores to be created on some
UNIX servers. Refer to the Oracle installation guides for system configuration
requirements.
If Adaplets will used, the open_cursors setting should be 12 times the number of
concurrent users.
Configuring for Adaplets
When using an adaplet with a Live Collaboration server, the Oracle instance needs to be
able to support more sessions than the connection pool size. The following Oracle
parameters should be set in init<SID>.ora as follows:
sessions=200
processes=250
These values should be considered guidelines, but both should be set greater than the value
of MX_CONNECTION_POOL_SIZE, which is set in the enovia.ini file for the Live
Collaboration Server. The default value for MX_CONNECTION_POOL_SIZE is
determined by the Java heap size selected during installation of the Live Collaboration
server (on UNIX that is small = 10, medium = 20, large = 30).
Chapter 3: Installing an Oracle Database
39
Also note that when adaplets will be used, the open_cursors setting should be 12 times the
number of concurrent users. Refer to the Studio Federation Toolkit Adaplet Programming
Guide for details.
Log Settings
LOG_CHECKPOINT_INTERVAL is defined as:
Redo Log Size
------------------------------------O/S block size
1
× -------------------------------------------------------------------------------------------------------------Number of Checkpoints desired per redo log
So, for a 10m redo log, an O/S block size of 2k, and 2 checkpoints per redo log, we have:
10240000 1
log_checkpoint_interval = ------------------------ × --- = 2500
2
2048
Given that the redo is really used for recovery, Oracle increments a Sequence Change
Number (SCN) with each checkpoint write. So, if you need to recover a database, having
multiple SCNs per redo log permits recovery to any SCN.
For dataload or upgrade conditions, consider setting the
LOG_CHECKPOINT_INTERVAL to a large number (such as 4096000), essentially
disabling the SCN write and tuning the database for performance.
The log buffers writes to the redo every 3 seconds or at 33 percent fill of the log buffer. It
is essential that the sum of the sizes of the redo logs exceeds the log buffer size. This
means that a 16mb log buffer demands redo logs larger than the Oracle defaults of 500k /
1m.
A redo log switch rate of 20 to 30 minutes is recommended for a production system.
Archive Logging
Although not documented in our sample init<SID>.ora file below (which is shown for
creation purposes) in production mode, archive logging is highly recommended. The
following settings may be added to the initialization file:
log_archive_start = true
log_archive_dest = directory path for Archive logs
log_archive_format = arch%S.arc (for example)
Refer to the Oracle Server Administrator’s Guide for discussion of these and other
settings. For instance, to enhance archiving performance consider setting:
log_archive_buffers = 2
However, for writes to disk or fast tape, try a larger value. Oracle documentation provides
many more details.
Oracle Setup for ENOVIA Live Collaboration with
Case-sensitive Off
If you plan to work with ENOVIA Live Collaboration in a case-insensitive environment,
the Oracle database must be configured to use a function-based index by adding the
following to init<SID>.ora:
QUERY_REWRITE_ENABLED=TRUE
40
ENOVIA Live Collaboration Installation Guide
QUERY_REWRITE_INTEGRITY=TRUSTED
optimizer_mode = choose
If you have done some Oracle tuning, the optimizer may be in “Choose” mode. This is
acceptable as long as you calculate statistics regularly, since the system will use
cost-based optimizing if statistics are available. Refer to Oracle documentation for more
information on optimizer modes. Refer to the MQL Guide for more information on the
ENOVIA Live Collaboration casesensitive setting and recalculating statistics.
Sample init<SID>.ora file
A sample init<SID>.ora file is shown below, configured for 10 users.
db_name=GBOHTD01
instance_name=GBOHTD01
db_domain = world
service_names = GBOHTD01.world
db_block_size = 8192
# processes = 50
# processes = 100
# processes = 200
processes = 50
# SMALL
# MEDIUM
# LARGE
# ENOVIA Collaboration Platform 5 x concurrent
open_cursors = 220
cpu_count = 4
dml_locks = 100
# ENOVIA Collaboration Platform 10 x concurrent
control_files =
('D:\oracle\oradata\GBOHTD01\control01.ctl',
'D:\oracle\oradata\GBOHTD01\control02.ctl',
'D:\oracle\oradata\GBOHTD01\control03.ctl')
# Define directories to store trace and alert files
background_dump_dest=E:\oracle\admin\GBOHTD01\bdump
user_dump_dest=E:\oracle\admin\GBOHTD01\udump
core_dump_dest=E:\oracle\admin\GBOHTD01\cdump
#
#
#
#
#
Uncommenting the line below will cause automatic archiving if archiving has
been enabled using ALTER DATABASE ARCHIVELOG.
log_archive_start = true
log_archive_dest = %ORACLE_HOME%\database\archive
log_archive_format = "LOG%s_%t.ARC"
# ------------------------------------------------------------# db_file_multiblock_read_count = 8
Chapter 3: Installing an Oracle Database
# SMALL 8x8 = 64
41
# db_file_multiblock_read_count = 16
# db_file_multiblock_read_count = 32
db_file_multiblock_read_count = 8
# db_files
# db_files
# db_files
db_files =
= 80
= 400
= 1000
300
# SMALL
# MEDIUM
# LARGE
# INITIAL
db_cache_size= 25165824
# shared_pool_size
# shared_pool_size
# shared_pool_size
shared_pool_size =
# ENOVIA Collaboration Platform
= 11534336
= 3500000
= 5000000
50000000
#
#
#
# ENOVIA Platform
log_checkpoint_interval = 10000000
# log_buffer
# log_buffer
# log_buffer
log_buffer =
# MEDIUM 4x16 = 64
# LARGE 2x32 = 64
# INITIAL
= 8192
= 32768
= 163840
163840
# audit_trail = true
timed_statistics = true
max_dump_file_size = 10240
LARGE
SMALL
MEDIUM
50 percent memory
# ENOVIA Platform 100000x512
# SMALL
# MEDIUM
# LARGE
# ENOVIA Collaboration Platform
# if you want auditing
# if you want timed statistics
# limit trace file size to 5 Meg each
# If using public rollback segments, define how many
# rollback segments each instance will pick up, using the formula
#
# of rollback segments = transactions \ transactions_per_rollback_segment
# In this example each instance will grab 40\10 = 4:
# transactions = 40
# transactions_per_rollback_segment = 10
transactions_per_rollback_segment = 32
# ENOVIA Collaboration Platform
# Global Naming -- enforce that a dblink has same name as the db it connects to
global_names = TRUE
#
#
#
#
#
Edit and uncomment the following line to provide the suffix that will be
appended to the db_name parameter (separated with a dot) and stored as the
global database name when a database is created. If your site uses
Internet Domain names for e-mail, then the part of your e-mail address after
the '@' is a good candidate for this parameter value.
# db_domain = us.acme.com # global database name is db_name.db_domain
#
#
#
#
42
Uncomment the following line if you wish to enable the Oracle Trace product
to trace server activity. This enables scheduling of server collections
from the Oracle Enterprise Manager Console.
Also, if the oracle_trace_collection_name parameter is non-null,
ENOVIA Live Collaboration Installation Guide
# every session will write to the named collection, as well as enabling you
# to schedule future collections from the console.
# oracle_trace_enable = TRUE
remote_login_passwordfile = exclusive
#
# When installing the starter database, we can't have
# snapshot_refresh_processes or job_queue_processes set, since the
# 'alter database oracle character set ...' statements in createdb.sql will
# fail.
#
# job_queue_processes = 2
# The following parameters are needed for the Advanced Replication Option
# open_links = 4
# Optimizer tuning
compatible = '9.2.0.5.0'
cursor_space_for_time = true
session_cached_cursors = 12
hash_join_enabled = true
star_transformation_enabled = FALSE
java_pool_size = 0
large_pool_size = 0
query_rewrite_enabled = FALSE
# Disc/memory tuning
fast_start_mttr_target = 300
pga_aggregate_target = 52428800
# UNDO Tablespace
undo_management='AUTO'
undo_retention=1800
undo_tablespace='UNDO'
_b_tree_bitmap_plans=FALSE
Creating the
Database
Sample scripts for Version 9:
--- CREATE THE DATABASE (GBOHTD01)
-create database GBOHTD01
maxinstances
1
maxlogfiles
32
maxlogmembers
3
Chapter 3: Installing an Oracle Database
43
maxdatafiles
150
character set
AL32UTF8
datafile 'D:\ORACLE\ORADATA\GBOHTD01\SYSTEM01.DBF' size 150M
logfile group 1 ('D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO01a.rdo',
'D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO01b.rdo') size 5M,
group 2 ('D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO02a.rdo',
'D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO02b.rdo') size 5M,
group 3 ('D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO03a.rdo',
'D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO03b.rdo') size 5M,
group 4 ('D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO04a.rdo',
'D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO04b.rdo') size 5M,
group 5 ('D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO05a.rdo',
'D:\ORACLE\ORADATA\GBOHTD01\REDO\REDO05b.rdo') size 5M
undo tablespace UNDO datafile 'D:\ORACLE\ORADATA\GBOHTD01\undo01.dbf' size 200M
;
--- SET THE CORRECT ORACLE HOME HERE --@E:\oracle\ora92\rdbms\admin\catalog.sql
@E:\oracle\ora92\rdbms\admin\catproc.sql
connect system/manager
@E:\oracle\ora92\sqlplus\admin\pupbld.sql
--- GENERAL TABLESPACES
-create temporary tablespace TEMP
tempfile 'D:\ORACLE\ORADATA\GBOHTD01\TEMP01.DBF' size 100M
extent management local
;
--- ENOVIA Collaboration Platform SCHEMA TABLESPACES
-create tablespace ITTEST
datafile 'D:\ORACLE\ORADATA\GBOHTD01\ITTEST_DATA01.DBF' size 160M REUSE AUTOEXTEND ON
NEXT 1M
extent management local
segment space management auto
;
create tablespace ITTEST_IDX
datafile 'D:\ORACLE\ORADATA\GBOHTD01\ITTEST_IDX01.DBF' size 160M REUSE AUTOEXTEND ON
NEXT 1M
extent management local
segment space management auto
;
--- BAT SCHEMA TABLESPACES
-create tablespace GSP_DATA
datafile 'D:\ORACLE\ORADATA\GBOHTD01\GSP_DATA01.DBF' size 100M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
44
ENOVIA Live Collaboration Installation Guide
;
create tablespace GSP_IDX
datafile 'D:\ORACLE\ORADATA\GBOHTD01\GSP_IDX01.DBF' size 100M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace BEG_DATA
datafile 'D:\ORACLE\ORADATA\GBOHTD01\BEG_DATA01.DBF' size 150M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace BEG_IDX
datafile 'D:\ORACLE\ORADATA\GBOHTD01\BEG_IDX01.DBF' size 150M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace CLARITY_DATA
datafile 'D:\ORACLE\ORADATA\GBOHTD01\CLARITY_DATA01.DBF' size 200M REUSE AUTOEXTEND ON
NEXT 1M
extent management local
segment space management auto
;
create tablespace CLARITY_IDX
datafile 'D:\ORACLE\ORADATA\GBOHTD01\CLARITY_IDX01.DBF' size 200M REUSE AUTOEXTEND ON
NEXT 1M
extent management local
segment space management auto
;
create tablespace SAM_DATA
datafile 'D:\ORACLE\ORADATA\GBOHTD01\SAM_DATA01.DBF' size 250M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace SAM_IDX
datafile 'D:\ORACLE\ORADATA\GBOHTD01\SAM_IDX01.DBF' size 250M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace UM_DATA
datafile 'D:\ORACLE\ORADATA\GBOHTD01\UM_DATA01.DBF' size 100M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace UM_IDX
Chapter 3: Installing an Oracle Database
45
datafile 'D:\ORACLE\ORADATA\GBOHTD01\UM_IDX01.DBF' size 100M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace WMS_DATA
datafile 'D:\ORACLE\ORADATA\GBOHTD01\WMS_DATA01.DBF' size 170M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace WMS_IDX
datafile 'D:\ORACLE\ORADATA\GBOHTD01\WMS_IDX01.DBF' size 170M REUSE AUTOEXTEND ON NEXT
1M
extent management local
segment space management auto
;
create tablespace PRODSPEC_DATA
datafile 'D:\ORACLE\ORADATA\GBOHTD01\PRODSPEC_DATA01.DBF' size 100M REUSE AUTOEXTEND ON
NEXT 1M
extent management local
segment space management auto
;
create tablespace PRODSPEC_IDX
datafile 'D:\ORACLE\ORADATA\GBOHTD01\PRODSPEC_IDX01.DBF' size 100M REUSE AUTOEXTEND ON
NEXT 1M
extent management local
segment space management auto
;
-- create tablespace COPYEDCTEST
-- datafile 'D:\ORACLE\ORADATA\GBOHTD01\COPYEDCTEST01.DBF' size 160M REUSE AUTOEXTEND
ON NEXT 1M
-- extent management local
-- ;
--- CREATE THE ENOVIA Collaboration Platform USER
-create user ITTEST identified by MATRIX
default tablespace ITTEST
temporary tablespace TEMP
;
grant connect, resource to ITTEST
;
alter user ITTEST default role all
;
create user EJSADMIN identified by EJSADMIN
default tablespace SYSTEM
temporary tablespace TEMP
;
grant connect, resource to EJSADMIN
;
46
ENOVIA Live Collaboration Installation Guide
alter user EJSADMIN default role all
;
connect sys/change_on_install as sysdba
;
grant select on sys.v_$session to ITTEST
;
--- AMEND DBA USERS
-alter user sys temporary tablespace TEMP
;
alter user system default tablespace SYSTEM temporary tablespace TEMP
;
connect sys/change_on_install as sysdba
startup mount pfile=E:\oracle\admin\GBOHTD01\pfile\initGBOHTD01.ora
alter database archivelog;
alter database open;
alter system switch logfile;
drop rollback segment rb0;
shutdown;
startup
set pages 0
set feedback off
spool c:/temp/rebuild.sql
--- REDISTRIBUTE THE MATRIX SCHEMA INDEXES
-select 'alter index '||owner||'.'||index_name||' rebuild tablespace MATRIX_INDEX ;'
from dba_indexes
where tablespace_name = 'MATRIX_DATA'
and owner = 'MATRIX'
;
spool off
@c:/temp/rebuild.sql
exit
Oracle 10G
On Oracle 10G, the Automatic Statistics Gathering feature is enabled by default. The
Automatic Statistics Gathering feature allows Oracle to automatically gather statistics on
all database objects and maintains those statistics in a regularly-scheduled maintenance
job. This feature eliminates many of the manual tasks associated with managing the query
optimizer, and reduces the chances of getting poor execution plans because of missing or
stale statistics.
Also on Oracle 10g security has been tightened. The Connect role had some default
privileges deprecated. In order to create db links, you must specifically give the following
privileges to the Connect Role.
GRANT CREATE DATABASE LINK TO CONNECT;
GRANT CREATE PUBLIC DATABASE LINK TO CONNECT;
Chapter 3: Installing an Oracle Database
47
Also, you should grant the following:
GRANT UNLIMITED TABLESPACE TO ${USERNAME};
48
ENOVIA Live Collaboration Installation Guide
Configuring Oracle for Non-English Languages
ENOVIA Live Collaboration/Oracle users located across the globe that access a common
database need the ability to view and edit data using their preferred language and
territorial requirements. The setup for both Oracle servers and ENOVIA Live
Collaboration/SQL clients must be properly configured to meet these goals. This section
provides instructions for setting up ENOVIA Live Collaboration and Oracle to properly
display any character set.
Oracle uses an integrated national language architecture that supports national languages
and character encoding. More than one language can be used to view and update a single
database accessed by a broad spectrum of multilingual users. Language-dependent
features can be customized for a specific application, user, or organization. Since a mixed
environment of computer platforms may use different character-encoding schemes,
character data passed between the client and server must be converted.
Some ENOVIA Live Collaboration configuration may be required for use of decimal
characters other than a period. Refer to Localized Decimal Character Settings in
Chapter 20 for more information.
Choosing a
Character Set for
the Oracle Server
The Oracle install program supplies a value for the NLS_LANG parameter based on the
language selected for using the Oracle applications. The NLS_LANG setting is used to
determine how to display the text for both the server and client software. Oracle clients may
access a database specifying different character sets in their NLS_LANG setting, as long as the
database character set is equivalent to, or a superset of, these character sets.
The NLS_LANG variable uses the following format:
NLS_LANG = LANGUAGE_TERRITORY.CHARACTER_SET
Where:
LANGUAGE—Specifies the language and conventions for displaying of messages, day
name and month name.
TERRITORY—Specifies the territory and conventions for calculating week and day
numbers.
CHARACTER_SET—Controls the character set used for displaying text. This setting
during database creation controls the character set used for data storage.
It is important to differentiate between the character set used for storage and the one used
for display.
•
When the database is created, if you don’t specify a character set for the database, it
uses the one from NLS_LANG, and all character data stored will use this character
set. Once the database is created, the character set cannot be changed without
re-creating the database.
Currently, multiple languages can be supported in each of the following ways:
•
ENOVIA Live Collaboration/Oracle supported operating systems in any language
(including double-byte languages) can handle the native language and English at one
time, using the database character set that supports their native language.
•
English and Western European operating systems can concurrently support multiple
non-English, single-byte languages, using WE8ISO8859P15 for the database
character set.
Chapter 3: Installing an Oracle Database
49
•
Only an English operating system may be used to concurrently support more than one
double-byte language, or one double-byte language and another non-English
language, using UTF-8 (or also AL32UTF8 and AL32UTF16) for the database
character set.
In any of these scenarios, clients then set their NLS variables to handle the conversion for
their language and territory.
Establishing the Character Set for the Server and Client
The default language setting of Oracle is American English. If you accept the default
language on Windows, NLS_LANG is set to:
AMERICAN_AMERICA.WE8ISO8859P1
While this character set, WE8ISO8859P1,does support both English and Western
European characters, it does not support the Euro symbol. The character set that does
support the Euro is WE8ISO8859P15.This should be used for all English and Western
European server’s and clients. You can select other languages for viewing the software by
clicking Product Languages from the Available Product Components page. Choose the
languages needed for the DBA.
Establishing the Character Set for the Database
After Oracle products are installed, the ENOVIA Live Collaboration database (user) must
be created with the language parameters defined properly. After the server is installed, the
Oracle Database Configuration Assistant is used to create the database. If you choose
Custom for the type of database, you can change the character set on the page where you
set the DB name and SID. For English and Western European operating systems that
support it, you should use UTF-8, AL32UTF8, or AL32UTF16).
You can also use a script to create the database. For example:
create database MATRIX
datafile 'd:\oradata\matrix\sys1matrix.ora'
logfile 'd:\oradata\matrix\log1matrix.ora'
'd:\oradata\matrix\log2matrix.ora'
'd:\oradata\matrix\log3matrix.ora'
maxdatafiles 255
noarchivelog
character set UTF8;
size
size
size
size
60M
2M,
2M,
2M
Once the database has been created with a character set other than the default, the Oracle
owner’s server startup file must have the environment set as follows:
ORA_NL32 = $ORACLE_HOME/ocommon/nls/admin/data
NLS_LANGUAGE = German (optional)
NLS_TERRITORY = Germany (optional)
NLS_LANGUAGE and NLS_TERRITORY are optional. They should be set to the language
preferences required by the System Administrator responsible for the Oracle server, and
only need to be set if different from the settings in the database.
LD_LIBRARY_PATH = $ORACLE_HOME/lib:/usr/openwin/lib:/usr/dt/lib:
ORACLE_HOME =
ORACLE_SID =
50
ENOVIA Live Collaboration Installation Guide
ORACLE_TERM = vt100 (supported Oracle terminal windows are listed in the Oracle
installation manuals for specific platforms.)
If possible, match the ORACLE_TERM to the UNIX shell window defined in the user’s
.cshrc or .profile. Many display errors are due to new shells being created without using
the appropriate Oracle startup parameter file.
As with all UNIX environment variables, be sure to export them. For example:
$ export NLS_LANGUAGE, NLS_TERRITIORY, ORA_NL32, NLS_LANG,
LANG, LC_ALL, LD_LIBRARY_PATH, ORACLE_HOME, ORACLE_SID,
ORACLE_TERM, SCRHOME, TERM, PATH
Loading Language
Message Libraries
on UNIX
Additionally for UNIX servers, you have the option of loading all available language
message libraries during installation.UNIX platforms rely on message libraries compiled
for specific UNIX platforms to display Oracle messages for all Oracle products. Loading
all languages will load all compiled font message files for that specific UNIX platform
during installation. Select all languages when installing, if adequate space is available. If
an additional language message file is required after the UNIX server has already been
installed, Oracle must be completely reinstalled and configured since the message files for
each Oracle product are located in the product itself. Also, note that the last message file
library loaded will be the default language for viewing.
Selecting “all languages” upon installation is a recommended because if an additional
language message file is later required, Oracle must be completely reinstalled and
configured.
Chapter 3: Installing an Oracle Database
51
Disk Layout Suggestions
There are two ways to look at disk layout vis-à-vis optimizing the Oracle database and the
ENOVIA Live Collaboration for I/O performance and availability:
•
Method #1: Multiple disks, multiple disk spindles.
•
Method #2: Multiple disks plus Raid Arrays.
•
Method #3: Advanced Storage devices using large scale write buffer caches.
There are multiple Oracle processes that involve writing to disk:
1. DBWR—writes data from the database buffer cache to the database datafiles; that is,
to the ENOVIA Live Collaboration user datafile, to the data, and index datafiles.
2. DBWR—will also write rollback data to the rollback datafile, also any temp/system
datafile updates.
3. LGWR—writes data from the log buffer to the redo log files (possibly mirrored).
4. ARCH—if enabled, will copy off redo logs at redo log switch time only.
In addition, ENOVIA Live Collaboration may involve a write to local disk for FTP/NFS
file transfer as part of file checkin/checkout transactions, if stores are locally configured.
So, for a fully-used production system, as transaction updates are made continuously by a
large pool of people, or during dataload, parallel writes to disk for vault datafile, index
datafile, redo log and rollback datafile occurs. Temp datafile updates may also occur. The
diagram below shows all possible write transactions.
52
ENOVIA Live Collaboration Installation Guide
4 to 7 Disk System
In the past, Oracle/ENOVIA Live Collaboration would have requested a 4-7 disk system
with multiple drive spindles to optimize a large scale production database. Datafiles might
have been configured as follows across multiple disks:
•
Disk1: OS/Oracle/ENOVIA Live Collaboration installation—init files, system, temp,
rollback datafiles
•
Disk 2: Data datafiles, control file1, ENOVIA Live Collaboration user default
tablespace datafile
•
Disk 3: Index datafiles, control file 2
•
Disk 4: Redo logs
•
Disk 5: Mirror of redo logs, control file 3
•
Disk 6: Archive log files, backup data disk
•
Disk 7: Captured store data (ftp/nfs checked-in data referenced by Oracle metadata)
This is still a very valid and optimal solution, assuming a capable backup strategy. The
problem is there is vulnerability to single disk failure. Note that the most important choice
is to choose multiple disks and multiple spindles rather than one large disk.
Disk Layout
Example (Vault
Sizing)
This example shows:
•
How to size the Oracle datafiles for projected ENOVIA Live Collaboration growth
•
How to optimize the disk layout for optimal Disk I/O performance and really how to
minimize contention of hot disk read and write needs of the application’s hot table
indexes and tables.
This example assumes a projected migration of 2TB of attached File Store data might
translate down to something at upwards of 4,000,000 business objects in this database.
This estimate presumes an average file size of 500K.
The average business object sizes range from 2k - 20k depending on six independent
variables but a good guide is to presume that production systems should plan for an
average business object size of 10k.
This leads to the suggestion that the production system could be sized between 60-75g.
The Development System will not reach this size, but the database could be installed with
these initial tablespace structures:
Name
Description
Value
MATRIX_TS
Admin Tables (Lesser) Vault Tables
500m
MATRIX_ITS
Admin Indexes (Lesser) Vault Indexes
500m
DB45_TS-
DB45 (Major Vault) Tables
4g
DB45_ITS
DB45 (Major Vault) Indexes
4g
Chapter 3: Installing an Oracle Database
53
The Production and Test systems may need specialized growth tuning considerations
including ‘large and hot’ object datafile isolation with further tablespaces:
Name
Description
Value
DB45_STRING_DATA
DB45 String Tables
10g
DB45_STRING_INDEX
DB45 String Indexes
10g
DB45_RO_DATA
DB45 Relationship Tables
2g
DB45_RO_INDEX
DB45 Relationship
Indexes
2g
DB45_HIST_DATA
DB45 History Table
10g
DB45_HIST_INDEX
DB45 History Indexes
10g
DB45_BO_DATA
DB45 Bus. Object Tables
2g
DB45_BO_INDEX
DB45 Bus. Object Indexes
2g
Factor in an additional 10-15g for large Undo Tablespaces (imports and dataloads which
tend to stretch Undo)
For Development, however, assume that additional \large specialized tablespace structures
for uniquely large and hot objects are not required. So plan for the initial set of application
specific tablespaces and presume subsequent Oracle tuning will occur before any large
scale dataloading.
RAID Technology
54
RAID (Redundant Array of Inexpensive Disks) devices might be used to contain the
database and index tablespace data files to provide protection against disk failure.
Hot-swapable RAID 0+1 or perhaps a RAID 5 device with large buffer cache are
recommended for the best combination of the write performance and downtime
prevention. Read performance will not usually be affected by RAID, as the database
should reside almost entirely within the server's memory (System Global Area). Redo logs
and Archived logs are accessed sequentially (usually for writes) and therefore are not
ideally suited for being placed on a RAID-5 device. Also, datafiles which belong to
temporary tablespaces and rollback segments should not be placed on a RAID-5 device.
ENOVIA Live Collaboration Installation Guide
Fault Tolerance and Data Availability with RAID
The following chart is designed to reflect the various RAID configurations and weigh the
benefits on a scale of 1-5 (5 being least desirable)
Independent
Disks
RAID 0
RAID 1
RAID 0+1
RAID 3
RAID 5
Random Read Access
2
1
2
1
5
1
Random Write Access
1
1
2
1
5
5
Sequential Performance
4
1
5
1
2
3
Data Protection
4
5
1
1
2
2
Cost of Redundancy
1
1
3
5
2
2
Chapter 3: Installing an Oracle Database
55
The benefits and drawbacks of each RAID configuration are spelled out in the table that
follows.
Description of RAID arrays
RAID supplies fault tolerance and improves data availability
RAID 0
RAID 1
RAID 0+1
RAID 2
RAID 3
RAID 4
RAID 5
Striped disks
(speed)
Mirrored disks
(reliable
redundancy)
Striping plus
Mirroring
Provides check
disks with data
'bit-striped'
across data
and check
disks
Parallel data
transfer
Block or sector
striping is done
on the data
disks, allows for
multiple
unrelated
sectors to be
read
simultaneously.
Distributed data
and parity
•
•
•
•
•
•
Used for
transaction
processing
systems
•
•
Write
operations
can
become a
bottleneck
Allows for
multiple
read and
write
operations
simultaneo
usly
•
Can have
poor
random
write
performanc
e
•
Transfer
rate and
read
transaction
rate scale
with the
number of
drives
•
•
Excellent
sequentia
l transfer
rate
performa
nce and
very
good
transactio
n rate
performa
nce
No
redundan
cy
Low cost
•
•
Fully
redundan
t copy of
data on a
second
disk
Doubles
the cost
of
storage
Both
drives
can be
used for
reads to
improve
performa
nce
•
•
Excellent
random
write and
transfer
rate
performa
nce
Suitable
for
all-aroun
d
performa
nce and
reliability
Expensive,
d
ata is
completel
y
duplicate
d
•
Detects
and
corrects
single bit
errors,
detects
double
bit errors
Check
disks
consume
30% of
the total
disk
array,
complex
to
impleme
nt
•
A parity
disk is
used for a
group of
drives,
the data
written to
the disk
array is
bit-stripe
d across
the data
disks
Reduces
overhead
for check
disk,
consumes
20% of
the total
array
space
Common RAID selections
•
RAID 0+1 for best protection and high transaction rates, most expensive.
•
RAID 5 for excellent protection, but willing to sacrifice possible loss in write
performance, has excellent read performance.
So, with a RAID system the Oracle/ENOVIA Live Collaboration configuration solution
may be as follows:
56
•
Raid 0+1: Data/Index datafiles, ENOVIA Live Collaboration User datafile, System
datafiles, control files, Oracle/ENOVIA Live Collaboration installation, Rollback
datafile
•
Raid 1: Redo Logs, Temp tablespace
ENOVIA Live Collaboration Installation Guide
Other Disk
Solutions
•
Raid 1: Captured store data
•
External Disk: Backup disk, archive logs
EMC, IBM, and Sun have been exploring alternate disk storage solutions at the high end
for some time. Some newer lower cost solutions have come to market recently that some
customers have explored including Auspex fileservers, Solaris NFS storage devices,
Network Appliances storage devices, and Oracle's Raw Iron solution to name but a few.
These solutions typically have a very large write cache or minimal OS overhead, ensuring
extremely fast writes and disk failure handling capacity. For large scale captured data
storage, these solutions perform extremely well in tandem with Oracle Windows and
UNIX systems. In addition to fast read/write access, high availability of disk, they also
provide new and very fast techniques for data backup, frequently without requiring
downtime.
Most of these solutions will directly support an Oracle installation. We recommend you
download white papers from the vendors' Websites for more detailed information on each
solution. Note this area is in transition—it is unclear at this time if one solution maintains
a distinct advantage over any other.
Chapter 3: Installing an Oracle Database
57
Reconfiguring Oracle
Many settings may be adjusted in the init<SID>.ora file. This file and certain settings are
discussed in Oracle Parameter File: init<SID>.ora. But for more complete information,
refer to Oracle documentation.
The section provides guidelines for common Oracle reconfiguring tasks, which should be
performed only after fully understanding what the task is accomplishing.
Rebuilding the
Control File
Most adjustments to an Oracle configuration can be made by editing a value in the
init<SID>.ora, and then stopping and restarting the DB so that the value is incorporated.
However, certain settings can only be modified by recreating the database or by recreating
the control files. These settings include maxdatafiles, maxlogfiles,
character_set, db_block_size, and maxlogmembers.
The settings for maxlogfiles and maxdatafiles are upper limit values. However,
actual values may be adjusted on the fly in init<SID>.ora using db_files or
max_log_members, but they are clamped by the upper limit set at controlfile/
database-creation time.
Before rebuilding the control file, generating a complete backup of the entire system is
highly recommended. Also, be sure all users are logged off before proceeding.
For background and more complete information, refer to the Oracle Server
Administrator’s Guide and the Oracle DBA Handbook.
To reconfigure a control file:
1. Open SVRMGR, SQL*Plus, or SQL Worksheet and log in as Oracle dba (e.g. system/
manager).
2. Generate the list of current controlfile parameters using the following command:
alter database DBNAME backup controlfile to trace;
where DBNAME is the name in the init<SID>.ora file. For example:
alter database MATRIX backup controlfile to trace;
This results in the most current .trc file in the \orant\rdbms73\trace directory being
updated with the exact commands you will need to run. Open this file in a text editor.
3. Select the section that starts with STARTUP (NO)MOUNT and ends with the “;” after
the last datafile name. Copy and paste to a text file, adding a “;” after the STARTUP
MOUNT. (Oracle left it out).
4. You may modify any of the MAX parameters, for example, MAXDATAFILES. You
may also add lines for character_set or db_block_size. Save the file.
Example of modified file:
STARTUP NOMOUNT;
CREATE CONTROLFILE REUSE DATABASE “ORACLE” NORESETLOGS
NOARCHIVELOG
MAXLOGFILES 32
MAXLOGMEMBERS 3
MAXDATAFILES 200
58
ENOVIA Live Collaboration Installation Guide
MAXINSTANCES 16
MAXLOGHISTORY 1600
LOGFILE
GROUP 1 ‘E:\ORANT\DATABASE\LOG2ORCL.ORA’ SIZE 10M,
GROUP 2 ‘E:\ORANT\DATABASE\LOG1ORCL.ORA’ SIZE 10M
DATAFILE
‘E:\ORANT\DATABASE\SYS1ORCL.ORA’,
‘E:\ORANT\DATABASE\USR1ORCL.ORA’,
‘E:\ORANT\DATABASE\RBS1ORCL.ORA’,
‘E:\ORANT\DATABASE\TMP1ORCL.ORA’,
‘E:\ORCLTEST\MATRIX\ORCL1MX.DBF’,
‘E:\ORCLTEST\MXDEMO\ORCL1MXD.DBF’,
‘E:\ORCLTEST\CUSTTEST\ORCL1MXC.DBF’,
‘E:\ORCLTEST\MXJUNK\ORCL1MXJ.DBF’
5. In server manager (MS DOS Command Prompt, svrmgr23) connect as the dba and do
a shutdown immediately.
Last Chance: At the OS level make sure you have backups of everything!
6. At the OS level delete your control file(s) as referenced in the initialization file.
7. In server manager, run the text file you modified and saved by typing:
@bldcontrol.sql
8. Once “statement processed” comes up, type:
alter database open;
9. Rerun the alter database backup controlfile command and verify the latest trc has any
new settings. Changed settings will be the last entry in the latest trc. The old entries
are there also, so be sure to look towards the end of the file.
10. Test connecting to Oracle with ENOVIA Live Collaboration and verify functionality
is restored.
Rebuilding Redo
Logs
Once you start tuning you may have to modify the size of and append redo logs. In the
$ORACLE_BASE/admin/SID/bdump/alert_SID.log file, the rate of switching of redo logs
should ideally be every 20-30 minutes. If at dataload time, you notice a switch rate of 30
secs/1minute, Oracle is poorly tuned. The solution is to increase the size (and possibly
number) of your redo logs. However you cannot resize a redo log, you may only drop and
recreate the log. Remember one redo log may have 2 or more members spread across
multiple disks.
A user with DBA privileges can perform these steps.
To drop and add a redo log:
1. Log into SQL*Plus as system or sys. Select your redo logs to determine how many,
which are current, etc. by typing:
"select * from v$log;" and
"select * from v$logfile;"
You cannot alter the current redo log.
Note whether you have one or more than one logmembers per redo log.
Chapter 3: Installing an Oracle Database
59
It is always suggested that you have at least 2 valid redo logs at all times. If you have only
2 redo logs, you should construct a new one before deleting one.
2. To drop a redo log, use a command similar to the following:
alter database drop logfile member
'c:\orant\database\log3orcl.ora';
alter database drop logfile
'c:\orant\database\log4orcl.ora';
alter database drop logfile member
'c:\orant\database\log2orcl.ora';
Note that the logfile is listed by path and filename, and the exact specification will
likely vary.
3. To add a redo log and/or member of a redo log, use something like:
alter database oracle
add logfile group 1 'g:\orant\database\redolog01.log'
size 10M reuse;
alter database oracle
add logfile group 3 'g:\orant\database\redolog03.log'
size 10M reuse;
alter database oracle
add logfile group 4 'g:\orant\database\redolog04.log'
size 10M reuse;
Note you must name the database (oracle), the group number, the log location and
size.
4. Now cycle through all the redo logs to make sure all are functional as follows:
alter system switch logfile;
select * from v$log;
select * from v$logfile;
alter system switch logfile; .....
If multiple log members exist in a group, they must be dropped and added as well.
60
ENOVIA Live Collaboration Installation Guide
Tuning and Statistics
After installing ENOVIA Live Collaboration, you should consider the following tuning
recommendations in order to achieve optimum performance:
•
In the init<SID>.ora file, increase the DB_BLOCK_BUFFERS setting to the size
appropriate for the Oracle server system. Refer to the Designing the Database topic in
this chapter, in particular the Oracle Parameter File: init<SID>.ora section.
•
Set the Oracle optimizer mode to “choose” by adding the following line to the
init<SID>.ora file:
optimizer_mode = CHOOSE
Choose mode allows Oracle to decide between rule-based or cost-based optimizing
depending on whether or not statistics are calculated on the tables used. With this
setting in place, you should calculate statistics regularly. (Statistics are required and
used for cost-based optimizing.) Ensure that other optimizer settings are also correct.
Refer to optimizer_index_caching and optimizer_index_cost_adj. Refer to Oracle
documentation for more information on optimizer modes.
•
Calculate statistics on all ENOVIA Live Collaboration tables by executing the
following MQL command:
<mql> validate level 4;
This forces the mode to be cost-based, since statistics will be available for every table,
and in most cases, performance is optimal. However, the validate level 4 command
should be run after any substantial data load operation, and periodically thereafter, in
order to update the statistics.
Depending on the nature the data, some large databases perform better using the
rule-based optimizer. If performance degradation is noticed after performing the above
tuning, try removing all Oracle table statistics by running an MQL validate level 2
command, which forces the use of the rule-based optimizer. Once you are running with the
rule-based optimizer, you should not calculate statistics again.
Oracle
Initialization
Parameters
This section describes common Oracle initialization parameters and their recommended
settings in a ENOVIA Live Collaboration environment. The initialization parameters are
found in the init.ora file.
_b_tree_bitmap_plans
This hidden parameter should be set to False. In Version 8i, this is False by default. In
Version 9i, this must be set to False.
compatible
Check and set this parameter to indicate the correct RDBMS version to ensure optimal
query plan performance. This is available in Versions 7.3, 8.x, 9.x, and 10.x.
Chapter 3: Installing an Oracle Database
61
cpu_count
Set this to reflect the correct number of available CPUs for this instance. Hyper-threading
on Windows can incorrectly define this parameter. It is important to correctly set this
parameter since many settings are derived from it. This is available in Versions 7.3, 8.x,
9.x, and 10.x.
cursor_space_for_time
This parameter lets you use more memory to get faster execution. It ensures maximum
reuse of SQL cursors. Sufficient memory must exist to enable this parameter to be set to
true. This is available in Versions 7.3, 8.x, 9.x, and 10.x.
db_block_checking
Make sure that this setting is set to false to prevent the 1-10% block verification overhead
occurring. This should only be set to true if data block corruption is suspected. Block
checking for the system table space is always on. This is available in Versions 8.1.7, 9.x,
and 10.x.
db_block_size
The value for this parameter can be 2K, 4K, 8K, 16K, or 32K. Because the ENOVIA
applications are OLTP systems, they achieve better performance with an 8K block size.
Smaller sizes tend to incur additional IO overheads. Larger values incur extra intra-block
locking (hot blocks). The only size recommended by ENOVIA is 8K. This is available in
Versions 7.3, 8.x, 9.x, and 10.x.
db_cache_advice
This parameter defines the primary database block buffer cache. Size this while
monitoring and maintaining a 95% hit ratio, thereby ensuring valuable real memory is not
wasted. The following script determines the buffer cache hit ratio:
SELECT ROUND ((1 - (phy.VALUE - LOB.VALUE - dir.VALUE) /
ses.VALUE) * 100,2) “CUMULATIVE CACHE HIT RATIO”
FROM $sysstat ses,
$sysstat LOB,
$sysstat dir,
$sysstat phy
WHERE
ses.NAME = ‘session logical reads’
AND
dir.NAME = ‘physical reads direct’
AND
LOB.NAME = ‘physical reads direct (lob)’
AND
phy.name = ‘physical reads’;
db_cache_advice is a new setting available in Version 8.1.7, 9.x, and 10.x. This is an
internal parameter so be careful when setting.
62
ENOVIA Live Collaboration Installation Guide
db_cache_size
This sets the size of the default buffer pool for standard block size buffers. Set this at least
between 500-750m, and perhaps more depending on the size of the physical RAM. This is
a setting available in Version 9i and above.
db_file_multiblock_read_count
This parameter is determined by the maximum disc IO transfer value of the underlying
operating system. If this value is not known, a good estimate for the transfer value would
be 64K.
With a transfer value of 64K, this parameter would be set to 8 based on the 8K block size
to ensure that Oracle generates optimum query plans. Incorrectly setting this parameter
could potentially cause non-optimal query plans to be generated (i.e. full table scans
instead of index look ups). Normally this parameter should be set between 8 - 16. It should
be set higher only if you are rebuilding indexes or performing bulk loading.
This is available in Versions 7.3, 8.x, 9.x, and 10.x.
Setting this value too large will have the effect of lowering the sort costs, permitting
Oracle to perform more sort merge joins. This is dependent on whether the underlying OS
can manage the IO transfer, which in most cases it cannot.
db_files
This parameter should correctly reflect the number of database files being used by the
Oracle instance. The default is 200, which should be more than adequate for an ENOVIA
Live Collaboration installation. This value should be looked into before designing the
database. Setting this value too high will waste space in the data blocks.
This is available in Versions 7.3, 8.x, 9.x, and 10.x.
db_writer_processes
This parameter should not be modified from the default value 1 without prior detailed
analysis. Only very intensive write applications should consider modifying this from the
default. More contention occurs with more writer processes, which can then impact on
overall write performance.
This is available in Versions 8.x, 9.x, and 10.x.
dml_locks
The setting should be based on 10 locks per concurrent user, so the formula is:
dml_locks = concurrent ENOVIA Live Collaboration users X 10.
This parameter applies for all applications within the instance.
This is available in Versions 7.3, 8.x, 9.x, and 10.x.
Chapter 3: Installing an Oracle Database
63
enqueue_resources
This setting should be allowed to derive from the “sessions” parameter.
fast_start_mttr_target
The default setting of zero will incur extra overhead while the system attempts to ensure
the instance is immediately recoverable. A more conservative estimate of 1800 (30
minutes) is a better value since it balances recoverability (Mean Time To Recover) with
the risks and likelihood of an associated instance crash.
This is available in Versions 9.2, and 10.x.
global_names
This parameter should always be set to False to ensure that multiple ENOVIA Live
Collaboration Server entries are possible.
This is available in Versions 7.3, 8.x, 9.x, and 10.x.
hash_join_enable
This should be set to False for queries that involve certain “Parts” operations using Version
9i and Matrix Version 10 and greater (this includes ENOVIA Live Collaboration
V6R2011x).
large_pool_size
This parameter sets the size in bytes of the large allocation pool. Use the default value.
This can be set to zero to prevent wasting valuable memory.
This is available in Versions 8.0.6, 9.x, and 10.x.
java_pool_size
Since ENOVIA Live Collaboration does not use the Oracle JVM, reduce this parameter to
the minimum setting (default 24M) and allow the memory to be used by other
components. The recommendation would be to set this to:
If SGA < 128M: 4m granule
If SGA > 128M: 16m granule
This is available in Versions 8.1.x, 9.x, and 10.x.
log_archive_max_processes
This parameter sets the maximum number of active archive processes. It should be left at
the default value, which is normally sufficient for most ENOVIA products. You should
only modify this parameter if the archive log configuration is insufficient to meet the
system throughput demands.
This is available in Versions 8.1.x, 9.x, and 10.x.
64
ENOVIA Live Collaboration Installation Guide
log_archive_start
This parameter starts the archival process on SGA initialization. Always set this to true for
a production environment. This will ensure that recoverability is possible after a system
crash. Archive log mode incurs additional overhead, and the performance baseline should
not be set too high initially by not setting this parameter from the onset.
This is available in Versions 7.3, 8.x, 9.x, and 10.x.
log_buffer
This parameter sets the redo buffer size. Set it to 256K. This is sufficient for most
applications provided redo log production does not become a bottleneck.
This is available in Versions 7.3, 8.x, 9.x, and 10.x
open_cursors
This parameters sets the maximum number of cursors per session. Set this parameter to
220. In reality the number of open cursors per user is significantly less, but the additional
overhead of the setting is minimal and sometimes needed by applications other than
ENOVIA Live Collaboration.
This is available in Versions 7.3, 8.x, 9.x, and 10.x
open_links
This parameters sets the maximum number of open links per session. Use the default value
4. This allows remote vaults/foreign adaplet vaults to be configured without errors.
This is available in Versions 7.3, 8.x, 9.x, and 10.x
optimizer_dynamic_sampling
Listed below are typical values and their affects:
0
Dynamic sampling will not be done.
1
Dynamic sampling will be done, provided that:
2 - 10
•
more that one table is involved in the query
•
some tables have not been analyzed and have no indexes
Perform more aggressive sampling while ignoring the above rule.
It is important to always ensure that Oracle statistic generation is complete. This means
there should not be any tables without statistics; therefore, set this value to 0. Options 2-10
cannot be recommended without first benchmarking the application.
This is available in Versions 9.2.x, and 10.x
Chapter 3: Installing an Oracle Database
65
optimizer_features_enable
This parameter should always be set to the current release unless other database
interaction warrants disabled features. This is unlikely in ENOVIA Live Collaboration
implementations.
This is available in Versions 8.x, 9.x, and 10.x
optimizer_index_caching
This parameter should be set to 99. Setting this parameter to 99 influences the optimizer to
assume index blocks will be found in the buffer cache 99% of the time. This parameter
should direct Oracle to favor indexes over full table scans.
This is available in Versions 8.x, 9.x, and 10.x
optimizer_index_cost_adj
This parameter should be set to 1. Setting this parameter to 1 would influence the
optimizer to effectively value index scans as 1% of their original cost. This parameter
should direct Oracle to favor indexes over full table scans.
This is available in Versions 8.x, 9.x, and 10.x
optimizer_max_permutations
Use the default value. Monitor this if you have hard parse counts. Since hard parse counts
account for high CPU usage on short-running queries, reducing this parameter can help
resolve bottlenecks.
Hard parse is very expensive in both terms of CPU used and in the number of latch gets
performed. An example of hard parse: If a new SQL statement is issued that does not exist
in the shared pool then it has to be parsed fully. Oracle has to allocate memory for the
statement from the shared pool, and check the statement syntactically and semantically.
If a session issues a SQL statement that is already in the shared pool and it can use an
existing version of that statement, this is known as a “soft parse”. The application has
asked to parse the statement.
optimizer_mode
This value should be “choose”. However, benchmark this parameter with all options
against an ENOVIA product (choose, all_rows, first_rows, first_n_rows). All these options
differ slightly in terms of generated query plans and it is impossible to predict which will
perform better for the entire application. Other applications operating within this instance
will also be effected by this parameter change.
This is available in Versions 7.3.x, 8.x, 9.x, and 10.x
pga_aggregate_target
This parameter sets the Target size for the aggregate PGA memory consumed by the
instance. Use this parameter to ensure that more control is established over PGA memory.
A starting setting would be 1GB. Using the SORT_AREA_SIZE parameter has difficulties
66
ENOVIA Live Collaboration Installation Guide
when considering large numbers of users. The actual setting depends on the operating
system but should be considerably less than the available real memory to avoid memory
swapping. This is a new setting available in Version 9i and above.
processes
This setting is the number of user processes allowed. This setting should be based on 5
sessions per concurrent user, as follows:
processes = concurrent ENOVIA Live Collaboration users X 5.
This parameter applies to all applications within the instance.
This is available in Versions 7.3.x, 8.x, 9.x, and 10.x
session_cached_cursors
This setting is the number of cursors to save in the session cursor cache. If sufficient
memory exists, use this parameter with a start point of 12. This parameter works with
cursor_space_for_time. The cursor hit ratio can be measured by:
select
to_char(100 * sess / calls, '999999999990.00') || ‘%’
cursor_cache_hits,
to_char(100 * (calls - sess - hard) / calls, '999990.00') || ‘%’
soft_parses,
to_char(100 * hard / calls, ‘999990.00’) || ‘%’ hard_parses
from
(select value calls from v$sysstat where name = ‘parse count (total)’),
(select value hard from v$sysstat where name = ‘parse count (hard)’),
(select value sess from v$sysstat where name = ‘session cursor cache
hits’)
This is available in Versions 7.3.x, 8.x, 9.x, and 10.x
sga_max_size
This parameter defines the maximum size of memory available to the SGA (buffer pool,
large pool, shared_pool, etc.). The individual components are then allowed to grow within
this available constraint. At least 1GB of physical RAM should be available after deciding
upon the SGA values. sga_max_size may either be derived from other settings or may
be explicitly set. If set, it would represent the upper limit of memory space up to which
db_cache_size, shared_pool_size and variable size contributors add up to. This
is a new setting available in Version 9i and above.
shared_pool_reserved_size
This parameter should be left to the default value of the shared_pool_size (5%).
This is available in Versions 7.3.x, 8.x, 9.x, and 10.x
Chapter 3: Installing an Oracle Database
67
shared_pool_size
This parameter defines the area for SQL use. Size this area while monitoring and
maintaining a high hit ratio thus ensuring valuable memory is not wasted. The following
script will determine the shared pool hit ratio. An approximate starting point would be
15M per user, with a suggested size of 150M in Version 9i and above. Do not size too large
and waste memory
This is available in Versions 7.3.x, 8.x, 9.x, and 10.x.
select
namespace,
gets,
gethits,
rethitratio
from
v$librarycache
timed_statistics
This parameter should always be set to true to ensure that whenever statistic analysis is
required it can be enabled without requiring an instance restart. The overheard associated
with this parameter is minimal.
This is available in Versions 7.3.x, 8.x, 9.x, and 10.x
trace_enabled
This parameter can be set to false on a production system to avoid tracing overhead. It
should only be set when insufficient information is being produced during a debugging
exercise. This is an internal Oracle parameter.
This is available in Versions 7.3.x, 8.x, 9.x, and 10.x
undo_management
Use UNDO management as opposed to rollback segments. This is enabled by setting this
parameter to AUTO. This method is far more efficient in managing “rollback”
information. Large rollback assignment is no longer an issue as this is now handled
through undo quotas (default unlimited). This is a new setting available in Version 9i and
above.
undo_retention
This parameter is only useful if the undo tablespace is sufficient to hold all active
transactions. If so, the default value of 15 seconds is normally sufficient. The amount of
undo available for use is determined by the size of the undo tablespace and not this
parameter. An approximate starting point for the UNDO tablespace would be 200M. This
is a new setting available in Version 9i and above.
68
ENOVIA Live Collaboration Installation Guide
workarea_size_policy
This setting is a policy used to size SQL working areas (MANUAL/AUTO). It should be
allowed to default and be derived from the pga_aggregate_target parameter.
This is available in Versions 9.x, and 10.x.
A note about
scalability and
performance
The issue of scalability comes down to the specific schema and functionality of the
implementation. An implementation may be able to support 4,000 concurrent users on a
certain hardware/software configuration, but on that same configuration they might not be
able to support another custom application with 500 concurrent users. Use of Web
Navigator means that the schema, the triggers, etc. are all custom and will scale at a
different rate than any other ENOVIA product implementation.
The approach to take is to find out what in the specific application uses a lot of resource
and re-architect it to be either more efficient, or offload it to a background process on
another server. If 500 users are utilizing 100% of the CPU, then either more CPU is
needed or the application needs to be more scalable. Inefficient use of APIs, complex
triggers that need to be executed frequently, and inefficient data modeling are common
sources of scalability issues. Database tuning including adding additional indices, is an
effective technique to improve performance and scalability simultaneously. Code and
design review specifically with an eye toward scalability is the recommended approach.
Chapter 3: Installing an Oracle Database
69
70
ENOVIA Live Collaboration Installation Guide
4
Installing a DB2 Database
Installing the Database Software
This chapter describes DB2 setup requirements and guidelines for configuring DB2 for
use with ENOVIA Live Collaboration. DB2 and ENOVIA Live Collaboration may be
installed:
•
As a stand-alone system, where the client and server machines are the same. In this
case, DB2 server software is installed, and there is no need to install additional
database client software, since it is a subset of the server software.
•
In a networked environment, with a database server and multiple clients. In a
networked installation, you must install the DB2 server software on the central server,
as well as the DB2 client software on each machine that will be running ENOVIA
Live Collaboration.
A corollary of this is the ENOVIA Live Collaboration Server, which is really just
another DB2 client. Web clients will then access data via the Web from the server,
without requiring further DB2 client software at the end user’s machine.
If you are upgrading from a prior version of ENOVIA Live Collaboration, refer to
Installing a New Version of Studio Modeling Platform in Chapter 7 for upgrade
procedures. DB2 settings may require temporary adjustments while upgrading the
schema.
71
Installing the DB2 Server
Before installing the DB2 Enterprise Edition software, read this chapter in its entirety.
Then use the guidelines provided here in conjunction with the instructions provided by
IBM. Supported platforms and software versions are shown in the Program Directory for
the given release.
Since DB2 is a very complex product, do NOT attempt to install it without the appropriate
installation guides, which are available from IBM. For a white paper on DB2 ESE
Windows installation, send a request to idsicc@fr.ibm.com
Once the DB2 software has been installed, you must create a database suitable for
enterprise use with ENOVIA Live Collaboration. While the following sections provide
guidance on some settings, it is strongly recommended that you consult with a DB2 DBA.
72
ENOVIA Live Collaboration Installation Guide
Code Set and Language Settings
The DB2 database must use the UTF-8 code set. This means that the default IBM-1252
code set must be changed during database creation. You cannot modify the code set on an
existing database. To determine what code set is in use, enter the following command from
the DB2 command line:
db2 get database configuration for DBNAME
You can then set the LANG environment variable to control the display of characters on
the server including decimal/comma separators in date and amount formats. On AIX, use
the setenv command to set the language for DB2. For example,
setenv LANG de_DE
will set the language in DB2 to German/Germany.
DB2 Database
Client
Configuration
Any Live Collaboration Server that is run with MX_CHARSET=UTF8 must also set
db2set DB2CODEPAGE=1208, which corresponds to UTF8. The db2set command should
only be run on machines that are running the Live Collaboration Server. The db2set
command is a DB2 registry command which sets the UTF-8 code set for all DB2 clients. If
you do not run this command, UTF-8 will be set as an environment variable for ENOVIA
Live Collaboration only. This command should not be run for thick clients. Thick clients
should use the default operating system character setting.
Query re-optimization
The following query re-optimization variable should always be set. This variable allows
real values to be queried when bind values are used in dynamic SQL statements. The
following is a prerequisite command that must be launched on the database:
db2
db2
Set
cli
db2
Chapter 4: Installing a DB2 Database
bind db2clipk.bnd collection NULLIDR1
bind db2clipk.bnd collection NULLIDRA
Query reoptimization to ALWAYS (SQL_ATTR_REOPT=4) with db
cfg:
update cli cfg for section SAMPLE using SQL_ATTR_REOPT 4
73
Using DB2 with ENOVIA Products
DB2 and ENOVIA
Products
Before using DB2 with ENOVIA products, it is useful to understand the following terms:
•
Table: the primary data structure in the database consisting of rows and columns.
ENOVIA products uses three kinds of tables: MX tables for General Administration
data, LX for vault data (see below), and IX tables for indexed attributes.
•
Index: the data structure in the database for accelerating access to data via indexing
columns on commonly accessed tables.
•
Vault: is an ENOVIA Live Collaboration specific organization of data. By default,
there are three Governance vaults called eService Production, eService Admin, and
eService Sample, and one VPM vault called vplm.
•
Tablespace: the physical storage area for database tables and indexes on the storage
bay or disk drive. For optimal performance, tables and indexes should be in separate
tablespaces.
File system caching should, in general, be disabled to avoid double caching of data on
both the file system cache by the operating system and in the bufferpool by DB2.
•
LONG and LONG RAW (also referred to as CLOBS and BLOBS): are special data
types in databases of large string or binary values. DB2 with ENOVIA products uses
CLOBS for comment fields and other very long strings. These objects are never
cached in the bufferpool so a dedicated tablespace should be used with file system
caching enabled.
•
Bufferpool: is the area in system memory where the database stores data that is
pulled in from tablespaces. Tablespaces are assigned bufferpools for caching data in
system memory. For performance reasons, frequently used data should be stored in
the bufferpool. An undersized or oversized bufferpool can have a negative impact on
performance.
ENOVIA Live Collaboration must remain case-sensitive when using DB2 databases.
To use DB2 with ENOVIA products
Be sure the following are done before attempting to use DB2 with ENOVIA products:
1. Create a DB2 database suitable for enterprise use. Refer to DB2 documentation and
Configuring DB2. It is highly recommended that you use automatic storage:
CREATE DATABASE NAME AUTOMATIC STORAGE YES ON /FS1/NAME/1,/FS2/
NAME/2,/FS3/NAME/3,/FS4/NAME/4 DBPATH ON /FS5/NAME USING
CODESET UTF-8 TERRITORY US PAGESIZE 32768;
Where Name is the name of the DB2 database you are creating.
Directories must exist BEFORE the database is created.
2. Run the following command (as the DB2 instance owner) to grant necessary
privileges to the USER-ID specified at bootstrap creation. You can alternatively create
and run a script to combine the commands in step 3, 4 and 5:
#PLMADMIN refers to the USER-ID provided at bootstrap creation. Change the
schema name and user name if necessary to match this USER-ID
db2 “GRANT CREATEIN, DROPIN, ALTERIN ON SCHEMA PLMADMIN TO USER
PLMADMIN WITH GRANT OPTION”
74
ENOVIA Live Collaboration Installation Guide
3. When DB2 is used with ENOVIA products, the administrative and schema
information (c-data) are stored in a default tablespace. An option is not provided to
choose an alternate tablespace. If you would like to store this information in a
tablespace other than the default, you must restrict the USE access of the USER-ID
provided at bootstrap creation to the default tablespace. When USE access is denied
to the default tablespace, DB2 will find an alternative tablespace to which the
USER-ID has USE access. This must be done before connecting to the DB2 database.
To revoke USE access to default tablespace:
REVOKE USE OF TABLESPACE USERSPACE1 FROM PUBLIC
4. Create specific bufferpools:
Bufferpool size is expressed in units of page size. For example, the values for the
USERTEMPBP bufferpool below mean 5000 pages at 32768 bytes per page or
156 MB. AUTOMATIC means the bufferpool is sized automatically but at a
minimum, it can be the specified page size.
CREATE
CREATE
CREATE
CREATE
BUFFERPOOL
BUFFERPOOL
BUFFERPOOL
BUFFERPOOL
USERTEMPBP SIZE 5000 AUTOMATIC PAGESIZE 32768;
TEMPBP SIZE 5000 AUTOMATIC PAGESIZE 32768;
MXBP SIZE 500 AUTOMATIC PAGESIZE 32768;
LXBP SIZE 35000 AUTOMATIC PAGESIZE 32768;
CREATE LARGE TABLESPACE LX_DATA PAGESIZE 32768 MANAGED BY
AUTOMATIC STORAGE
BUFFERPOOL LXBP
INITIALSIZE 5 G
INCREASESIZE 5 PERCENT
PREFETCHSIZE 32
NO FILE SYSTEM CACHING;
CREATE LARGE TABLESPACE LX_INDEX PAGESIZE 32768 MANAGED BY
AUTOMATIC STORAGE
BUFFERPOOL LXBP
INITIALSIZE 6 G
INCREASESIZE 5 PERCENT
PREFETCHSIZE 32
NO FILE SYSTEM CACHING;
GRANT USE OF TABLESPACE LX_DATA TO USER PLMADMIN WITH GRANT
OPTION;
GRANT USE OF TABLESPACE LX_INDEX TO USER PLMADMIN WITH GRANT
OPTION
The USERTEMPBP bufferpool is used for the USERTEMP tablespace. This
tablespace is used as overflow for large queries that do not fit in memory and need to
be temporarily stored to disk. TEMPBP is used for the system TEMPSPACE1
tablespace. MXBP id used for the MX tablespaces. LXBP is used for the LX
tablespaces. The size of the LXBP bufferpool in the example should be reviewed and
increased or decreased according to available system memory and tablespace size.
5. Create a user temporary tablespace. Use the following:
CREATE USER TEMPORARY TABLESPACE USERTEMP IN DATABASE PARTITION
GROUP IBMDEFAULTGROUP PAGESIZE 32768 MANAGED BY SYSTEM
USING ('/FS1/NAME/1/tmp5',
'/FS2/NAME/2tmp5',
'/FS3/NAME/3/tmp5',
'/FS4/NAME/4/tmp5')
EXTENTSIZE 32
Chapter 4: Installing a DB2 Database
75
PREFETCHSIZE 32
BUFFERPOOL USERTEMPBP
OVERHEAD 7.500000
TRANSFERRATE 0.060000
NO FILE SYSTEM CACHING
DROPPED TABLE RECOVERY OFF;
a ) Set a dedicated buffer pool for the temporary tablespace:
ALTER TABLESPACE TEMPSPACE1 BUFFERPOOL TEMPBP;
b ) Grant user rights:
GRANT USE OF TABLESPACE USERTEMP TO USER PLMADMIN WITH GRANT
OPTION;
6. Set DB2 registry variables:
DB2_USE_ALTERNATE_PAGE_CLEANING=ON
DB2_DIRECT_IO=
DB2_INLIST_TO_NLJN=NO
DB2_EVALUNCOMMITTED=ON
DB2_SKIPDELETED=ON
DB2_SKIPINSERTED=ON
DB2MAXFSCRSEARCH=1
DB2ASSUMEUPDATE=OFF
DB2_CORRELATED_PREDICATES
DB2_HASH_JOIN=
DB2ENVLIST=EXTSHM
DB2_MMAP_WRITE=OFF
DB2_MMAP_READ=OFF
DB2_PARALLEL_IO=*
7. Install the Studio Modeling Platform and generate the connection file (MATRIX-R
file), which connects ENOVIA products to the database.
8. Restart DB2 in order for the new settings to take affect.
9. Install the Live Collaboration Server. For details, see Chapter 8, Installing the Live
Collaboration Server.
10. Install Business Process Services. This creates the three Governance vaults: eService
Production, eService Admin, and eService Sample. If the tablespaces for Data and
Index were specified during the setup program, these will be used for the eService
Production vault. The eService Admin and eService Sample vaults are rarely used but
their data and indexes will always be in the USERSPACE1 tablespace. This location
is not optimal because indexes and data are combined. but this should not impact
performance because the vaults are rarely used.
11. Install any ENOVIA products you are using, for example ENOVIA Engineering
Central. This populates the LX Tables.
The vplm vault is created when the ENOVIA VPM Multi-Discipline Collaboration
Platform is installed. An IX table is created on each vault for the indexes enabled via
the MXINDEX table. If a tablespace was specified during setup, the vault is placed
there. An IX table is created on each vault for the indexes enabled via the MXINDEX
table.
76
ENOVIA Live Collaboration Installation Guide
The following tables for the eService Production and/or vplm vaults are usually large
enough that the data and indexes should be put in separate tablespaces:
MXPROPERTY, LXBO, LXBOOL, LXINT, LXHIST, LXOID, LXREAL, LXRO,
LXSTATE, LXSTRING.
Vplm and eService Production vault tables are placed in the LX_DATA tablespace but
the indexes are also placed here which is not optimal. The indexes should be created
in the index tablespace or the LX_INDEX tablespace. The IX indexed column must
be first in the QuerySpec for the IX table to be used.
Chapter 4: Installing a DB2 Database
77
Configuring DB2
This section contains suggestions for improving the performance of DB2 running
ENOVIA Live Collaboration. These suggestions are based on results from ENOVIA QA
labs. Your results may vary depending on your platform configuration.
Currently
Committed Mode
When Currently Committed (CC) mode is enabled, writers will no longer block readers.
CC mode greatly improves concurrency. By default, CC mode is enabled (cur_commit is
set to 2) in new DB2 9.7 databases and disabled (cur_commit set to 0) in databases created
using version DB2 9.5 or earlier.
It is highly recommended that CC mode is either enabled or allowed in DB 9.7 databases.
CC mode is enabled by setting cur_commit to 2 and allowed by setting cur_commit to 1.
When upgrading to DB2 9.7 from a previous version, you must manually enable or allow
CC mode.The DB2_SKIPINSERT and DB2_SKIPDELETED settings are obsolete in
DB2 9.7. When using DB2 9.5, DB2_SKIPINSERT and DB2_SKIPDELETED are set by
default.
Disk and I/O
Management
You should have separate storage for each of the following locations:
DB2 Database Storage
For optimal performance, automatic storage should be specified on the CREATE
DATABASE statement, which will spread data evenly over the specified data paths.
Automatic storage is implemented via the ON /path-1, … , /path-n clause shown below.
Use the following example as a guideline:
CREATE DATABASE <database name> ON /path-1, …,/path-n USING
CODESET UTF-8 TERRITORY US PAGESIZE 32768;
Data will be spread equally across all paths specified. Each path should be a file system
backed by separate storage disks, which spreads all data equally across all storage disks.
Database directory files will be placed on the first path in the list.
DB2 Logs Location
This is where DB2 logs all changes made to objects and their contents. The logfiles record
all completed (committed work) and any uncommitted work which has been written to
disk (this allows uncommitted work written to disk to be removed if a transaction rollback
occurs). If there is a failure in a transaction, DB2 uses these files to rollback the changes.
If DB2 crashes, DB2 will verify consistency using the log files. The default logfiles
location is in the <DB2 Datafile Location>, but you can change the location by issuing an
update database configuration for the variable NEWLOGPATH.
It is highly recommended that DB2 log files are placed on a file system dedicated to the
log, and backed by disk spindles dedicated to this file system. For example:
UPDATE DB CFG FOR dbname
USING NEWLOGPATH
/db2log
For AIX environments, logging performance will be further enhanced by mounting the
logging file system with the CIO attribute. For example:
78
ENOVIA Live Collaboration Installation Guide
mount -o cio /db2log
Configuration
Parameters
DB2 Database Manager (DBM) level configuration parameters
Database Manager configuration parameters affect the entire instance (all databases
running in that instance). The default parameters provide a reasonable starting point. They
can be changed if necessary via the DB2 command:
UPDATE DBM CFG USING parm_name parm_value
The DBM parameter settings can be viewed by the command:
GET DBM CFG
Alternatively, they can be viewed and changed in the Control Center. Right click on the
correct DB2 database in the left navigation pane and select “Configure Parameters.”
The following DBM configuration parameters are recommended for maximum
performance on industrial databases with millions of business objects:
Recommended
DBM Parameter
DB2 Default
Setting
More Information
update dbm cfg using
NUMDB 5
8
NUMDB: The maximum number of concurrent databases running on the
instance should be 1 in the production environment.
DFT_MON_BUFPOOL
ON
OFF
All Monitors should be set to ON. SORT Monitoring can be set to OFF
in very specific cases if it is causing overhead during large sort
operations.
DFT_MON_LOCK ON
OFF
DFT_MON_SORT ON
OFF
DFT_MON_STMT ON
OFF
DFT_MON_TABLE ON
OFF
DFT_MON_UOW ON
OFF
BACKBUFSZ 10240
1024
RESTBUFSZ 10240
1024
ASLHEAPSZ 64
15
ASLHEAPSZ is the buffer between the application and agent. It should
be set to handle the majority of the requests in a single send-and-receive
pair.
QUERY_HEAP_SZ
10000
1000
Only allocated when needed or on demand. The setting should be
increased to avoid issues with complex queries.
Chapter 4: Installing a DB2 Database
BACKBUFSZ, RESTBUFSZ: should be set to large values because they
are only allocated at backup and restore time. They should fit in
UTIL_HEAP_SZ.
79
DB2 Database (DB) level configuration parameters
Database configuration parameters are specific to each database. Most default values
represent a reasonable starting point, but unlike the DBM level parameters, some tuning of
these parameters may be expected.
•
By default, the Self Tuning Memory Manager (STMM) is enabled. The master DB
STMM configuration parameter SELF_TUNING_MEM is set to ON, and all
subsidiary DB STMM configuration parameters are set to AUTOMATIC. This results
in DB2 dynamically managing it's memory pools based on workload. If self tuning
memory is not desired, then issue:
UPDATE DB CFG FOR dbname USING SELF_TUNING_MEM OFF. If this is
done, then manual tuning of the subsidiary memory parameters will be required.
•
By default, several other non-memory parameters are also set to AUTOMATIC. DB2
sets values for these based on the hardware/OS environment, or otherwise selecting
what it thinks are reasonable values.
•
The following default values are typically not optimal and should be changed.
Following are suggested values, but may need to be tuned further:
UPDATE DB CFG USING LOGBUFSZ 2048
UPDATE DB CFG USING NUM_IOSERVERS 225
UPDATE DB CFG USING LOGFILSIZ 25000
UPDATE DB CFG USING LOGPRIMARY 30
UPDATE DB CFG USING LOGSECOND 10
The DB level configuration parameter settings can be viewed by the command:
GET DB CFG FOR dbname
Alternatively, they can be viewed and changed in the Control Center. Right click on the
correct DB2 database in the left navigation pane and select “Configure Parameters”
The following DM configuration parameters are recommended for maximum performance
on industrial databases with millions of business objects:
Recommended
DM Parameter
update
80
DB2 Default
Setting
More Information
db cfg for SAMPLE using
SHEAPTHRES_SHR
5000
AUTOMATIC
SORTHEAP 5000
AUTOMATIC
CATALOGCACHE_SZ
6000
-1
Depends on the number of database objects.
UTIL_HEAP_SZ
15000
5000
UTIL_HEAP_SZ is used by backup, restore, load, and runstats
operations. It can be set to a large value because it is only used when
required.
DFT_QUERYOPT 3
5
DFT_QUERYOPT 3: gives better results than the default value of 5.
Should be set to a fixed value on test environments to avoid decreasing
STMM during “sleep time.” This parameter can be set to AUTOMATC
on production environments where loading is almost constant.
ENOVIA Live Collaboration Installation Guide
Recommended
DM Parameter
DB2 Default
Setting
More Information
AUTO_MAINT OFF
ON
Should be set to OFF in test environments to avoid having it impact
performance measurements. It can be set in production environments.
CLOB Datatypes
You should separate Catalog objects and Application objects into separate buffer pools.
Review the IBM documentation on how to create and manage buffer pools effectively.
ENOVIA Live Collaboration makes extensive use of CLOB datatypes. These CLOB
columns are typically defined as having a maximum size of 2m.
LOBS and Buffer Pools
LOB datatypes do not flow through buffer pools. Since DB2 performs direct reads, DB2
buffering and memory pooling do not apply to these objects.
LOBS and Table Spaces
Currently, ENOVIA Live Collaboration stores CLOB data and non-CLOB data for a table
in the same tablespace. After installing ENOVIA Live Collaboration you might want to
alter (unload, drop, recreate and reload) the tables that contain CLOBs for performance
reasons.
DB2 tablespaces can either utilize OS file caching or bypass OS (Operating System) file
caching. Since all data, except for LOB and LONG VARCHAR, is cached in DB2 buffer
pools, it is generally recommended to avoid OS file system caching, since this results in
double memory buffering of data. By default, DB2 tablespaces (except temporary
tablespaces) do not use OS file system caching. However, since LOB and LONG
VARCHAR data do not pass through DB2 bufferpools, there may be a performance
advantage to allowing the OS to file cache this data.
To implement file caching for LOB and LONG VARCHAR data:
1. Create a tablespace which uses OS file system caching. For example:
CREATE TABLESPACE CACHETS FILE SYSTEM CACHING
CACHETS is the name of the tablespace.
2. For tables which have LOB or LONG VARCHAR columns, edit the schema DDL to
indicate that LONG data (LOB/LONG VARCHAR) should be placed in a separate
tablespace. Specify a tablespace which uses OS file system caching. For example:
CREATE TABLE ……. LONG IN CACHETS
3. Tables for which this change is done will have to be unloaded, dropped, recreated, and
reloaded.
Chapter 4: Installing a DB2 Database
81
Additional Performance Related Tasks
•
DB2 requires accurate statistics, obtained by invoking the RUNSTATS utility, to make
the proper access path decisions. By default, RUNSTATS is automatically invoked
periodically against highly active tables. Although, after initial database population, it
is recommended that statistics for all tables be updated with the following command:
REORGCHK
•
UPDATE STATISTICS ON TABLE ALL
Some tables/indexes may benefit from a periodic reorganization. Run the following
command to see which tables/indexes should be considered for reorganization. The
last column in the report will have one or more asterisk (*) instead of all dashes (-) if
a reorganization is suggested
REORGCHK
UPDATE STATISTICS ON TABLE ALL
A reorganization can be done via command line or via the control center (right click
on the desired table and select “Reorganize” or “Reorganize Indexes.“
•
The SQL statements with the longest total execution time (average execution time per
statement * number of executions of this statement) should be periodically examined
to ensure they have optimal access plans. Executing the following SQL statement will
show the top 10 SQL statements with the longest elapsed time:
To show the top 10 SQL statements with the longest elapsed time
1. Run the following script as the instance owner to enable monitoring, and if necessary,
change “db2inst1” below to the actual instance owner:
db2 attach to db2inst1
db2 update dbm cfg using dft_mon_stmt on
db2 detach
2. Run the workload for a period of time.
3. Execute the following query - increase the value 100 as needed to capture the entire
text of the statements
“select average_execution_time_s * num_executions as total_exec_time,
substr(stmt_text,1,100) as stmt from sysibmadm.top_dynamic_sql order by
total_exec_time desc fetch first 10 rows only”.
The Visual EXPLAIN tool can display the access paths for these statements as
follows: Using the Control Center, right click on the database> select Explain Query;
then paste one of the SQL statements obtained from the preceding query into the
window and press OK.
4. Run the following script as the instance owner to disable monitoring, and if necessary,
change “db2inst1” below to the actual instance owner:
db2 attach to db2inst1
db2 update dbm cfg using dft_mon_stmt off
db2 detach
SQL0429N LOB
locator limit
If you exceed the SQL0429N limit of concurrent LOB locators, the following error is seen
in mxtrace.log:
[IBM][CLI Driver][DB2/6000] SQL0429N The maximum number of
concurrent LOB locators has been exceeded. SQLSTATE=54028
82
ENOVIA Live Collaboration Installation Guide
Use the CLI patch to remove the problem:
Set the DB2 client parameter PATCH2=50:
For system wide change: set PATCH2=50 in db2cli.ini
For session wide change: db2 update cli cfg for section <session name> using
PATCH2 50
AIX Environment
If the DB2 server and the ENOVIA Live Collaboration Server are running on the same
AIX system, you may receive the following error:
[IBM][CLI Driver] SQL1224N A database agent could not be started
to service a request, or was terminated as a result of a
database system shutdown or a force command. SQLSTATE=55032
Severity:3 ErrorCode:1
To remove the problem:
Catalog the local node as remote and catalog the database to remote node.
Or
Set the AIX environment variable EXTSHM=ON
To use EXTSHM with DB2
1. In client sessions, export EXTSHM=ON
2. When starting the DB2 server:
export EXTSHM=ON
db2set DB2ENVLIST=EXTSHM
db2start
Chapter 4: Installing a DB2 Database
83
Sample DB2 Database Creation Script
In the following script is a sample and is meant to be used as an example.
-- bpj Modif substitute LX to MATRIX & PATH & subst 32K to 32768
set to OFF
& logarchmeth1
-- bpj 20090114 Remove NOT EXTENDED STORAGE & Add NO FILE SYSTEM CACHING & switch
USERTEMP to SMS & Modify BUFFERPOOL NAME
-- Minimum of 5 GB free disk space on $DatabasePath
-- Tablespaces for MX and LX tables segmented by DATA, INDEX, LONG
-- Separate Tablespace for MXPROPERTY (MXPROP and MXPROP_I for indexes) as this
table often contains >100k rows
DatabasePath=/Data/DB2/V6R2010
DatabaseName=V6R2010
DatabaseSchema=enovadm6
DatabaseBinariesPath=/opt/IBM/DB2/V9.5
CREATE DATABASE $DatabaseName AUTOMATIC STORAGE YES ON $DatabasePath/
1,$DatabasePath/2,$DatabasePath/3,$DatabasePath/4 DBPATH ON $DatabasePath/DBPATH
USING CODESET UTF-8 TERRITORY US COLLATE USING SYSTEM PAGESIZE 32768;
CONNECT TO $DatabaseName;
-- Smaller buffer pools all start at 200MB; large buffer pool for vaults starts at
2 GB
-- To calculate size : SIZE * 32768 / 1024 / 1024 in MB
-- Alternatives: Separate bufferpools for large LX tables, for the MXPROP
tablespace, etc.
CREATE BUFFERPOOL USRTMPBP SIZE 6400 AUTOMATIC PAGESIZE 32768 ;
CREATE BUFFERPOOL TEMPBP SIZE 6400 AUTOMATIC PAGESIZE 32768 ;
CREATE BUFFERPOOL MXBP SIZE 6400 AUTOMATIC PAGESIZE 32768 ;
CREATE BUFFERPOOL LXBP SIZE 64000 AUTOMATIC PAGESIZE 32768 ;
DISCONNECT current ;
CONNECT TO $DatabaseName;
ALTER TABLESPACE TEMPSPACE1 BUFFERPOOL TEMPBP;
DISCONNECT current ;
84
ENOVIA Live Collaboration Installation Guide
CONNECT TO $DatabaseName;
CREATE USER TEMPORARY TABLESPACE USERTEMP IN DATABASE PARTITION GROUP
IBMDEFAULTGROUP PAGESIZE 32768 MANAGED BY SYSTEM USING
('$DatabasePath/tmp1','$DatabasePath/tmp2','$DatabasePath/
tmp3','$DatabasePath/tmp4')
EXTENTSIZE 32
PREFETCHSIZE 32
BUFFERPOOL USRTMPBP
OVERHEAD 7.500000
TRANSFERRATE 0.060000
DROPPED TABLE RECOVERY OFF;
CREATE
LARGE TABLESPACE MX_DATA PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL MXBP
INITIALSIZE 100 M
INCREASESIZE 20 PERCENT
PREFETCHSIZE 32;
CREATE
LARGE TABLESPACE MX_INDEX PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL MXBP
INITIALSIZE 100 M
INCREASESIZE 20 PERCENT
PREFETCHSIZE 32;
CREATE
LARGE TABLESPACE MX_LONG PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL MXBP
INITIALSIZE 100 M
INCREASESIZE 20 PERCENT
PREFETCHSIZE 32
FILE SYSTEM CACHING;
CREATE
LARGE TABLESPACE MXPROP PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL MXBP
INITIALSIZE 100 M
INCREASESIZE 20 PERCENT
PREFETCHSIZE 32;
CREATE
LARGE TABLESPACE MXPROP_I PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL MXBP
INITIALSIZE 100 M
INCREASESIZE 20 PERCENT
Chapter 4: Installing a DB2 Database
85
PREFETCHSIZE 32;
CREATE
LARGE TABLESPACE LX_DATA PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL LXBP
INITIALSIZE 1 G
INCREASESIZE 20 PERCENT
PREFETCHSIZE 32;
CREATE
LARGE TABLESPACE LX_INDEX PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL LXBP
INITIALSIZE 1 G
INCREASESIZE 20 PERCENT
PREFETCHSIZE 32;
CREATE
LARGE TABLESPACE LX_LONG PAGESIZE 32768 MANAGED BY AUTOMATIC STORAGE
BUFFERPOOL LXBP
INITIALSIZE 1 G
INCREASESIZE 5 PERCENT
PREFETCHSIZE 32
FILE SYSTEM CACHING;
update
db cfg for $DatabaseName using
SHEAPTHRES_SHR AUTOMATIC
SORTHEAP AUTOMATIC
MAXAPPLS AUTOMATIC
APPLHEAPSZ AUTOMATIC
STMTHEAP AUTOMATIC
DBHEAP AUTOMATIC
CATALOGCACHE_SZ 6000
LOGBUFSZ 2048
UTIL_HEAP_SZ 15000
STAT_HEAP_SZ AUTOMATIC
LOGFILSIZ 25000
LOGPRIMARY 30
LOGSECOND 10
logarchmeth1 OFF
logarchmeth2 OFF
newlogpath $DatabasePath/DBLOG
PCKCACHESZ AUTOMATIC
86
ENOVIA Live Collaboration Installation Guide
SELF_TUNING_MEM ON
LOCKLIST AUTOMATIC
MAXLOCKS AUTOMATIC
NUM_IOSERVERS 255
LOCKTIMEOUT -1
DFT_QUERYOPT 3
AUTO_MAINT OFF
DFT_DEGREE 1
MAXFILOP 32768
APPL_MEMORY AUTOMATIC;
update dbm cfg using
NUMDB 5
DIAGLEVEL 3
NOTIFYLEVEL 3
DFT_MON_BUFPOOL ON
DFT_MON_LOCK ON
DFT_MON_SORT ON
DFT_MON_STMT ON
DFT_MON_TABLE ON
DFT_MON_TIMESTAMP ON
DFT_MON_UOW ON
HEALTH_MON OFF
MON_HEAP_SZ 2048
JAVA_HEAP_SZ 2048
AUDIT_BUF_SZ 0
INSTANCE_MEMORY AUTOMATIC
BACKBUFSZ 10240
RESTBUFSZ 10240
SHEAPTHRES 0
ASLHEAPSZ 64
RQRIOBLK 32767
QUERY_HEAP_SZ 10000
MAX_CONNECTIONS AUTOMATIC
NUM_INITAGENTS 0
KEEPFENCED YES
Chapter 4: Installing a DB2 Database
87
SPM_NAME ''
MAX_QUERYDEGREE ANY
INTRA_PARALLEL NO
NUM_POOLAGENTS AUTOMATIC
FENCED_POOL AUTOMATIC;
GRANT
DBADM,CREATETAB,BINDADD,CONNECT,CREATE_NOT_FENCED_ROUTINE,IMPLICIT_SCHEMA,LOAD,CR
EATE_EXTERNAL_ROUTINE,QUIESCE_CONNECT ON DATABASE TO USER $DatabaseSchema;
GRANT USE OF TABLESPACE USERSPACE1 TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE USERTEMP TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE MX_DATA TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE MX_INDEX TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE MXPROP TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE MXPROP_I TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE MX_LONG TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE LX_DATA TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE LX_INDEX TO USER $DatabaseSchema WITH GRANT OPTION;
GRANT USE OF TABLESPACE LX_LONG TO USER $DatabaseSchema WITH GRANT OPTION;
bind
$DatabaseBinaries/bnd/db2clipk.bnd collection NULLIDRA;
update cli cfg for section $DatabaseName using SQL_ATTR_REOPT 4;
DISCONNECT current ;
terminate;
88
ENOVIA Live Collaboration Installation Guide
5
Installing an SQL Server
Database
Installing the Database Software
This chapter describes Microsoft SQL Server setup requirements and guidelines for
configuring SQL Server for use with ENOVIA Live Collaboration. SQL Server and
ENOVIA Live Collaboration may be installed:
•
As a stand-alone system, where the client and server machines are the same. In this
case, SQL Server software is installed, and there is no need to install additional
database client software, since it is a subset of the server software.
•
In a networked environment, with a database server and multiple clients. In a
networked installation, you must install the SQL Server software on the central server,
as well as the SQL Server client software on each machine that will be running
ENOVIA Live Collaboration.
A corollary of this is the ENOVIA Live Collaboration Server, which is really just
another SQL Server client. Web clients will then access data via the Web from the
server, without requiring further SQL Server client software at the end user’s
machine.
89
Installing SQL Server
You can install the Standard or the Enterprise edition of SQL Server. Before installing the
software, read this chapter in its entirety. Then use the guidelines provided here in
conjunction with the instructions provided by Microsoft. Supported platforms and
software versions are shown in the Program Directory for the given release.
Do NOT attempt to install SQL Server without the appropriate installation guides, which
are available from Microsoft.
SQL Server cannot be used with the Studio Modeling Platform on double-byte language
operating systems. This limitation is due to the SQL Server requirement that characters be
converted to Unicode before they can be stored in the database, and would require the
following settings: MX_CHARSET=UTF8 and LANG=C. However, the Studio Modeling
Platform requires characters to be mapped according to the operating system language
setting, and so LANG must be set to the appropriate language (e.g. SJIS) rather LANG=C
for Studio Modeling.
90
ENOVIA Live Collaboration Installation Guide
Setting up SQL Server for Use with ENOVIA
Live Collaboration
After you have installed SQL Server, you need to create an ODBC data source for use with
ENOVIA Live Collaboration. The data source should be created on the client machine
where ENOVIA Live Collaboration is running.
ENOVIA Live Collaboration software version V6R2011x supports SQL Server 2008 SP1
(build 10.0.2531). This version of SQL Server does not require the SQL Native Client.
Before configuring the ODBC driver for the very first time, update the SQL Server
instance using the SQL Server Management Studio to enable SQL Server and Windows
authentication.
A database must be created before you can create an ODBC data source for use with
ENOVIA Live Collaboration.
To create a database (database engine)
The following source provides general information on how to create a database:
http://technet.microsoft.com/en-us/library/ms175198.aspx
The following source provides information specific to SQL Server Management Studio:
http://technet.microsoft.com/en-us/library/ms186312.aspx
This topic describes how to create a database by using SQL Server Management Studio.
1. In Object Explorer, connect to an instance of the SQL Server Database Engine, and
then expand that instance. For example:
Chapter 5: Installing an SQL Server Database
91
2. Right-click Databases, and then click New Database.
3. In the New Database dialog, enter a database name.
4. To create the database by accepting all default values, click OK; otherwise, continue
with the following steps.
5. To change the owner name, click (...) to select another owner.
The “Use the full-text indexing” option is always checked and dimmed because, beginning
with SQL Server 2008, all user databases are full-text enabled. For more information, see
Configuring Full-Text Catalogs and Indexes for a Database (http://technet.microsoft.com/
en-us/library/cc879299.aspx).
6. To change the default values of the primary data and transaction log files, in the
Database files grid, click the appropriate cell and enter the new value. For more
information, see How to: Add Data or Log Files to a Database (SQL Server
Management Studio) (http://technet.microsoft.com/en-us/library/ms189253.aspx).
7. To change the collation of the database, select the Options page, and then select a
collation from the list.
8. To change the recovery model, select the Options page, and then select a recovery
model from the list.
9. To change database options, select the Options page, and then modify the database
options. For a description of each option, see Setting Database Options (http://
technet.microsoft.com/en-us/library/ms190249.aspx).
10. To add a new file group, click the File groups page. Click Add, and then enter the
values for the file group.
11. To add an extended property to the database, select the Extended Properties page:
a ) In the Name column, enter a name for the extended property.
b ) In the Value column, enter the extended property text (for example, one or more
statements that describe the database).
12. Click OK to create the database.
92
ENOVIA Live Collaboration Installation Guide
To create an ODBC data source (and alias to ENOVIA Team Server database)
This topic describes how to create an ODBC data source (em1sql) alias to the ENOVIA
Team Server database, which will be used during ENOVIA Team Server installation.
Before you begin:
Open the ODBC Data Source Administrator panel using one of the following methods:
•
For 32-bit Windows, open a command window and issue the command:
> C:\WINDOWS\system32\odbcad32.exe
•
For 64-bit Windows, including 32-bit media on 64-bit machines, open a
command window and issue the command:
> C:\WINDOWS\SysWOW64\odbcad32.exe
1. In the ODBC Data Source Administrator panel, click the System DSN tab, and then
click Add.
Chapter 5: Installing an SQL Server Database
93
2. In the Create New DataSource page, select SQL Server Native Client 10.0 for the
driver, and then click Finish.
3. In the Create a New Data Source to SQL Server panel:
a ) Provide the name of the data source that the ENOVIA Team Server installation
will use (in this example, em1sql).
b ) Provide a description of the data source.
c ) Select the server (in this example, <workstation_name>\MSSQL).
Click Next.
4. Specify the Login ID and the password.
94
ENOVIA Live Collaboration Installation Guide
The login ID and password you enter here correspond to the SQL Server
Administrator (in this example, sa). Click Next.
5. Select the default database from the database drop-down list. This is the name of the
database created in the MSSQL Server (in this example, EnoviaDB). Click Next.
Chapter 5: Installing an SQL Server Database
95
6. Uncheck the Perform translation for character data option. Click Finish.
7. Click Test Data Source... to test the connectivity with the database.
Testing the connectivity ensures that the data source is able to talk to the ENOVIA Live
Collaboration database on the SQL Server instance. If the test fails, you will need to close
out this administrator session and create a new data source.
8. Click OK to exit the ODBC Data Source Administrator.
ENOVIA Live Collaboration can now use the data source you have created to talk to the
database.
96
ENOVIA Live Collaboration Installation Guide
Configuring SQL Server
Minimizing
Deadlock Potential
The READ_COMMITTED_SNAPSHOT database option should be ON in your SQL
Server database. This option is similar to the locking model used by Oracle and prevents
readers from blocking writers, and writers from blocking readers. This option increases
through-put while minimizing deadlock potential:
ALTER DATABASE DATABASE_NAME
SET READ_COMMITTED_SNAPSHOT ON
Using Indexes with
SQL Server
When enabling ENOVIA Live Collaboration indexes on SQL Server, the operation should
be performed within a transaction using MQL. For example:
start transaction;
enable index MXINDEX;
commit transaction;
Case Sensitivity
System Administrators can configure ENOVIA Live Collaboration for either
case-insensitive mode or case-sensitive mode when using an SQL Server database. The
underlying database must be configured to support the desired sensitivity. By default, SQL
Server is supported as case-insensitive. For information on configuring the
case-sensitivity, see “Case-Sensitive Mode” in the MQL Guide.
In general, case sensitivity does not have an impact on ENOVIA Live Collaboration
performance. An exception may be queries using case-insensitive comparison operators
on a case-sensitive database.
Maintaining the
Database
It is recommended to use the maintenance wizard to create a job to update statistics and
run DBCC checkdb regularly. Additionally, the main database log should be backed up or
truncated at an interval that is based on the log size, bandwidth and the maximum
allowable window of vulnerability.
Shrinking and Maintaining the Transaction Log
If the transaction log is not truncated correctly or its maintenance job is failing, the log
will grow larger and larger and eventually eat the disk. If your transaction log has grown
too large, follow these steps to shrink it down to a reasonable size:
USE TestDB
GO
-- View Size of Database and file names
sp_helpdb TestDB
GO
-- set recovery to simple, makes shrinking easier
ALTER DATABASE TestDB SET RECOVERY SIMPLE
Chapter 5: Installing an SQL Server Database
97
-- shrink to 1GB
DBCC SHRINKFILE (TestDB_log, 1024)
-- set recovery to full
ALTER DATABASE TestDB SET RECOVERY FULL
GO
-- View Size of Database and file names
sp_helpdb TestDB
GO
-- BACKUP the database now
After the log is shrunk, it is important to verify that its maintenance job is running
correctly. If the maintenance job for the transaction log is not working correctly, the log
will not be truncated or backed up. When you configure the maintenance job for the
transaction log, make sure the option to “Create a backup file for every database” is
checked as well as the option to “Create a sub-directory for each database.”
Additionally you should monitor all your maintenance jobs by checking the Job log and
looking for files with a time stamp of the current day.
98
ENOVIA Live Collaboration Installation Guide
Configuring Disk Layout
For optimal I/O performance, it is highly recommended that different database files be
separated onto separate disk drives with each disk drive having its own disk controller.
Separating database files minimizes the impact of physical I/O contention at the server
level. The following components should be placed on separate disk drives/arrays:
•
Application data (such as tables and indexes)
•
Database log files
•
Database temporary space (TempDB) used for sort and join operations
Database log files should be placed on a separate drive from data files, OS files, and SQL
Server binary files. This is due to the fact that transaction log files are written serially and
using a dedicated disk controller allows the disk heads to stay in place for the next write
operation. You should use the fastest disks available for your log files. The sizing of the
log file should be mitigated frequently by transaction log backups to minimize the file
size. Additionally, transaction log backups should be part of the backup process so your
database can be restored to a point in time.
TempDB should be configured on a separate disk from the operating system and data files.
All the files in TempDB should be identical in size since SQL Server uses a proportional
fill algorithm. Sizing of TempDB should be performed after a series of exhaustive tests so
that it has had a chance to grow to a meaningful size.
Selecting and
Formatting Drives
In addition to separating the different database files onto separate disk drives, the types of
drives used and their formatting is very important for performance. The following
recommendations should be used when selecting and formatting your drives:
•
Log activity is very write intensive operation which means the RAID format selection
for the drive holding the log files is very important. RAID0, RAID1, RAID0+1, or
RAID1+0 should be used for this drive. RAID5 should NOT be used.
•
RAID5 should NOT be used for the drive holding TempDB.
•
RAID5 can be used for application data.
For more information on RAID, see RAID Technology.
Performance and
Scalability
The Performance Monitor feature and the SQL Profiler should be used to take targeted
traces on the production server. The SQL Profiler should be run on a separate machine
from the machine with the server so profiling does not impact production. The traces taken
should be very targeted and as short as necessary.
Chapter 5: Installing an SQL Server Database
99
General Index Recommendations
In general, all tables in your database should have a clustered index. A clustered index
stores the data in a table on the disk in a physically sorted order and all data resides in the
leaf pages of the index structure. In general, clustered indexes perform better than tables
that are stored as heaps (no clustered index).
Configuring Table
Statistics
Tables statistics are used by SQL Server to determine which algorithm to use to process a
query. The AUTO CREATE and AUTO UPDATE statistics options should be on. Table
statistics should be kept up-to-date.
Limiting Physical I/
O
Usually the slowest part of any database system is the disk I/O sub-system and any
techniques that minimize the number of pages to be read from disk should be used.
100
•
You should not duplicate the clustering key in a non-clustered index since the
clustering key is automatically added to each non-clustered index row. Adding
another key increases the storage needed by the non-clustered index.
•
When you are designing the clustering key, data access patterns must be taken into
account. For example if a table contains a surrogate key (for example, an IDENTITY
column) but you never query based on that key, but do range based queries on a date
column, it is more appropriate to cluster on the date column since all rows that satisfy
the query will be on the same or nearby data pages.
•
When examining STATISTIC IO results, or query execution plans, you should
attempt to limit the number of physical reads that must occur to satisfy the query. For
example, if you do not have a covering index for a query you will increase the number
of reads to satisfy the request.
ENOVIA Live Collaboration Installation Guide
SQL Server Limitations with ENOVIA Live
Collaboration
Some uncommonly used features are not supported on databases other than Oracle.
Limitations are noted within the context of the feature documentation. Some limitations
are listed below.
SQL Server
concurrency
In a SQL Server environment with many users accessing the same data, you may receive
the following error, when 2 users are creating new objects or relationships at the same
time:
Message:Cannot commit transaction Severity:3 ErrorCode:1500101
Message:State 40001: [Microsoft][SQL Native Client][SQL
Server]Transaction (Process ID XXX) was deadlocked on lock
resources with another process and has been chosen as the
deadlock victim. Rerun the transaction. Severity:3
If this concurrency issue is noticed regularly, you should generate the deadlock graph in
SQL Server Profiler and evaluate it to see if the LXRO table and the mxOID table are the
conflicting tables. If this is found to be the case, you can change the vault indexes from
non-clustered to clustered to resolve the issue.
To change object vault tables to use clustered indices in SQL Server
1. Start SQL Server Management Studio and login to the server.
2. Expand Database list.
3. Find and expand the Matrix database.
4. Expand Tables of Matrix database.
5. Find and expand the first lxRO_XXX table, where XXX is a vault ID.
6. Expand Indexes of the lxRO_XXX table.
7. Double click the lxRO_XXX_lxOID_Index.
8. In the dialog that opens, use the dropbox to change non-clustered to clustered.
9. A dialog pops up asking if you want to rebuild the indexes. Click Yes to continue.
10. Click OK.
11. Repeat steps 5 through 10 for each lxRO_XXX table.
Chapter 5: Installing an SQL Server Database
101
Localization Support
Since SQL Server uses the Unicode character set, ENOVIA Live Collaboration must
convert all data to Unicode before storing it in the SQL Server database. Therefore, when
installing the ENOVIA Live Collaboration Server, select UTF-8 support and ensure that
any additional manual UTF-8 configuration is also performed. Refer to Automated UTF-8
Settings and Additional Manual UTF-8 Settings in Chapter 8 for details.
For the ENOVIA Studio Modeling Platform, you need to manually add the following
setting to client enovia.ini files:
MX_CHARSET = UTF8
The MQL command set system decimal CHARACTER; is not supported for use
with databases other than Oracle. In these cases, the data is always stored with “.” but
displayed based on the desktop client’s MX_DECIMAL_SYMBOL setting, or in
Web-based implementations, the locale of the browser.
102
ENOVIA Live Collaboration Installation Guide
6
Installing a MySQL
Database
Installing the Database Software
This chapter describes setup requirements and guidelines for configuring MySQL Server
for use with ENOVIA Live Collaboration. MySQL Server and ENOVIA Live
Collaboration may be installed:
•
As a stand-alone system, where the client and server machines are the same. In this
case, MySQL Server software is installed, and there is no need to install additional
database client software since it is a subset of the server software.
•
In a networked environment, with a database server and multiple clients. In a
networked installation, you must install the MySQL Server software on the central
server, as well as the MySQL Server client software on each machine that will be
running ENOVIA Live Collaboration.
A corollary of this is the ENOVIA Live Collaboration Server, which is really just
another MySQL Server client. Web clients will then access data via the Web from the
server, without requiring further MySQL Server client software at the end user’s
machine.
103
Installing MySQL Server
Before installing the MySQL Server software, read this chapter in its entirety. Then use
the guidelines provided here in conjunction with the instructions provided by MySQL.
Supported platforms and software versions are shown in the Program Directory for the
given release. MySQL Server installation guides are available at http://www.mysql.com/.
104
ENOVIA Live Collaboration Installation Guide
Setting up MySQL Server for Use with ENOVIA
Live Collaboration
After you have installed the MySQL Server, you need to install the MySQL Server clients
or MySQL Connector/ODBC on all ENOVIA Live Collaboration client machines. For
information on installing the MySQL Connector/ODBC, see http://www.mysql.com/
products/connector/odbc/.
After you have installed the necessary MySQL Server clients, you need to create an
ODBC data source for use with ENOVIA Live Collaboration. The data source should be
created on the client machine where ENOVIA Live Collaboration is running. Use the
procedures below to create the data source.
The unixODBC package for Red Hat Enterprise Linux must be installed. You can select
this option when installing Red Hat Enterprise Linux.
Windows
Configuration
To Create an ODBC Data Source to use with ENOVIA Live Collaboration
1. Select Control Panel > Administrative Tools > Data Sources (ODBC).
2. In the ODBC Data Source Administrator panel, click the System DSN tab.
3. Click Add.
4. In the Create New DataSource page, select MySQL OBDC 5.16 Driver for the
driver.
5. Click Finish.
6. In the Connector/ODBC - Add Data Source Name page, provide the name of the
data source that ENOVIA Live Collaboration will use.
This name will become the connect string in the bootstrap file and should correspond
to the name of the MySQL database.
7. Provide a description of the data source.
8. Select the server with which ENOVIA Live Collaboration will communicate.
9. Specify the Login ID and the password.
The username and password you enter here should be the username and password in
the bootstrap file. They are set in MySQL Server when you create the database.
10. Select the default database from the drop down list for Database. This is the name of
the database created in the MySQL Server.
11. Click Test to test the connectivity with the database.
This is an optional but highly recommended step. Test the connectivity to make sure that
the data source is able to talk to the ENOVIA Live Collaboration database on the MySQL
Server instance. If the test fails, you will need to close out this administrator session and
create a new data source.
12. Click OK to exit the administrator.
Chapter 6: Installing a MySQL Database
105
A data source has now been created. ENOVIA Live Collaboration can use this data source
to talk to the database.
Linux
Configuration
To configure MySQL Server on Linux:
1. Use the MySQL Server distributed sample configuration file “my-large.cnf” as a
template to create my.cnf and make the following changes:
•
Enable all InnoDB settings. ENOVIA Live Collaboration requires InnoDB as the
MySQL Server storage engine.
•
Add or modify the following settings as shown below:
default-storage-engine=INNODB
lower-case-table-names = 1
default-character-set = utf8
max_allowed_packet = 4G
2. Restart the MySQL Server.
3. Create a datasource for ENOVIA Live Collaboration to use:
a ) Open the odbc.ini file in /etc. Create the file if it is not there. Add the
following lines:
myodbc5
= MyODBC 5.16 Driver DSN
[myodbc5]
Driver
= /usr/lib64/libmyodbc5.so
Description = Connector/ODBC 5.16 Driver DSN
SERVER
= localhost
PORT
=
USER
= root
Password
=
Database
= test
OPTION
= 5
SOCKET
=
b ) Create the datasource by adding a datasource section to the file similar to the
following.
[mxdb]
Description = MySQL ENOVIA Collaboration Platform
database
Driver
= MySQL
Server
= localhost
Port
= 3306
Database
= mxdb
4. After you have created the datasource, create a MySQL user who has unlimited
access to the database you created. To create a MySQL user:
a ) From MYSQL_HOME log into bin\mysql as:
Bin\mysql --user=root (to login without a root password)
106
ENOVIA Live Collaboration Installation Guide
Bin\mysql --user=root -p (to login with a password)
b ) To grant unlimited access to the user from his local machine, add the following:
grant all privileges on *.* to <user>@localhost identified by
‘<pass>’ with grant option;
In the following example, user Test is granted all privileges as a MySQL User.
grant all privileges on *.* to test@localhost identified by
'test' with grant option;
Query OK, 0 rows affected (0.08 sec)
To grant unlimited access to the user from a remote client, add the following:
grant all privileges on *.* to <user>@'%' identified by
‘<pass>’ with grant option;
5. Open the odbcinst.ini file located in /etc. Create the odbcinst.ini if it is
not there. Add the following lines.
[MySQL]
Description = ODBC for MySQL
Driver
= /usr/lib64/libmyodbc5.so
Setup
= /usr/lib64/libodbcmyS.so
Threading
= 0
FileUsage
= 0
6. Use the ODBC SQL utility to test that you can connect to the database using the
ODBC datasource. For example:
isql mxdb ENOVIA_USER ENOVIA_PASS
where:
ENOVIA_USER is the MySQL ENOVIA Live Collaboration user
ENOVIA_PASS is the MySQL ENOVIA Live Collaboration user password
7. Create the bootstrap file where:
user is the MySQL ENOVIA Live Collaboration user
password is the MySQL ENOVIA Live Collaboration user password
connectstring is the name you gave to the MySQL ENOVIA Live Collaboration in
your odbc.ini file. In this example it is mxdb.
Databasedriver is MySQL/ODBC.
Chapter 6: Installing a MySQL Database
107
Configuring MySQL Server
Important MySQL
Server Parameters
It is recommended that the following parameters use these minimum settings:
query_cache_size=8M
innodb_buffer_pool_size=500M
innodb_log_file_size=150M
innodb_log_buffer_size=4M
The default settings are listed when the following command is run in the MySQL Shell:
Shell>mysqld --verbose --help
See MySQL Server documentation for more details.
MySQL Server
with Linux
Environments
The TRADITIONAL parameter should be set when using MySQL Server with a Linux
environment. This parameter issues an error message when object names exceed 127
bytes. When this parameter is not set, objects with names that exceed 127 bytes can be
created without the error message. Additional characters from these names are then
removed at random. Set the TRADITIONAL parameter in my.cnf:
sql_mode = 'TRADITIONAL'
Maintaining the
Database
It is recommended to use the maintenance wizard to create a job to update statistics and
run DBCC checkdb regularly. Additionally, the main database log should be backed up or
truncated at an interval that is based on the log size, bandwidth and the maximum
allowable window of vulnerability.
Case Sensitivity
System Administrators can configure ENOVIA Live Collaboration for either
case-insensitive mode or case-sensitive mode when using an MySQL Server database. The
underlying database must be configured to support the desired sensitivity. By default,
MySQL Server is supported as case-insensitive. For information on configuring the
case-sensitivity, see “Case-Sensitive Mode” in the ENOVIA Studio Modeling Platform
MQL Guide.
In general, case sensitivity does not have an impact on ENOVIA Live Collaboration
performance. An exception may be queries using case-insensitive comparison operators
on a case-sensitive database.
108
ENOVIA Live Collaboration Installation Guide
Configuring Disk Layout
For optimal I/O performance, it is highly recommended that different database files be
separated onto separate disk drives with each disk drive having its own disk controller.
Separating database files minimizes the impact of physical I/O contention at the server
level. The following components should be placed on separate disk drives/arrays:
•
Application data (such as tables and indexes)
•
Database log files
•
Database temporary space (TempDB) used for sort and join operations
Database log files should be placed on a separate drive from data files, OS files, and
MySQL Server binary files. This is due to the fact that transaction log files are written
serially and using a dedicated disk controller allows the disk heads to stay in place for the
next write operation. You should use the fastest disks available for your log files. The
sizing of the log file should be mitigated frequently by transaction log backups to
minimize the file size. Additionally, transaction log backups should be part of the backup
process so your database can be restored to a point in time.
TempDB should be configured on a separate disk from the operating system and data files.
All the files in TempDB should be identical in size since MySQL Server uses a
proportional fill algorithm. Sizing of TempDB should be performed after a series of
exhaustive tests so that it has had a chance to grow to a meaningful size.
Selecting and
Formatting Drives
In addition to separating the different database files onto separate disk drives, the types of
drives used and their formatting is very important for performance. The following
recommendations should be used when selecting and formatting your drives:
•
Log activity is very write intensive operation which means the RAID format selection
for the drive holding the log files is very important. RAID0, RAID1, RAID0+1, or
RAID1+0 should be used for this drive. RAID5 should NOT be used.
•
RAID5 should NOT be used for the drive holding TempDB.
•
RAID5 can be used for application data.
For more information on RAID, see RAID Technology.
Chapter 6: Installing a MySQL Database
109
MySQL Server Limitations with ENOVIA Live
Collaboration
Some uncommonly used features are not supported on databases other than Oracle.
Limitations are noted within the context of the feature documentation. Some limitations
are listed below.
Difference in
Configuration
MySQL tables do not work exactly like tablespaces in other databases. You have two
configuration options: you can store all the data/indexes in one file (the default) or you can
store all the data/indexes in one file in its own table.
These are storage configuration options, not a DDL configuration option. Therefore, if a
tablespace is specified when creating an ENOVIA Live Collaboration vault with MySQL,
it is ignored. The configuration option set in MySQL is used.
To store all the data/indexes in one file per table, add the following to the MySQL
configuration file (my.cnf) in the [mysqld] section: innodb_file_per_table.
110
ENOVIA Live Collaboration Installation Guide
Localization Support
In order to support multiple languages, you must configure the ENOVIA Collaboration
Server for UTF-8.
In addition, you must use the default setting for the system decimal character. All floating
point numbers are stored in MySQL with “.” as the decimal character, and are displayed
based on the user’s operating system’s locale setting.
Chapter 6: Installing a MySQL Database
111
112
ENOVIA Live Collaboration Installation Guide
7
Installing the Studio
Modeling Platform
Overview
This chapter describes procedures for installing ENOVIA Studio Modeling Platform Rich
Clients software.
113
Installing ENOVIA Studio Modeling Platform on
UNIX/Linux
In order to install the ENOVIA Studio Modeling Platform on UNIX platforms, you must
perform the appropriate setup options from the Primary Setup Menu.
If you are upgrading from a prior version of Studio Modeling Platform, refer to the
Program Directory for additional instructions on installing the platform and upgrading
the schema.
If you want JPO support, you must first install Java (JRE, JDK, SDK). You should use the
same version as is used to write the JPOs.
Mounting the CD
If you are installing from CD, you must mount the CD drive so that the operating system
software can access the files contained on the disk.
To mount the CD-ROM
1. Insert the ENOVIA Live Collaboration CD-ROM for your platform into a local
CD-ROM drive. If a local drive is not available, consult your operating system
administrator's guide.
2. Create a “mount point” directory for the CD-ROM drive:
mkdir /cdrom
3. Mount the CD-ROM. Below are examples of the commands:
Installing the
Software on UNIX/
Linux
Hardware
Example of Command
SPARCstation
mount -F hsfs -r /dev/dsk/c0t6d4s0 /cdrom
IBM RS6000
mount -v cdrfs -r /dev/cd0 /cdrom
You can install the ENOVIA Studio Modeling Platform as the root user. If you are not root
user on AIX 5.1, you must install to a directory that does not have the sticky bit set. Only
root is permitted to turn the sticky bit on or off.
The ENOVIA Studio Modeling Platform Rich Clients Setup program can be run in one of
three modes—graphical, console, or silent:
114
•
To install the Studio Modeling Platform on UNIX/Linux in graphical mode, see
page 115.
•
To install the Studio Modeling Platform on UNIX/Linux in console mode, see
page 123.
•
To install the Studio Modeling Platform on UNIX/Linux in silent mode, page 127.
ENOVIA Live Collaboration Installation Guide
To install the Studio Modeling Platform on UNIX/Linux in graphical mode
1. Copy the <media_name>.tar.gz file, where <media_name> is the name of the media
for your platform (for example, ENOVIAStudioModelingPlatformRichClients-V6R2011x.RHEL64), from the CD or ENOVIA Download page to the
distribution directory.
2. Mount the CD-ROM drive. Refer to Mounting the CD in Chapter 7 if necessary.
3. Untar the <media_name>.tar.gz file to a temporary directory. Change to the
<media_name>/1/ subdirectory, and then run the Setup program in graphical
mode as follows:
% cd /<media_name>/1
% ./StartGUI.sh
The ENOVIA Studio Modeling Platform graphical Setup program starts.
Setup first allows you to enter the directory where the ENOVIA Studio Modeling
Platform software will be installed. On UNIX, the default installation path is empty.
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
Chapter 7: Installing the Studio Modeling Platform
115
Click Browse and navigate to the desired directory or type in the path.
After specifying the directory, click Next.
116
ENOVIA Live Collaboration Installation Guide
4. Setup then lists the components that are packaged in the media. If multiple products
are shown, you can choose the ones you want to install, or All. As the DMP media
contains only a single product (ENOVIA Studio Modeling Platform Rich Clients),
you can ignore this step and go directly to the next panel by clicking Next.
5. Next, you must choose the specific Studio Modeling Platform components you wish
to install. The choices are:
•
Business—This component should be installed only on machines to be used by
Business Administrators.
•
Matrix—This component should be installed by all users who want to use
Matrix Navigator.
•
System—This component should be installed only on machines to be used by
System Administrators.
•
MQL—This component may be useful to most users, but certainly should be
installed on Business and System Administrators' machines.
A white check box indicates that an item is selected. All items are selected by default.
If you want to deselect any item, click inside its check box. Click Next.
Chapter 7: Installing the Studio Modeling Platform
117
6. Setup then asks you to enter the Java Home path. This is the location of your Java
Development Kit (JDK)
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
If you want to select a directory other than the default, click Browse and navigate to
the desired directory or type in the path.
118
ENOVIA Live Collaboration Installation Guide
Click Next.
7. Setup than asks you to choose a database type. Only those database types that are
supported on your particular platform are displayed. Depending on the OS, the
available database options could be any of the following:
•
Oracle, DB2, and MySQL
•
Oracle and DB2
•
Oracle only
If your platform supports multiple types of databases, Oracle is the default. A white
check box means that an item is selected. Select the desired database type.
Click Next.
Chapter 7: Installing the Studio Modeling Platform
119
8. If you selected Oracle, Setup asks for the location of the TNS_ADMIN directory,
which contains the tnsnames.ora file. This file contains the client-side network
configuration parameters required for Oracle. You can copy a tnsnames file from the
Oracle server and put it in the location specified here after the installation completes.
Setup cannot detect the correct Oracle path on UNIX. Incorrect Oracle path selection may
abort the installation without a message indicating the reason for the failure.
To install to a different location than the displayed default, click Browse and navigate
to the desired directory or type in the path.
120
ENOVIA Live Collaboration Installation Guide
Click Next.
9. If you selected Oracle, Setup then asks you to read and accept Oracle’s client license
agreement. Read the agreement, then click the “I have read and accept the license
terms” radio button. The Next button becomes active once you click this option.
Again, a white check box means that an item is selected. Click Next.
10. If you selected a different database type than Oracle, Setup displays a different set of
questions:
•
For DB2, you are asked to enter the DB2 product directory and the DB2 Instance
Name (the default on UNIX is "db2inst1").
•
For MySQL, you are asked to enter the directory where the ODBC initialization
files reside.
Chapter 7: Installing the Studio Modeling Platform
121
11. Setup then asks you to enter the directory of your connection file (MATRIX-R file). If
you want to choose a different location, click Browse and navigate to the desired
directory or type in the path. Click Next.
12. The next panel displays the installation summary, including the DMP installation
directory, selected product(s), components to be installed, Java Home path, database
type, TNS_ADMIN directory, and finally the location of your MATRIX-R connection
file. Review the contents and if you want to make any changes, click Back and make
the desired corrections. When you are satisfied with the information displayed, click
Install to start the installation.
122
ENOVIA Live Collaboration Installation Guide
Setup displays the current state of progress of the installation.
13. Once the installation is complete, Setup informs you that the “DMP - ENOVIA
Studio Modeling Platform Rich Clients” component has been successfully installed.
Click End to end the Setup program and dismiss the window.
To install the Studio Modeling Platform on UNIX/Linux in console mode
1. Copy the <media_name>.tar.gz file, where <media_name> is the name of the media
for your platform (for example, ENOVIAStudioModelingPlatformRichClients-V6R2011x.RHEL64), from the CD or ENOVIA Download page to the
distribution directory.
2. Mount the CD-ROM drive. Refer to Mounting the CD in Chapter 7 if necessary.
3. Untar the <media_name>.tar.gz file to a temporary directory. Change to the
<media_name>/1/ subdirectory, and then run the Setup program in console mode
as follows:
% cd /<media_name>/1
% ./StartTUI.sh
Chapter 7: Installing the Studio Modeling Platform
123
The ENOVIA Studio Modeling Platform console-based Setup program starts.
4. Setup displays the directory in which the software will be installed.
*****V6R2011x ENOVIA Studio Modeling Platform Choose Destination
Location*****
Setup will install V6R2011x ENOVIA Studio Modeling Platform in
the following directory:
Default []: /qausr/Enovia_V6R2011x/Studio
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
Change the destination location if desired then press Enter, or simply press Enter to
accept the default and continue.
5. Setup asks you to select the software you want to install:
•
Click 1, or press Enter, to install the DMP—ENOVIA Studio Modeling Platform
Rich Clients software to the specified directory.
•
Click 2 to end selection and exit Setup.
The following is an example of the text that appears on the screen:
*****V6R2011x ENOVIA Studio Modeling Platform Select
Software*****
Click to select the components you want to install in
directory
/qausr/Enovia_V6R2011x/Studio.
You can choose not to install V6R2011x ENOVIA Studio
Modeling Platform by clicking Cancel to exit setup.
Space available: 26996065 Kb
Space required: 110641 Kb
-2 End selection
-1 [X] All
DMP - ENOVIA Studio Modeling Platform Rich Clients
Enter selection (default: Next) :
6. Setup then asks you to select the components you wish to install: Business Modeler,
Matrix, System Manager, and MQL. You can optionally install ENOVIA Live
Collaboration Matrix Navigator at the same time as ENOVIA Studio Modeling
Platform. Most clients have only Matrix Navigator and possibly MQL installed.
Business Administrators typically have all applications except System Manager,
while System Administrators have all but Business Modeler. To ensure database
integrity, the System Manager application should be installed in a secure environment
for the System Administrator’s use only.
*****V6R2011x ENOVIA Studio Modeling Platform Choose
Components*****
Select the components that you wish to install.
If the check box is unchecked, that component will not be
installed.
Click Next to continue the installation.
-2 End selection
1 [X] Business
2 [X] Matrix
124
ENOVIA Live Collaboration Installation Guide
3 [X] System
4 [X] MQL
Enter selection (default: Next) :
Setup creates the application script files for the selected Studio Modeling Platform
components in the application directory (i.e., Business, Matrix, System, or MQL).
These script files set up the environment before calling up the application executable.
In order to allow access to all the application script files created in this step, the
permissions of each file are changed to allow the owner rwx, the group rx, and others
rx. The executable binaries themselves are set to the permissions you specified.
7. Setup then asks you to select the Java Home path.
*****V6R2011x ENOVIA Studio Modeling Platform Select Java
Home*****
Please enter Java Home path
Default [/usr/java]: /usr/jdk/jdk1.6.0_19
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
The next panel asks you to choose the type of database you want to use. Depending on
the OS, the available database options could be any of the following:
•
Oracle, DB2, and MySQL
•
Oracle and DB2
•
Oracle only
If your platform supports multiple types of databases, Oracle is the default. Select the
desired database type.
*****V6R2011x ENOVIA Studio Modeling Platform Database
selection*****
Choose the database type:
-2 End selection
1 (*) Oracle
Enter selection (default Next):
•
If you select Oracle, proceed as follows:
a )Setup asks for the location of the TNS_ADMIN directory, which contains the
tnsnames.ora file. This file contains the client side network configuration
parameters required for Oracle. The directory where your tnsnames.ora file is
located is automatically filled with the path from the ORACLE_HOME
environment variable if it is set. For example:
/home/data/or11g/network/admin
You can copy a tnsnames file from the Oracle server and put it in the location
you specify after the installation completes.
*****V6R2011x ENOVIA Studio Modeling Platform Oracle
Server Connection Parameters*****
TNS_ADMIN directory
Default [/home/data/ora11g/network/admin]: /app/oracle/
product/11.2.0/network/admin
Chapter 7: Installing the Studio Modeling Platform
125
Setup cannot detect the correct Oracle path on UNIX. Incorrect Oracle path selection may
abort the installation without a message indicating the reason for the failure.
b )The Oracle license agreement is presented. Read the license agreement and
when you reach the end, respond to these prompts:
*****V6R2011x ENOVIA Studio Modeling Platform Oracle
Instant Client License*****
Be sure to carefully read and understand all the
rights and restrictions described
in the license terms. You must accept the license
terms before you can install the
software
1 [ ] I have read and accept the license terms
2 [ ] I do not accept the license terms
Enter your choice 1 or 2( if you choose 2, the
installer will end): 1
1 [X] I have read and accept the license terms
2 [ ] I do not accept the license terms
You must accept the Oracle license agreement to continue with the installation.
•
If your platform supports a database other than Oracle and you select DB2,
proceed as follows:
Enter the DB2 product directory [ ]?
Enter the DB2 Instance Name [db2inst1]?
You must enter the directory where DB2 is installed and the name of your DB2
instance. (The default instance name on UNIX is db2inst1, which you can
change.)
•
If your platform supports a database other than Oracle and you select MySQL,
proceed as follows:
Enter the directory where the ODBC initialization
files reside [ ]?
8. Setup then asks you to enter the directory of your connection (MATRIX-R) file.
Before using the Studio Modeling Platform, the system must have a connection
(bootstrap) file in the ENOVIAHOME directory. This file contains the information
necessary for ENOVIA Live Collaboration to locate and open the database.
*****V6R2011x ENOVIA Studio Modeling Platform Choose MatrixHome
Location*****
Please enter the directory of your connection file (MATRIX-R
file).
Default [/qausr/Enovia_V6R2011x/Studio]: /qausr/Enovia_V6R2011x
Moving logs from "/tmp/InstallData/log/CODE/solaris_a64/
ENOVIA_DMP.media-2010_08_12-104344/" to "/qausr/
Enovia_V6R2011x/Studio/InstallData/log/CODE/solaris_a64/
ENOVIA_DMP.media-2010_08_12-104344/"
If you want to choose a different location, click Browse and navigate to the desired
directory or type in the path. Click Next.
126
ENOVIA Live Collaboration Installation Guide
9. Setup is now ready to start copying the program files. If you want to change any
settings, type the letter 'b' (for Back) and press Enter, then make the desired
corrections. When you are satisfied with the displayed settings, press Enter to start
the installation.
*****V6R2011x ENOVIA Studio Modeling Platform Start Copying
Files*****
Setup has enough information to start copying the program files.
If you want to review or change any settings, click Back.
If you are satisfied with the settings, click Install to begin
copying files.
Files will be installed in the following directory: /qausr/
Enovia_V6R2011x/Studio
Selected products: All
Components to install: Business, Matrix, System, MQL
DSYInsControler.JavaPath.Resume(/usr/jdk/jdk1.6.0_19)
Database type: Oracle
TNS_ADMIN directory: /app/oracle/product/11.2.0/network/admin
MatrixHome Location: /qausr/Enovia_V6R2011x/Studio
Enter your choice (default Install):
CODE/solaris_a64/InsStudioOnly (589 b)
..............................
10. Once the installation is complete, Setup informs you that “DMP—ENOVIA Studio
Modeling Platform Rich Clients” has been successfully installed.
*****V6R2011x ENOVIA Studio Modeling Platform Setup
Complete*****
Setup has finished installing V6R2011x ENOVIA Studio Modeling
Platform on your computer.
DMP - ENOVIA Studio Modeling Platform Rich Clients: installed.
-2 End selection
Enter selection (default: Next) :
To install the Studio Modeling Platform on UNIX/Linux in silent mode
Silent mode requires completion of installation of Studio Modeling Platform in one of the
other two modes (graphical or console). After installation, the files needed for silent mode
are created under ENOVIAHOME/InstallData/. In this directory, there is a file called
UserIntentions.xml.
If you want to allow the installer to run on a non-empty directory, you must manually
modify the TARGET_PATH variable in the UserIntentions.xml and InstallData.xml files,
both of which are located in the InstallData subdirectory of the ENOVIAHOME directory.
1. Open a console window.
2. Change to the <media_name>/1/ subdirectory, and then run the Setup program in
silent mode as follows:
% cd /<media_name>/1
% ./StartTUI.sh --silent <full_path>/UserIntentions.xml
Chapter 7: Installing the Studio Modeling Platform
127
where <full_path> is the path to the InstallData/ subdirectory under the
ENOVIAHOME directory.
128
ENOVIA Live Collaboration Installation Guide
Installing ENOVIA Studio Modeling Platform on
Windows
The ENOVIA Studio Modeling Platform Rich Client is installed on Windows systems by
following the prompts displayed by the installation program, which is referred to in these
instructions as “Setup.” Use the guidelines below for assistance.
If you are upgrading from a prior version of Studio Modeling Platform, refer to the
Program Directory for additional instructions on installing the platform and upgrading
the schema.
If you want JPO support, you must first install Java (JRE, JDK, SDK). You should use the
same version as is used to write the JPOs.
Installing the
Software on
Windows
ENOVIA Studio Modeling Platform client software is distributed on one CD-ROM or
may be downloaded from the ENOVIA website as a tar file.
The ENOVIA Studio Modeling Platform Rich Clients Setup program can be run in one of
three modes—graphical, console, or silent:
•
To install the Studio Modeling Platform on Windows in graphical mode, see page 129.
•
To install the Studio Modeling Platform on Windows in console mode, see page 135.
•
To install the Studio Modeling Platform on Windows in silent mode, see page 141.
To install the Studio Modeling Platform on Windows in graphical mode
1. Log into Windows as a user with Administrator privileges.
2. Copy the <media_name>.zip file, where <media_name> is the name of the media for
your platform (for example, ENOVIAStudioModelingPlatformRichClients-V6R2011x.Windows64), from the CD or ENOVIA Download page to
a temporary directory.
Please note that when transferring .zip files from the internet, executable files may
silently be excluded when unzipping due to Windows security behaviour. To prevent
this from happening, before unzipping the file, right click in the file, select
Properties, then click Unblock.
3. Unzip the <media_name>.zip file to a temporary directory. Change to the
<media_name>\1\ subdirectory, and then run the Setup program in graphical
mode as follows:
> cd \<media_name>\1
> setupV6
The ENOVIA Studio Modeling Platform graphical Setup program starts.
Chapter 7: Installing the Studio Modeling Platform
129
4. Setup displays the directory where the ENOVIA Studio Modeling Platform software
will be installed. The default is C:\enoviaV6R2011x\studio. If you want to
choose a different location, click Browse and navigate to the desired directory or type
in the path. Click Next.
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
5. Setup then lists the products that are packaged in the media. If multiple products are
shown, you can choose the ones you want to install, or all. As the DMP media
contains only a single product (ENOVIA Studio Modeling Platform Rich Clients),
you can ignore this step and go directly to the next panel by clicking Next.
6. Next, you must choose the specific Studio Modeling Platform components you wish
to install. The choices are:
130
•
Business—This component should be installed only on machines to be used by
Business Administrators.
•
Matrix—This component should be installed by all users who want to use
Matrix Navigator.
ENOVIA Live Collaboration Installation Guide
•
System—This component should be installed only on machines to be used by
System Administrators.
•
MQL—This component may be useful to most users, but certainly should be
installed on Business and System Administrators' machines.
Check the items you want to install. Click Next.
7. Setup then asks for the Java Home path. If you want to select a directory other than
the default, click Browse and navigate to the desired directory or type in the path.
Click Next.
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
Chapter 7: Installing the Studio Modeling Platform
131
The next panel asks you to choose the type of database you want to use. The options
are Oracle and Others. If your platform supports multiple types of databases, Oracle is
the default. If you want to use a different type of database than Oracle, select Others
and then select the desired database type. Click Next.
8. If you selected Oracle, Setup asks for the location of the TNS_ADMIN directory,
which contains the tnsnames.ora file. This file contains the client side network
configuration parameters required for Oracle. You can copy a tnsnames file from the
Oracle server and put it in the location you specify after the installation completes.
The default is c:\oracle\product\10g\NETWORK\ADMIN. To install to a
different location, click Browse and navigate to the desired directory or type in the
path. Click Next.
Incorrect Oracle path selection may abort the installation without a message indicating
the reason for the failure.
132
ENOVIA Live Collaboration Installation Guide
9. If you selected Oracle, you are asked to accept Oracle’s client license agreement.
Read the agreement, then click the “I have read and accept the license terms” radio
button. The Next button becomes active once you click this option. Click Next.
The following value is written to the HKEY_LOCAL_MACHINE/Software/Oracle
registry key:
•
TNS_ADMIN—location of your tnsnames.ora file
10. Setup then asks you to enter the directory of your connection file (MATRIX-R file).
The default is C:\enoviaV6R2011x\studio. If you want to choose a different
location, click Browse and navigate to the desired directory or type in the path. Click
Next.
11. The next panel displays the installation summary, including the DMP installation
directory, selected product(s), components to be installed, Java Home path, database
type, TNS_ADMIN directory, and finally the location of your MATRIX-R connection
file.
Chapter 7: Installing the Studio Modeling Platform
133
Review the contents and if you want to make any changes, click Back and make the
desired corrections. When you are satisfied with the information displayed, click
Install to start the installation.
The window displays the current state of progress of the installation.
134
ENOVIA Live Collaboration Installation Guide
Once the installation is complete, Setup informs you that the “DMP - ENOVIA
Studio Modeling Platform Rich Clients” component has been successfully installed.
Setup also creates program shortcuts under the "Dassault Systemes Software
V6R2011x" program folder on the Start menu.
To install the Studio Modeling Platform on Windows in console mode
1. Log into Windows as a user with Administrator privileges.
2. Copy the <media_name>.zip file, where <media_name> is the name of the media for
your platform (for example, ENOVIAStudioModelingPlatformRichClients-V6R2011x.Windows64), from the CD or ENOVIA Download page to
the distribution directory.
Please note that when transferring .zip files from the internet, executable files may
silently be excluded when unzipping due to Windows security behaviour. To prevent
this from happening, before unzipping the file, right click in the file, select
Properties, then click Unblock.
3. Unzip the <media_name>.zip file to a temporary directory. Change to the
<media_name>\1\ subdirectory, and then run the Setup script in console mode as
follows:
> cd \<media_name>\1
> StartTUI.bat
The ENOVIA Studio Modeling Platform text-based Setup program starts.
Chapter 7: Installing the Studio Modeling Platform
135
4. Setup opens a console window and displays the directory where the ENOVIA Studio
Modeling Platform software will be installed. The default is
C:\enoviaV6R2011x\studio.
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
If you want to choose a different destination location, type in the desired path.
Press Enter.
5. Setup then asks you to confirm that you want to install ENOVIA Studio Modeling
Platform Rich Clients software.
Press Enter to continue with the installation.
6. Next, you must choose the specific Studio Modeling Platform components you wish
to install. The choices are:
136
•
1 for Business—This component should be installed only on machines to be used
by Business Administrators.
•
2 for Matrix—This component should be installed by all users who want to use
Matrix Navigator.
ENOVIA Live Collaboration Installation Guide
•
3 for System—This component should be installed only on machines to be used
by System Administrators.
•
4 for MQL—This component may be useful to most users, but certainly should
be installed on Business and System Administrators' machines.
All items are selected by default. If you want to install all items, simply press Enter.
If you want to choose three or fewer items, enter the number(s) of the item(s) you
want to install separated by spaces, then press Enter.
Setup redisplays the list with an X next to each item that you have selected.
Press Enter to confirm your selection.
7. Setup then asks for the Java Home path. If you want to select a directory other than
the default, type in the path.
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
Press Enter.
Chapter 7: Installing the Studio Modeling Platform
137
8. The next panel asks you to choose the type of database you want to use. The Windows
options are Oracle and Others. Oracle is the default. If you want to use a different type
of database than Oracle, select Others and then select the desired database type.
Press Enter.
9. If you selected Oracle, Setup asks for the location of the TNS_ADMIN directory,
which contains the tnsnames.ora file. This file contains the client side network
configuration parameters required for Oracle. You can copy a tnsnames file from the
Oracle server and put it in the location you specify after the installation completes.
The default is c:\oracle\product\10g\NETWORK\ADMIN\. If you want to
install to a different location, type in the path.
Incorrect Oracle path selection may abort the installation without a message indicating
the reason for the failure.
Press Enter.
10. If you selected Oracle, you are asked to read and accept Oracle’s client license
agreement. Read the agreement, then enter one of the following:
138
•
Type '1' if you accept the license terms
•
Type '2' if you do not accept the license terms. Setup will end if you choose this
option.
ENOVIA Live Collaboration Installation Guide
Press Enter.
The following value is written to the HKEY_LOCAL_MACHINE/Software/Oracle
registry key:
TNS_ADMIN-location of your tnsnames.ora file
11. Setup then asks you to enter the directory of your connection file (MATRIX-R file).
The default is C:\enoviaV6R2011x\studio. If you want to choose a different
location, type in the path.
Press Enter.
Chapter 7: Installing the Studio Modeling Platform
139
12. The next panel displays the installation summary, including the DMP installation
directory, selected product(s), components to be installed, Java Home path, database
type, TNS_ADMIN directory, and finally the location of your MATRIX-R connection
file.
Press Enter to start the installation.
The console window displays the current state of progress of the installation.
140
ENOVIA Live Collaboration Installation Guide
13. Once the installation is complete, Setup informs you that “DMP - ENOVIA Studio
Modeling Platform Rich Clients” has been successfully installed.
Press Enter to exit the Setup program and dismiss the console window.
To install the Studio Modeling Platform on Windows in silent mode
Silent mode requires completion of installation of Studio Modeling Platform in one of the
other two modes (graphical or console). After installation, the files needed for silent mode
are created under SERVER_INSTALL\InstallData\. In this directory, there is a file
called UserIntentions.xml.
If you want to allow the installer to run on a non-empty directory, you must manually
modify the TARGET_PATH variable in the UserIntentions.xml and InstallData.xml files,
both of which are located in the InstallData\ subdirectory of the ENOVIA_INSTALL
directory.
1. Log into Windows as a user with administrative privileges.
2. Open a console window.
3. Change to the <media_name>\1\ subdirectory and then run the Setup script as
follows:
> cd \<media_name>\1
> StartTUI.bat --silent <full_path>\UserIntentions.xml
where <full_path> is the path to the InstallData\ subdirectory under the
ENOVIA_INSTALL directory.
Chapter 7: Installing the Studio Modeling Platform
141
Exiting Setup
The application script path, ENOVIAHOME/scripts/ should be in your path (on
UNIX). The script files may be customized for personal preferences of fonts and colors.
Refer to Configuring ENOVIA Live Collaboration in Chapter 9 for more information.
Use the following commands to start ENOVIA Studio Modeling Platform applications:
%
%
%
%
142
matrix[cr] Starts the Matrix application.
business[cr] Starts the Business Modeler application.
mql[cr] Starts the MQL application.
system[cr] Starts the System Manager application.
ENOVIA Live Collaboration Installation Guide
Installing a New Version of Studio Modeling
Platform
When you want to install a new version of the ENOVIA Studio Modeling Platform, it may
or may not require a database (schema) upgrade. Refer to the Program Directory for the
given release for details. If no upgrade is necessary, proceed with installing the new
software on all client machines.
If a database upgrade is required, the following factors should be evaluated to determine
the scope of the upgrade project:
•
The type of upgrade.
You can perform an Upgrade Analysis to determine what changes will be made to the
database when the upgrade is performed. When extensive changes will be made
during an upgrade and you are using Oracle, some Oracle Configuration may be
required before a successful upgrade can be accomplished.
The Program Directory may also provide insight as to the extent of an upgrade.
•
The size of the database.
Very large databases generally require database tuning before an upgrade is
performed.
When a database is linked to another database via a loose coupling, you should remove
the remote (LCD) vault before running upgrade or you will receive an error. Once
upgrade is complete, you can restore the remote vaults.
When an upgrade is required, always refer to specific procedures provided in the Program
Directory for the new ENOVIA Live Collaboration release.
Using Lower
Version Software
after Upgrading
the Database
When there are a very large number of users, it may be difficult to accomplish the
installation of the new software for every client before performing an upgrade. For less
involved upgrades, when the extent of the schema change is the addition of new database
tables, ENOVIA Live Collaboration lets users connect to a higher revision database with
the lower revision Live Collaboration software. This lets System Administrators install the
new software on some clients, those that perhaps need access to the new features it
provides, then upgrade the database, and complete the software installation on the
remaining clients when there is time.
However, if existing tables are modified and their version number is changed, users are not
allowed to connect to the higher revision database with the lower revision Live
Collaboration software. The user receives a warning that they must install new software
and the application shuts down. Refer to the current Program Directory or perform an
Upgrade Analysis to find out the extent of the schema change the upgrade will perform.
Upgrade Analysis
You can use the validate upgrade command to report the actions that will be taken
by an upgrade without actually performing the upgrade. This allows System
Administrators to assess the scope and impact of the upgrade and determine what
Chapter 7: Installing the Studio Modeling Platform
143
preparatory actions might be appropriate, regarding scheduling and system resource
allocation.
You first install the new version of MQL that points to the existing database, and then run
the validate upgrade command against the old database.
Tables are processed for validate upgrade in the same order as they would be
processed by the actual upgrade: first the administration tables, then the vault/store tables.
A header is output to separate the administration upgrade steps from the vaults/stores
upgrade steps.
The MQL command is:
validate [level N] upgrade;
Where N is either 0 or 1, indicating the level of detail required:
•
level 0 lists all tables indicating which are changing and which are not, with old
and new version numbers. For example:
MQL<3>validate level 0 upgrade;
Administration tables
Unchanged: mxSchema version 1
Unchanged: mxLicense version 1
Unchanged: mxOid version 1
Unchanged: mxIcon version 1
Unchanged: mxDesc version 1
Upgrade: mxLattice version 1 -> 2
Unchanged: mxStore version 1
Upgrade: mxUser version 6 -> 9
...
Tables for vaults and stores
Unchanged: lxOid_%s version 1
Unchanged: lxImg_%s version 1
Unchanged: lxDesc_%s version 1
Unchanged: lxBO_%s version 7
Upgrade: lxRO_%s version 5 -> 8
Unchanged: lxString_%s version 1
Unchanged: lxReal_%s version 1
...
•
level 1 provides level 0 output but also includes the SQL command(s) that will be
run to perform each upgrade step. This is the default if the level clause is not included.
For example:
MQL<2>validate upgrade;
Administration tables
Unchanged: mxReportField version 1
Unchanged: mxForm version 1
Upgrade: mxField version 1 -> 2
update mxField set mxValue=null,mxLabel=null where
mxType=12
Unchanged: mxTTable version 1
Unchanged: mxQuery version 1
Unchanged: mxCue version 6
Unchanged: mxMail version 1
144
ENOVIA Live Collaboration Installation Guide
Upgrade: mxMailRcp version 1 -> 2
create index mxMailRcp_mxTo_Index on mxMailRcp(mxTo)
Upgrade: mxSet version 5 -> 6
update mxSet set mxKind=0 where mxKind is null
Unchanged: mxSetObj version 1
Unchanged: mxVer6 version 1
Upgrade: mxServer version 1 -> 7
alter table mxServer add mxTZ varchar2(64)
update mxMail set mxDate=mxDate-(-300/1440)
update lxBO_d1ff63d2 set lxCrDate=lxCrDate-(-300/1440)
update lxBO_d1ff63d2 set lxModDate=lxModDate-(-300/1440)
update lxBO_d2001d35 set lxCrDate=lxCrDate-(-300/1440)
...
Tables for vaults and stores
Unchanged: lxOid_%s version 1
Unchanged: lxImg_%s version 1
Unchanged: lxDesc_%s version 1
Unchanged: lxBO_%s version 7
Upgrade: lxRO_%s version 5 -> 8
update lxRO_d1ff63d2 set lxRelRul=1 where lxRelRul is null
update lxRO_d2001d35 set lxRelRul=1 where lxRelRul is null
No change to lxRO_d1ff63d2
No change to lxRO_d2001d35
create index lxRO_d1ff63d2_lxType_Index on
lxRO_d1ff63d2(lxType)
create index lxRO_d2001d35_lxType_Index on
lxRO_d2001d35(lxType)
...
These examples are from running validate upgrade with Matrix 8.0.2 software
against a version 6.0.1 database—a major upgrade.
Oracle
Configuration
ENOVIA Live Collaboration is a client to the database. For Oracle environments, all
upgrades involve adding or deleting tables, indexes, and constraints of one Oracle user
only. Sometimes the upgrade adds a column to a table or modifies the field contents of a
column. Each of these actions is bounded by a transaction across all vaults.
Adding or deleting tables does not require a lot of system resources. However, applying
indexes and constraints impact rollback segments, redo logs, and the Temp tablespace.
And modifying field content data can impact rollback segments and redo logs very
significantly.
When upgrading all databases, always follow these generic rules:
•
Always have a complete backup before upgrading.
Always run upgrade with sql tracing on. Use the following:
trace type sql filename sqlupgrade.log;
•
For upgrades that involve major data modifications, use the following additional
guidelines. When upgrading a small database (less than 25,000 business objects)
observing these rules should be sufficient:
•
Assign 3 large, online rollback segments and ensure that rollback tablespaces can
auto-extend, also ensuring that sufficient disk space is available. Turn off all other
rollback segments except system.
Chapter 7: Installing the Studio Modeling Platform
145
•
Ensure that Temp tablespace and datafiles can auto-extend.
•
Always use a minimum of 4 redo logs with a minimum of 10MB per redo log.
•
Modify init<SID>.ora, setting the Log_buffer to at least 16MB and
log_checkpoint_interval to a very large number (suggestion: 4096000) for
the upgrade only.
•
It is recommended that you first upgrade a test database in order to benchmark
success and elapsed time.
For major upgrades of large databases, also follow additional procedures provided in the
Program Directory included with the new ENOVIA Live Collaboration release.
Running the
Upgrade
Upgrades should only be performed when required. Higher version software will work
against a database that has not been upgraded. However, if a new feature requires a new
table, it may not be usable. Also, when new features of the higher version software are
used, the upgrade command may affect this data. Refer to the Program Directory for
specifics.
To verify that the upgrade was successful, make sure no errors resulted in running the
upgrade command. To see a complete list of tables, run validate upgrade after the
upgrade is complete.
To upgrade the database
1. Install the new Studio Modeling Platform software on all client machines. New
software clients will be able to run against older version databases.
mql< >
2. Modify the command line that starts MQL so that an error log is generated. For
example, on Windows, change the shortcut for MQL as follows:
ENOVIA_INSTALL\Mql.exe –stdout:c:\temp\upgrade.txt
-stderr:c:\temp\upgrade.err.
On UNIX, use this MQL command syntax to generate an error log:
mql INPUTFILE 2> LOGFILE
3. Set context to a System Administrator user (for example, creator). Enter the following
commands:
mql< > verbose on;
mql< > upgrade;
Older version clients will no longer be able to connect to the upgraded database.
4. Be sure the Live Collaboration server and Matrix Web Navigator software are
upgraded as well.
Upgrade Warnings
Upgrade may encounter errors on existing tables due to rollbacks (such as tablespace and
other admin related issues). While it is difficult to catch all possible errors and roll back up
to the last successful sql command, upgrade can look for certain expected error messages
that need to be ignored (and does so). If the error is one of the following, upgrade issues
warnings (and does not error) and updates the mxSchema table:
146
ENOVIA Live Collaboration Installation Guide
1. ORACLE
•
ORA-00955 (Name is already used by an existing object)
•
ORA-00275 (Such a referential constraint already exists)
•
ORA-02260 (Table can have only one primary key)
2. DB2
•
SQLSTATE=42710 (Object already exists)
•
SQLSTATE=01550 (Index already exists)
•
SQLSTATE=42889 (Cannot have more than one primary key)
However, if the error is something other than these valid error messages, upgrade will
error and the mxSchema will not get updated. The DBA needs to correct it on his/her own
and then re-run upgrade.
After the Upgrade
The upgrade command for V6R2011x creates tsee if there are duplicate objects in your
system, you can run:
If you found duplicates but don’t want to allow it, fix the objects (that is, rename so all are
unique) before running upgrade TNR. To m:
upgrade TNR [notglobal] [tablespace DBTABLE] [indexspace
DBINDEX];
Only use notglobal if you found duplicate objects in the database and want to allow
duplicate TNRs in different vaults.
Include tablespace and indexspace if you want a separate space for the mxTNR table and
its indices. This is recommended. upgrade TNR may take an hour or more to finish.
Index analysis
Once the database has been fully upgraded, runvalidate index;
this is a time-consuming operation (approximately 30 mins per 10 million objects), but
can be interrupted (killed) and restarted to pick up from where it left off. If not run, these
ids are generated upon request, so VPM integrations won’t fail, but running the command
now could improve performance of all VPM operations.
Physical and logical IDs are not required for other collaborative business process products.
If you do choose to run this command, you should use a separate tablespace and
indexspace for the new MxIdent table. For example:
set system tablespace DBTABLESPACE;
set system indexspace DBINDEXSPACE;
upgrade physicalid;
Chapter 7: Installing the Studio Modeling Platform
147
Uninstalling ENOVIA Studio Modeling Platform
on UNIX/Linux
To uninstall the ENOVIA Studio Modeling Platform software on UNIX/Linux
1. Delete the ENOVIAHOME directory.
Uninstalling ENOVIA Studio Modeling Platform
on Windows
To uninstall the ENOVIA Studio Modeling Platform software on Windows
1. Remove the ENOVIA Studio Modeling Platform-related shortcuts from the Start >
All Programs > Dassault Systemes Software V6R2011x menu.
2. Delete the ENOVIA_INSTALL directory.
148
ENOVIA Live Collaboration Installation Guide
8
Installing the Live
Collaboration Server
Overview
The Live Collaboration Server tier includes:
•
A third party Web or Application Server
•
The Live Collaboration Kernel
•
The mid-tier RMI Live Collaboration Server
The Full Text Search Server with Autonomy has its own installer. Refer to “Installing
Advanced Search” under Unified Live Collaboration > Live Collaboration Platform >
Full Text Search Server with Autonomy in the ENOVIA online documentation for details.
Web or
Application Server
Initially, the term “Web server” was used to mean an HTTP server that simply managed
Web page requests from the browser and delivered HTML documents, or Web pages, in
response. As the technology progressed, Web servers began to be used for server-side
processing in the form of CGI scripts and Active Server Pages (ASPs), which provided
functions such as database searching. The next-generation, Java-based Web servers of
today use Java servlets and JavaServer Pages (JSPs) to perform the processing, but also
support CGI and ASPs. JSP and servlet-enabled Web servers are sometimes referred to as
Application Servers.
149
The term Application Server has also evolved. In a client/server environment, an
Application Server could have been added to perform business logic in a middle tier.
Today, the term Application Server is used to mean the server that sits along with or
between the Web server and the databases and legacy applications, enabling a
browser-based application to link to multiple sources of information via servlets, JSPs,
and Enterprise JavaBeans (EJBs).
Many Application Servers are also Web servers; however, in large sites, separate
Application Servers may be linked to one or more Web servers to provide load balancing
and fault tolerance for high-volume traffic. For smaller Web sites, the Application Server
may be used as the Web server.
When running MQL from CGI, you must add the HOME parameter to the MQL scripts.
The value for the HOME parameter should be the home directory of the user running this
session. It can be any valid path. For example, enovia HOME/.
Live Collaboration
Kernel
The Live Collaboration Kernel includes:
•
dynamic modeling
•
business information services (lifecycle, workflow, association, replication, content
management, etc.)
•
FlashDB, providing the high performance method of moving data from the storage
tier into the mid-tier, while maintaining a flat memory profile
•
Adaplets, for managing connected systems
•
stores, for connecting to various file servers
The kernel is packaged as a shared library (on UNIX) or .dll (on Windows) and provided
when the ENOVIA Live Collaboration Server is installed.
Java/RMI Server
The ENOVIA Live Collaboration Server is a Java/RMI server program that provides
communication services between Web Application Servers and ENOVIA Live
Collaboration. In fact, Business Process Services becomes available inside of these
Internet servers, via the Live Collaboration kernel.
When the Collaboration Server is installed, the following are available to the Application
Server:
•
Live Collaboration kernel (library file)
•
web.xml file
•
ENOVIA Live Collaboration servlets (in eMatrixServletRMI.jar)
•
ENOVIA Live Collaboration Studio Customization Toolkit classes (in
eMatrixServletRMI.jar)
•
the standard RMI required classes (in eMatrixServletRMI.jar)
•
MQL is included.
When the Web server receives an XML packet, it uses the ENOVIA XML servlet to
communicate with the mid-tier server. HTML applications can use JavaServer Pages that
include Java code which can in turn call the servlets. Both the servlets and the JSPs use the
Studio Customization Toolkit classes to communicate with the server and therefore the
Live Collaboration kernel.
150
ENOVIA Live Collaboration Installation Guide
The web.xml file is configured to let the server know the class paths for the servlets as well
as other configuration settings. It is installed with the server and is used by the servlets.
Refer to Web.xml in Chapter 10 for more information.
In the sections that follow, more information on the ENOVIA Live Collaboration Server is
provided, as well as installation instructions. Refer also to the Program Directory for the
given release before installing.
RIP: RMI
In-process
RMI In-process (RIP) is the default installation option for the ENOVIA Live Collaboration
Server that allows RMI to run within the ENOVIA Live Collaboration kernel.
The recommended configuration for RMI is RIP mode.
RMI In-process uses the ENOVIA Live Collaboration Server implementation classes, but
instead of going through a registry and invoking a separate process, the server classes are
loaded directly into the client’s address space. Instead of communicating with the
ENOVIA Live Collaboration Server, ENOVIA Live Collaboration actually links with it,
removing the RMI marshalling/unmarshalling and the need for the additional RMI
(daemon) process. Database communication is directly between the ENOVIA client and
the database. This should be notably more efficient in situations that involve processing an
extremely large number of transactions.
The other configuration option, RMI Gateway provides load balancing by using multiple
ENOVIA Live Collaboration Server processes to handle requests. Since RIP does not use
multiple ENOVIA Live Collaboration Servers, load balancing can be accomplished by
running multiple Application Servers for each CPU.
The key to a successful deployment is access to the classes and properties required. For
RMI RIP mode, this is easily handled by the J2EE archive file since the Application
Server, the ENOVIA Live Collaboration Server, and the Live Collaboration kernel all
share a JVM.
For non-RIP RMI, the correct classpath is defined at runtime by rmireg, using
ComputedClassPath. Refer to the description of MX_CLASSPATH in Configuring
ENOVIA Live Collaboration in Chapter 9 for details. During J2EE deployment with
non-RIP RMI, all of the jars in the war file are copied to SERVERHOME/<platform>/
docs/javaserver/ (UNIX) or SERVER_INSTALL\intel_a\docs\javaserver\
(Windows). The framework.properties file is copied to SERVERHOME/managed/
properties/ (UNIX) or SERVER_INSTALL\managed\properties\ (Windows).
This is to ensure that JPOs have access to them.
RMI Gateway
RMI Gateway is an option that offers load balancing by using multiple ENOVIA Live
Collaboration Server processes to handle requests. In the simplest case, there is a single
instance of the RMI Gateway, and at least two instances of the ENOVIA Live
Collaboration Server, eMatrixServletRMI.jar. The RMI Gateway and ENOVIA Live
Collaboration Servers each run inside a Java2 activation daemon and have access to their
own Live Collaboration kernel. For example, you can set up the Gateway and two (or
more) servers with the RMI Gateway evenly distributing requests to the other processes. In
this case, once the request is passed, the client deals directly with the secondary server,
reducing the load on the Gateway.
Chapter 8: Installing the Live Collaboration Server
151
Optionally, instead of using a round-robin algorithm, one server may handle all requests
for a certain amount of time or for a certain number of operations. It would then perform
an implied quiesce function (that is, finish up currently running threads, complete RMI
garbage collection, and then shut itself down). At the same time, the other server begins to
handle new requests, providing uninterrupted, seamless request handling.
The client’s host URL should reference the port where the RMI Gateway is registered, the
default being 1099.
The default configuration of RMI Gateway distributes requests between servers in a
round-robin fashion. To configure the Gateway to use the quiesce function, refer to
Configuring the Gateway for Quiesce on Windows.
152
ENOVIA Live Collaboration Installation Guide
Installing a Web or Application Server
The ENOVIA Live Collaboration Server uses J2EE/RMI technology and works in
conjunction with a Web Application Server. For more information including configuration
details, refer to:
•
For WebLogic http://edocs.bea.com/common/docs100/install/index.html
•
For WebSphere http://www-3.ibm.com/software/info1/websphere/index.jsp
•
For Sun Java Server http://docs.sun.com/app/docs/doc/819-3657
•
For Tomcat http://tomcat.apache.org/tomcat-6.0-doc/index.html
ENOVIA supports only those Application Server versions listed in “Prerequisites” in the
Program Directory for a given release. If a newer version is available that is not explicitly
stated as qualified for ENOVIA Live Collaboration, it is highly recommended NOT to use
it unless otherwise stated for that specific platform.
If a qualified version includes a patch level (fix level, MP, etc.), it is highly recommended
to use this patch level although it is possible to use a higher patch level than the qualified
level. A patch level older than the level qualified should NOT be used. Higher patch levels
can be used since exact patch levels may not be available at the time of deployment.
Higher patch levels can improve security and/or performance and may be beneficial.
While most patch levels do not impact the functionality or stability of the system, it is
possible for a higher patch level to cause interoperability issues. If this is the case,
ENOVIA may recommend installing a higher patch level or reverting back to the qualified
patch level.
After every type of system change, such as a JVM patch or Application Server service pack
installation, it is highly recommended to check all configuration files (such as jvm.cfg,
rmireg.sh, etc.) to ensure that no important settings were changed.
There are different levels of servers that may be used for internet access, and each may be
used with the ENOVIA Live Collaboration Server as follows:
1. Simple Web server
When using the ENOVIA Live Collaboration Server, a simple Web server may be
used for custom Java client applications written with the Studio Customization
Toolkit that are not JSP-based. One or several simple Web servers may also be used to
front-end an enterprise’s Website. Refer to Optional Static Content Server for more
information.
2. A JSP/servlet-enabled Web or Application Server
When servlets and JSP applications will be used, the Web server must be JSP- and
servlet- enabled. All ENOVIA products require at least this level of Web server.
ENOVIA-specific configuration is required.
This section describes how to set up and configure the qualified Application Servers
required for level 2 use. The main tasks involved in installing and configuring a Web or
Application Server are:
1. Install a supported Web server using its installation guide and the guidance provided
below. Most supported Application Servers include a Java Development Kit, which
can be used by ENOVIA Live Collaboration as well, but in some cases you’ll need to
install it.
Chapter 8: Installing the Live Collaboration Server
153
2. Configure the Application Server as required.
3. Make sure the Application Server is operational before installing the Live
Collaboration Server.
4. After confirming that the Application Server is operational, you can install the
ENOVIA Live Collaboration Server by following the instructions in Preparing to
Install the ENOVIA Live Collaboration Server.
Since FCS and PDF rendering functions require access to Live Collaboration native code
libraries, you must install the ENOVIA Live Collaboration Server on each Application
Server that will be used for ENOVIA Live Collaboration access.
Tuning Pool Sizes
When many (i.e., 20 or more) users try to check in files simultaneously, FCS errors can
occur. To avoid this, be sure to tune pool sizes (e.g., for JDBC connections, Stateless
Session EJBs, and MDBs) to maximize concurrency for the expected thread utilization.
Sun Java System Application Server. Refer to http://docs.sun.com/app/docs/doc/
819-3681/abefm?l=En&a=view.
Tomcat. Refer to http://tomcat.apache.org/tomcat-6.0-doc/config/executor.html.
WebLogic. Refer to the following sources:
•
For WebLogic Server releases 9.0 and higher—A server instance uses a self-tuned
thread pool. The best way to determine the appropriate pool size is to monitor the
pool’s current size, shrink counts, grow counts, and wait counts. See Thread
Management in the WebLogic documentation. Tuning MDBs are a special case. See
Chapter 11, Tuning Message-Driven Beans, in the WebLogic documentation.
•
For releases prior to WebLogic Server 9.0—In general, the number of connections
should equal the number of threads that are expected to be required to process the
requests handled by the pool. The most effective way to ensure the right pool size is to
monitor it, and to make sure it does not shrink and grow. See How to Enable the
WebLogic 8.1 Thread Pool Model in the WebLogic documentation.
WebSphere. Refer to http://publib.boulder.ibm.com/infocenter/wasinfo/v5r1//
index.jsp?topic=/com.ibm.websphere.base.doc/info/aes/ae/uejb_rthrd.html.
Java Development
Kit
A version of the JDK is required for use with JPOs, qualified Application Servers, the
ENOVIA Live Collaboration Server, and the Studio Customization Toolkit. For complete
details, see the Program Directory for the given release.
Do not install the JDK to a directory with spaces in the name, or you will be unable to
install Live Collaboration software.
You can test the Java installation by opening the
JDK_INSTALL\demo\applets\nervoustextexample1.html. If the text is “dancing” in a
Web browser window, the installation is OK.
154
ENOVIA Live Collaboration Installation Guide
Java options
When the ENOVIA Live Collaboration Server is installed, recommended Java options are
set by default. Refer to JVM Options for details.
JDK notes
A version of the Java Development Kit (JDK) is required for use with JPOs, qualified
Application Servers, the ENOVIA Live Collaboration Server, and the Studio
Customization Toolkit. Each UNIX O/S vendor has their own version of the JDK, and Sun
and IBM, as well as BEA have JDKs for Windows. WebLogic, WebSphere, and the Sun
Java Live Collaboration Server all include a JDK when they are installed. In most cases,
Sun’s JDK should be used. The exceptions are as follows:
•
The JDK embedded with the WebSphere Application Server (on AIX and Windows,
IBM's JDK is included, on Solaris, Sun's JDK is included) can only be used to run
ENOVIA (CBP and VPM) applications deployed by this Application Server. This
JDK cannot be used to run other non-Application Server based ENOVIA tools/
applications (MQL command line, etc.).
To support this requirement, you must specify the operating system level JDK (and
not the JDK embedded with WebSphere) during ENOVIA Live Collaboration Server
installation. This JDK will be used to run non-Application Server based applications
while the JDK embedded with WebSphere will be used to run the applications
deployed by it. The operating system JDK you specify must be supported by
ENOVIA and correspond to the JDK requirement listed in “Prerequisites” in the
Program Directory for the given release.
•
When using WebLogic on AIX, use IBM’s JDK.
•
When using WebLogic on Windows the embedded JDK is JRockit. This means if you
are also running a stand-alone Live Collaboration Server, you must configure that
Live Collaboration Server to use the JRockit JDK and not the Sun JDK.
Sun’s JDK should be used with all other Application Servers.
•
If the Live Collaboration Server’s first connection to the database fails, you should be
suspicious of the JDK version. Use the java -version command and if it
indicates a JDK mismatch, install and point to the correct vendor’s JDK.
•
Programs (JPOs or custom applications) that will be run through the Live
Collaboration Server must be written with the same (or lower) version of the JDK as
the Application Server uses. Ideally in a production environment, all components
(application and Live Collaboration Server, as well as Studio Modeling Platform
clients) will use the same version of the JDK.
•
When using the ENOVIA Live Collaboration Server in RIP mode, the same instance
of Java used by the Application Server is used by the Live Collaboration Server. Use
the path to this Java during Live Collaboration Server installation). If, however, you
are using RMI Gateway configuration, you can optionally install and use a separate
JDK instance. You may want to do so if your JPOs, beans, or custom JSPs rely on a
newer version of the JDK. You must also install the JDK if you are installing and
using a Tomcat server, since one is not bundled with it.
Supported Application Servers and JDKs listed are for both 32-bit and 64-bit versions.
Chapter 8: Installing the Live Collaboration Server
155
Installing a
WebLogic Server
WebLogic Server and WebLogic Express, from BEA Systems, are both supported for use
with the ENOVIA Live Collaboration Server as outlined in the Program Directory for the
given release.
BEA’s WebLogic Server implements the Java 2 Enterprise Edition (J2EE™) platform
specification, including Servlets, Java Server Pages (JSP), Enterprise JavaBeans (EJB™),
Java Messaging Services (JMS), and other platform services. Additionally, you can deploy
certain ENOVIA components as J2EE-compliant using WebLogic. For more information
about J2EE deployment and ENOVIA, see Chapter 10, Deploying J2EE.
Install WebLogic as documented in WebLogic’s installation guide, available online at
http://e-docs.bea.com/. Follow one of the procedures for installation, as well as for System
Administration. If installing on Windows, you can choose to install as a service.
The Application Server’s embedded JDK must be 64-bit in order to run with 64-bit
ENOVIA software.
Changing the server’s port number
By default, WebLogic listens for HTTP requests on port 7001. To change this default,
change the following setting in the WebLogic startup script (startWebLogic.cmd for
Windows or startWebLogic.sh for UNIX):
-Dweblogic.system.listenPort=NEW_PORT_NUMBER
NEW_PORT_NUMBER should be the port you wish to use.
Java setting: -XX:MaxPermSize
This setting is the amount of memory set aside for loading all necessary classes that are
needed by an application. If using the Live Collaboration Server in RIP mode on Windows
with WebLogic, you will need to set MaxPermSize=120M (at least). Otherwise you
may see java.lang.OutOfMemoryError after about 2 hours of run time. If the
problem persists, increase the setting to 256m.
Configuring for large FCS synchronization operations
If WebLogic is used with an FCS performing large synchronization operations of 1500
files or more, the following configuration is requred:
1. From the admin console, navigate to Server > Protocols and select the http tab where
you can configure http servlets attributes.
2. Verify that the Max Post Size attribute is set to at least 5mb (5242880 bytes). You can
choose to leave the default value of -1 (unlimited).
3. Verify that the HTPP Max Message Size advanced attribute is set to 1 (unlimited)
since there is no limit on the data stream size created or exchanged by ENOVIA
applications.
4. Save any changes.
156
ENOVIA Live Collaboration Installation Guide
Installing
WebSphere
WebSphere can be used with the ENOVIA Live Collaboration Server as outlined in the
Program Directory for the given release. When you install Websphere you can also install
the IBM HTTP Web server, or use a proxy server as a front end. IBM’s JDK is also silently
installed on AIX and Windows. Follow the installation instructions found at http://
publib.boulder.ibm.com/infocenter/wasinfo/index.jsp for your version and platform.
IBM’s WebSphere Application Server implements the Java 2 Enterprise Edition (J2EE™)
platform specification, including Servlets, Java Server Pages (JSP), Enterprise JavaBeans
(EJB™), Java Messaging Services (JMS), and other platform services. Additionally, you
can deploy certain ENOVIA components as J2EE-compliant using WebSphere. For more
information about J2EE deployment and ENOVIA, see Chapter 10, Deploying J2EE.
Web Navigator checkins with WebSphere and its http server
When using WebSphere with its http webserver (on port 80 vs. connecting directly to the
Application Server on port 9080), errors may occur when checking in medium sized files
(12m) with Web Navigator. (“Socket write error” or “413 Request Entity Too Large”
errors). These errors indicate that you must configure the PostSizeLimit to -1 in the
plugin-cfg.xml file. You must then regenerate the plugin and restart the appserver.
For more information see:
http://publib.boulder.ibm.com/infocenter/weahelp/index.jsp?topic=/
com.ibm.websphere.wea.doc/cfg_post_limit.html
FCS file transfer timeout
On WebSphere if checkin/checkout to FCS takes longer than the timeout configured on
the MCS (Main Collaboration Server) Application Server, the operation may result in a
timeout error and the checkin will not be successful.
ENOVIA tests show that files up to 1GB (a fairly large file) can be checked in/out in less
than fifteen minutes to an FCS server accessible on the same LAN network as the client,
so this is unlikely to be a problem with a typical session timeout of 20-30 minutes.
To calculate the relationship between the file size, file transfer rate, and session timeout,
the following calculation can be used:
Total File Transfer Time = FileTransferRate * FileSize
In order for Total File Transfer Time to be less than the Session Timeout, it is necessary
for:
SessionTimeout > Transfer Rate * FileSize
Therefore, for a given SessionTimeout, the largest FileSize that could be transferred would
be:
FileSize = SessionTimeout/FileTransferRate.
Configuring for large FCS synchronization operations
If WebSphere is used with an FCS performing large synchronization operations of 1500
files or more, the PostSizeLimitParameter attribute for the node(s) that host the FCS must
be -1 (unlimited) or at least 5mb (5242880 bytes). WebSphere is usually deployed behind
one or more web servers (such as Apache) and is connected through HTTP transport
Chapter 8: Installing the Live Collaboration Server
157
plugins. The HTTP transport plugins configuration file, plugin-cfg.xml, contains the
PostSizeLimitParameter attribute for each server cluster node.
Promoting tasks in ENOVIA applications
On AIX with Websphere, the -Xmso1152k variable must be added to the JVM
configuration for Websphere to prevent it from possibly crashing when certain tasks are
promoted. This variable can be added through the WebSphere server console or directly to
the server.xml file. The full JVM argument should look like this:
"-Xmso1152k -Xss1024k -Xms640m -Xmx640m -Dclient.encoding.override=UTF-8
-Ddefault.client.encoding=UTF-8 -Dfile.encoding=UTF-8"
UTF-8 settings are included in this argument. If you are not using UTF-8, these settings
are not required.
Installing the Sun
Java System
Application Server
The Sun Java System Application Server (previously Sun ONE/iPlanet) is available for
use with the ENOVIA Live Collaboration Server as outlined in the Program Directory for
the given release.
To install the Sun Java System Application Server, see the appropriate Sun documentation
at http://docs.sun.com/app/docs/doc/819-3657.
StackSize
After installing, increase the StackSize. For Version 9, edit .../SUNWappserver/
domains/domain1/config/domain.xml to include the stack size as shown below.
<jvm-options>-Xmx512m</jvm-options>
<jvm-options>-Xms512m</jvm-options>
<jvm-options>-XX:NewSize=256m</jvm-options>
<jvm-options>-XX:MaxNewSize=256m</jvm-options>
<jvm-options>-XX:SurvivorRatio=2</jvm-options>
<jvm-options>-XX:MaxPermSize=128m</jvm-options>
<jvm-options>-XX:PermSize=32m</jvm-options>
<jvm-options>-Xss1024k</jvm-options>
<jvm-options>-Dfile.encoding.override=UTF-8 -Dfile.encoding=UTF-8
-Dclient.encoding.override=UTF-8</jvm-options>
RIP settings
If you are using RIP, the following permissions need to be provided in .../
SUNWappserver/domains/domain1/config/server.policy:
// Basic set of required permissions granted to
grant {
permission java.lang.RuntimePermission
permission java.lang.RuntimePermission
permission java.net.SocketPermission
permission java.io.FilePermission
"read,write,delete,execute";
permission java.util.PropertyPermission
158
all remaining code
"loadLibrary.*";
"queuePrintJob";
"*", "connect";
"<<ALL FILES>>",
"*", "read,write";
ENOVIA Live Collaboration Installation Guide
permission
permission
permission
permission
java.lang.RuntimePermission "createClassLoader";
java.lang.RuntimePermission "getClassLoader";
java.lang.RuntimePermission "modifyThreadGroup";
java.lang.RuntimePermission "setIO";
};
LD_LIBRARY_PATH update
The following change is required in the asadmin startup script before you can start the
Live Collaboration Server and deploy the .war file with Sun Java System 9.1:
Change:
LD_LIBRARY_PATH="$AS_NSS":"$AS_INSTALL/
lib":"$AS_ICU_LIB":"$LD_LIBRARY_PATH";export LD_LIBRARY_PATH
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$LD_LIBRARY_ENOVIA_PATH
To:
LD_LIBRARY_PATH="$AS_NSS":"$AS_INSTALL/
lib":"$AS_ICU_LIB":LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$LD_LIBRARY_
ENOVIA_PATH
Installing Tomcat
To install the Tomcat Application Server, see the appropriate Tomcat documentation. For
instructions about integrating Tomcat with Apache, see http://www.serverwatch.com/
tutorials/article.php/10825_2203891_2.
Tomcat does not include a JDK, so you must install it before installing Tomcat. ENOVIA
supports Tomcat on the platforms and with the JDK as outlined in the Program Directory
for the given release.
Tomcat 5.5 initializes via the Tomcat service even if you run it from the start command.
This means that the Server Startup Configuration Checker will give Critical warnings on
Java settings, that may not be real issues, as described in mxAudit.log File. Use the Tomcat
log to verify these settings are correct and disregard the warnings.
On AIX, before starting Tomcat you need to edit the file setclasspath.sh in the bin
directory of Tomcat, by commenting out (or deleting) the following 2 lines (the first and
the third, leave the CLASSPATH line):
#if [ "$1" = "debug" -o "$1" = "javac" ] ; then
CLASSPATH="$JAVA_HOME"/lib/tools.jar
#fi
Configuring for large FCS synchronization operations
If Tomcat is used with an FCS performing large synchronization operations of 1500 files
or more, you must add or modify the maxPostSize attribute value to at least 5mb (5242880
bytes). Add or modify the attribute in the <Connector> section of the server.xml file
(located in TOMCAT_HOME/conf/server.xml) for the FCS:
<Connector port="9090" protocol="HTTP/1.1"
connectionTimeout="20000"
redirectPort="8445"
maxPostSize="5242880" />
Chapter 8: Installing the Live Collaboration Server
159
Optional Static
Content Server
It is recommended that a static content server (a “reverse hosting server”) is implemented
for a production instance of the ENOVIA Live Collaboration Server. This is a simple Web
server front end (using products such as Apache or IIS) that is configured to serve all static
content and then pass any dynamic requests on to the Application Server. This is
especially crucial if there is WAN access to the ENOVIA products.
The importance of a front-end web reverse hosting server can be shown by breaking down
the requests from frequently used application pages. For example, when logging into an
ENOVIA product from emxLogin.jsp, there are about 11 requests for static content
(depending on the version used) and only 1 request for dynamic content generated.
Loading or refreshing the primary (content) page of the application (emxNavigator.jsp)
results in approximately 7 HTTP requests for dynamic content and the actual number of
requests for static content depends upon the browser configuration for browser caching:
•
“Automatic” browser caching generates about 10 requests
•
“Automatic” browser caching on startup generates about 52 requests
•
“Every page” browser caching generates about 164 requests
The default is Automatic, however, previous versions of ENOVIA products recommended
“Every page” to ensure that the newest version of any page was used. The Automatic
setting is the recommendation for Version 10.7 and higher.
Refer to Using a Web server in addition to an application server for more information.
160
ENOVIA Live Collaboration Installation Guide
Using a UNIX or Linux Live Collaboration
Server without a Monitor
If you want to run the ENOVIA Live Collaboration Server on UNIX or Linux on a system
that does not have a display, at a minimum you need to install an X-Windows server to
simulate a display. You may also need to install X-Windows if you're using a proxy server
and get the following errors:
java.lang.InternalError: Can't connect to X11 window server
using ':0.0' as the value of the DISPLAY variable
java.lang.NoClassDefFoundError
Some “headless” systems don’t even have a graphics card; in this case, you would need an
X virtual frame buffer (Xvfb), which is an X server that does not rely on any display
hardware or input devices for the simulation. It is an included component of X11R6, but
not in earlier X releases. Be sure to use a version of X server that includes Xvfb.
If you want to use Image Caching in ENOVIA products or custom applications with
X-Windows only (not Xvbf, and you have a graphics card but no monitor), you’ll need to
set the -headless java option in mxEnv.sh and rmireg.sh files as follows:
1. Add the “-Djava.awt.headless=true” option to MX_JAVA_OPTIONS in the mxEnv.sh
file. For example:
MX_JAVA_OPTIONS="-Xss512k [-Xmso768k (IBM JDK on AIX)]
-Xms1024m -Xmx1024m -XX:NewSize=128m -XX:MaxNewSize=128m
-XX:MaxPermSize=128m -XX:SurvivorRatio=3
-Djava.awt.headless=true"
2. Add the “-Djava.awt.headless=true” option to RMID_JAVA_OPTIONS in the
rmireg.sh file. For example:
RMID_JAVA_OPTIONS="-C-Xss512k -C-Xms1024m -C-Xmx1024m
-C-Djava.awt.headless=true"
These options take care of settings for ENOVIA Live Collaboration, but if needed, you
must ensure that the Application Server makes use of these settings; that is, some
additional configuration may be necessary for your Application Server.
However, if you want to use KavaCharts in Program Central, you should NOT set the
headless java option, just be sure to have X-Windows, or if needed, Xvfb installed.
Chapter 8: Installing the Live Collaboration Server
161
Preparing to Install the ENOVIA Live
Collaboration Server
The ENOVIA Live Collaboration Server provides another access mechanism to the data
that already exists in the ENOVIA Live Collaboration database. Therefore, you must first
have an ENOVIA Live Collaboration database set up before installing a Live
Collaboration Server. Generally, the version of Studio Modeling Platform should match
the version of the Live Collaboration Server, but refer to the Program Directory if it
appears that a new version of Studio Modeling Platform or the Live Collaboration Server
is released without the other. Also required is a machine with one of the configurations
shown in What Needs to be Installed?.
You can upgrade the ENOVIA Live Collaboration Server and Studio Modeling Platform
components without upgrading Business Process Services or other ENOVIA products.
The RAM requirements listed in “Prerequisites” in the Program Directory for the given
release are guidelines only, since they vary greatly depending on the number of users,
functions performed, etc. Other factors such as the number of processors and other
hardware variations must also be considered.
A Web or Application Server must be installed and operational before installing a Live
Collaboration Server. Refer to Installing a Web or Application Server for details.
Since FCS and PDF rendering functions require access to ENOVIA Live Collaboration
native code libraries, you must install a Live Collaboration Server on each Application
Server that will be used for ENOVIA Live Collaboration access.
There are two kinds of Live Collaboration Server installation routines:
•
Major installation, which installs all Live Collaboration Server components and
modifies startup scripts and property files. Instructions for performing major
installations are described in the sections Installing ENOVIA Live Collaboration
Server on UNIX/Linux and Installing ENOVIA Live Collaboration Server on
Windows.
Once the J2EE Live Collaboration Server is installed, configuration adjustments can be
made. Some are optional and some are required. Perform the installation in the order
indicated below.
General
Installation for
ENOVIA Live
Collaboration
Server
1. Install the DS License Server. The Dassault Systèmes License Server or DS License
Server is a prerequisite of the ENOVIA Live Collaboration Server and is responsible
for installing and making your company’s user licenses available for use. For more
information, see the Dassault Systèmes License Server Installation and
Configuration Guide.
2. Install the Live Collaboration Server as described in this section.
3. Follow the instructions for obtaining and assigning your user licenses in the Dassault
Systèmes Licensing Essentials Guide.
162
ENOVIA Live Collaboration Installation Guide
4. Install all necessary ENOVIA products as described in Installing Matrix Web
Navigator, Installing Business Process Services™ and/or Installing ENOVIA
Products.
5. If necessary, adjust the server configuration as required, including the recommended
UTF-8 configuration as described in UTF-8 Settings. Refer also to Configuring the
ENOVIA Live Collaboration Server and ENOVIA Live Collaboration Server
Environment Settings.
If you are using a Japanese environment, follow the instructions found in Configuring a
Japanese Web Environment for this step and steps 5 through 8 below.
6. Optionally adjust J2EE settings in the Web.xml or ematrix.xml file as described in
Modifying J2EE Settings.
7. Build the Web archive file as described in Building the J2EE Archive File.
8. Follow the instructions for Deploying the J2EE Archive File.
9. Optionally install an additional server as described in Installing Multiple ENOVIA
Live Collaboration Servers (RIP only).
Before Installing
ENOVIA Live
Collaboration
Server
The Live Collaboration Server machine must have access to an ENOVIA Live
Collaboration database. This means the following are prerequisites:
•
Database client software:
For Oracle, refer to the Program Directory for the given release for supported versions
and Chapter 3, Installing an Oracle Database for installation guidelines. Some
settings in the Oracle server configuration file (init<SID>.ora) may need to be
adjusted when a Live Collaboration Server is in use. Refer to Oracle Parameter File:
init<SID>.ora in Chapter 3 for more information.
For DB2, refer to the Program Directory for the given release for supported versions
and Chapter 4, Installing a DB2 Database for installation guidelines.
For SQL Server, refer to the Program Directory for the given release for supported
versions and Chapter 5, Installing an SQL Server Database for installation guidelines.
For MySQL, refer to the Program Directory for the given release for supported
versions and Chapter 6, Installing a MySQL Database for installation guidelines.
•
Optionally, ENOVIA Studio Modeling Platform to assist with troubleshooting.
However, it is not recommended that the Live Collaboration Server machine be used
frequently as a Studio Modeling Platform client. (MQL is included with the Live
Collaboration Server on both Windows and UNIX).
•
A connection (bootstrap) file that points to an ENOVIA Live Collaboration database.
You can use the included MQL executable to create a bootstrap after installation if
necessary.
Since the Live Collaboration Server can provide global access to an ENOVIA Live
Collaboration database, potentially handling a much greater number of users, be sure you
have the appropriate number and types of user licenses in your License Agreement. Users
defined as “Full” can access the database through the Live Collaboration Server, as well as
the Studio Modeling Platform applications. On the other hand, “Application” users will be
allowed access only through MQL or applications that use the Live Collaboration Server.
Refer to the Business Modeler Guide for information on the types of ENOVIA Live
Collaboration users.
Chapter 8: Installing the Live Collaboration Server
163
Installing ENOVIA Live Collaboration Server on
UNIX/Linux
Before installing any Live Collaboration Server software on UNIX from a CD-ROM you
must:
•
Create an ENOVIA user and group.
•
Mount the CD so the operating system software can access the files contained on the
disk. Refer to Mounting the CD in Chapter 7 for examples of mount commands for
each platform.
•
Remove any old versions of ENOVIA Live Collaboration Server.
•
Make sure you know:
•
•
For Oracle, the path where your tnsnames.ora file is located
•
For DB2, the path where DB2 is installed and the DB2 instance name
•
For MySQL, the path where the ODBC initialization files reside
•
The path where the Application Server is installed, and the name of the startup
script
•
The path for the JDK
Follow your OS instructions for automatic startup of mxrmirc services.
The ENOVIA Live Collaboration Server Setup program can be run in one of three
modes—graphical, console, or silent:
•
To install the Live Collaboration Server on UNIX/Linux in graphical mode, see
page 164.
•
To install the Live Collaboration Server on UNIX/Linux in console mode, see
page 177.
•
To install the Live Collaboration Server on UNIX/Linux in silent mode, see page 186.
To install the Live Collaboration Server on UNIX/Linux in graphical mode
1. Copy the <media_name>.tar.gz file, where <media_name> is the name of the media
for your platform (for example, ENOVIALiveCollaborationServer-V6R2011x.RHEL64), from the CD or ENOVIA Download page to the distribution directory.
2. Mount the CD-ROM drive. Refer to Mounting the CD in Chapter 7 if necessary.
3. Untar the <media_name>.tar.gz file to a temporary directory. Change to the
<media_name>/1/ subdirectory, and then run the Setup script as follows:
% cd /<media_name>/1
% ./StartGUI.sh
The ENOVIA Live Collaboration Server graphical Setup program starts.
164
ENOVIA Live Collaboration Installation Guide
4. Setup prompts for the installation directory. The default installation path is empty.
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
Click Browse to select a different location than the default.
Chapter 8: Installing the Live Collaboration Server
165
5. Click Next to continue.
6. Setup then displays the components available to be installed in the specified directory,
in this case, CSR - ENOVIA Live Collaboration Server. Click Cancel if you want to
end the installation, or click Next to continue.
7. Setup then asks you to enter the Java Home path. This is the location of your Java
Development Kit (JDK). Click Browse to select a different location than the default.
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
166
ENOVIA Live Collaboration Installation Guide
Click Next to continue.
8. Setup then asks you to choose a database type. Only those database types that are
supported on your particular platform are displayed. Depending on the OS, the
available database options could be any of the following:
•
Oracle, DB2, and MySQL
•
Oracle and DB2
• Oracle only
If your platform supports multiple types of databases, Oracle is the default.
A white check box means that an item is selected.
Select the desired database type. Click Next.
9. If you selected Oracle, Setup then asks you to enter the TNS_ADMIN directory. This
is the directory where your tnsnames.ora file is located. Click Browse to select a
different location than the default.
Chapter 8: Installing the Live Collaboration Server
167
Setup cannot detect the correct Oracle path on UNIX. Incorrect Oracle path selection may
abort the installation without a message indicating the reason for the failure.
Click Next to continue.
10. Setup then asks you to read and accept the terms in the Oracle Instant Client License
agreement. Again, a white check box next to an item indicates that the item is
selected. Leave the upper check box selected (the default) and click Next.
168
ENOVIA Live Collaboration Installation Guide
11. Setup then asks you to enter the location of your connection file (MATRIX-R file).
Click Browse to select a different location than the default. Click Next to continue.
If the MATRIX-R file does not yet exist, you must copy a valid bootstrap file to the
specified directory. Click OK to continue..
Installation can continue without a valid bootstrap file, but the Live Collaboration
Server will not operate without a valid connection file.
Chapter 8: Installing the Live Collaboration Server
169
12. Setup then asks you to select a deployment option. The available options are:
•
J2EE (build EAR and WAR archives)—Select this option for all supported J2EE
Application Servers. This option is required if you intend to install Advanced Search
on a dedicated machine. This is the default. See also Running the WAR Utility on
UNIX or Linux in Chapter 10.
•
None (Collaboration Kernel only)—Select this option if you intend to use custom
Studio Customization Toolkit applets or applications that do not use servlets. In this
case, an Application Server is not required, but you must configure the Live
Collaboration Server for RIP mode. See step 16.
13. Setup then asks you to select a Java heap size. This setting affects the options for Java
memory allocation. Select a Java heap size based on what your system will support.
Java Heap Size
For 32-Bit Systems
For 64-Bit Systems
Small:
256m
256m
Medium:
640m
960m
1024m
2048m
Large:
Software version V6R2011x supports only the 64-bit version of Live Collaboration Server
on both Windows and UNIX. The 32-bit version of Live Collaboration Server for Windows
is supported only for non-production use.
170
ENOVIA Live Collaboration Installation Guide
14. Setup then asks you to select the character encoding. The available options are:
•
UTF8—This option is the default, and is recommended for all implementations
besides Japanese, whether you support multiple non-English languages or only
English. When this option is selected, UTF-8 settings are added in your
environment, as described in Automated UTF-8 Settings. However, to finish
enabling UTF-8, refer to Additional Manual UTF-8 Settings.
•
Not UTF8—Select this option if your implementation must support Japanese.
Chapter 8: Installing the Live Collaboration Server
171
15. Setup then asks you where the Application server is installed. This is the location of
the startup script for applications. Below the following figure are some examples.
Application Server
Location of Startup Script
WebLogic:
WebSphere:
/app/weblogic/user_projects/
domains/base_domain
/app/WebSphere/AppServer/bin
Sun Java System Application Server:
/app/SUNWappserver7/bin
Tomcat:
/app/tomcat/bin
The following are some examples of Application Server startup script names:
Application Server
Startup Script Name
WebLogic:
startWebLogic.sh
WebSphere:
startServer.sh
Sun Java System Application Server:
asadmin
Tomcat:
startup.sh
16. Setup then asks whether you want to install the kernel in RIP mode. The available
options are:
172
ENOVIA Live Collaboration Installation Guide
•
Yes—RIP mode is the recommended configuration (and the default). This option
runs the kernel in the same process space as the Application Server. If you are
using the Sun Java Application Server and want to use RIP mode, be sure to
configure the Application Server as described in Installing the Sun Java System
Application Server.
•
No—Select this option to set up the standard RMID mode.
Chapter 8: Installing the Live Collaboration Server
173
a ) If you select no to RIP mode, Setup asks whether you want to install the RMI
Gateway. The default is No (single RMI server).
b ) If you want to use multiple RMI servers, click the button (white means selected).
Then click Next.
174
ENOVIA Live Collaboration Installation Guide
c ) If you chose yes to using multiple RMI servers, you must also specify the RMI
port number. The default is 1099.
17. Setup then asks you to enter the number of additional server processes to use for the
RMI Gateway. The minimum (and default) is 2.
Setup will assign sequential port numbers to each secondary server process used. For
example, if you accept the default of 2 for additional RMI processes, the RMI port
number entered above (e.g., 1099) will be for the Gateway, and the other processes
will use the next two ports (e.g., 1100 and 1101).
Chapter 8: Installing the Live Collaboration Server
175
18. Setup now has enough information to begin copying the program files.
19. Setup displays the status of the installation while it is in progress.
176
ENOVIA Live Collaboration Installation Guide
20. When Setup is finished installing the software, it displays the following message.
21. Continue with next step in General Installation for ENOVIA Live Collaboration
Server.
Be sure to place a working bootstrap file in the location specified in step 11 on page 169.
To install the Live Collaboration Server on UNIX/Linux in console mode
1. Copy the <media_name>.tar.gz file, where <media_name> is the name of the media
for your platform (for example, ENOVIALiveCollaborationServer-V6R2011x.RHEL64), from the CD or ENOVIA Download page to the distribution directory.
2. Mount the CD-ROM drive. Refer to Mounting the CD in Chapter 7 if necessary.
3. Untar the <media_name>.tar.gz file to a temporary directory. Change to the
<media_name>/1/ subdirectory, and then run the Setup script in console mode as
follows:
% cd /<media_name>/1
% ./StartTUI.sh
The ENOVIA Live Collaboration Server console-based Setup program starts.
4. The Setup program displays the default installation directory.
*****V6R2011x ENOVIA Live Collaboration Server Choose
Destination Location*****
Setup will install V6R2011x ENOVIA Live Collaboration
Server in the following directory:
Default []: /qausr/Enovia_V6R2011x/Server
If you want to change the location, type in the new installation directory path.
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
Press Enter to continue.
Chapter 8: Installing the Live Collaboration Server
177
5. Setup then asks you to select the components you want to install in the specified
directory, in this case tthe component is CSR - ENOVIA Live Collaboration Server.
*****V6R2011x ENOVIA Live Collaboration Server Select
Software*****
Click to select the components you want to install in directory
/qausr/Enovia_V6R2011x/Server.
You can choose not to install V6R2011x ENOVIA Live Collaboration
Server by clicking Cancel to exit setup.
Space available: 26268940 Kb
Space required: 158057 Kb
-2 End selection
-1 [X] All
CSR - ENOVIA Live Collaboration Server
Enter selection (default: Next) :
If you want to cancel the installation, type 2 . Press Enter to continue.
6. Setup then asks you to enter the Java Home path. The is the location of your Java
Development Kit (JDK).
*****V6R2011x ENOVIA Live Collaboration Server Select Java
Home*****
Please enter Java Home path
Default [/usr/java]: /usr/jdk/jdk1.6.0_19
You can use the JDK installed by the Application Server or a higher version, if your
custom Java programs require it. There cannot be any spaces in the directory name or
the install will fail, as this will cause problems during deployment.
The JDK you specify is used to configure Java for applications deployed by your
Application Server (except the WebSphere Application Server) and non-Application
Server based applications. If you are using WebSphere, please see JDK notes before
specifying your JDK.
If using RIP mode, enter the path to Java used by the Application Server.
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
Change the Java Home path, if desired. Press Enter to continue.
7. Setup then asks you to choose a database type. Only those database types that are
supported on your particular platform are displayed. Depending on the OS, the
available database options could be any of the following:
•
Oracle, DB2, and MySQL
•
Oracle and DB2
•
Oracle only
For example:
*****V6R2011x ENOVIA Live Collaboration Server Database
selection*****
Choose the database type:
178
ENOVIA Live Collaboration Installation Guide
-2 End selection
1 (*) Oracle
Enter selection (default Next):
If your platform supports multiple types of databases, Oracle is the default.
Select the desired database type. Press Enter.
8. If you selected Oracle, Setup then asks for the location of the TNS_ADMIN directory,
which contains the tnsnames.ora file. This file contains the client-side network
configuration parameters required for Oracle. You can copy a tnsnames file from the
Oracle server and put it in the location specified here after the installation completes.
*****V6R2011x ENOVIA Live Collaboration Server Oracle Server
Connection Parameters*****
TNS_ADMIN directory
Default [/home/data/ora11g/network/admin]: /app/oracle/product/
11.2.0/network/admin
Setup cannot detect the correct Oracle path on UNIX. Incorrect Oracle path selection may
abort the installation without a message indicating the reason for the failure.
Change the TNS_ADMIN directory, if desired. Press Enter to continue.
9. Setup then asks you to read and accept the terms in the Oracle Instant Client License
agreement.
*****V6R2011x ENOVIA Live Collaboration Server Oracle Instant
Client License*****
Be sure to carefully read and understand all the rights and
restrictions described
in the license terms. You must accept the license terms before
you can install the
software
1 [ ]
2 [ ]
Enter
end):
1 [X]
2 [ ]
I have read and accept the license terms
I do not accept the license terms
your choice 1 or 2( if you choose 2, the installer will
1
I have read and accept the license terms
I do not accept the license terms
Type 1 (the default) or simply press Enter to accept the license terms and continue
installation.
10. If you selected a different database type, Setup displays a different set of questions:
•
For DB2, respond to these prompts:
Enter the DB2 product directory [ ]?
Enter the DB2 Instance Name [db2inst1]?
You must enter the directory where DB2 is installed and the name of your DB2
instance. (The default instance name on UNIX is db2inst1, which you can
change.)
•
For MySQL, enter the directory where the ODBC files reside:
Enter the directory where the ODBC initialization
files reside [ ]?
Chapter 8: Installing the Live Collaboration Server
179
11. Setup then asks you to enter the directory of your connection file (MATRIX-R file).
This file contains the information necessary for the server to locate and open the
Platform root database. This should be set to the server’s installation directory.
*****V6R2011x ENOVIA Live Collaboration Server Choose MatrixHome
Location*****
Please enter the directory of your connection file (MATRIX-R
file).
Default [/qausr/Enovia_V6R2011x/Server]: /qausr/Enovia_V6R2011x
If you want to choose a different location than the default, type in the path. Press
Enter. Setup checks for the existence of the MATRIX-R file in the specified
directory.
If the file exists in the specified directory, you receive a confirmation message:
Matrix bootstrap exists.
If the bootstrap does not exist in the specified directory, you instead get a warning:
Stdout of child process:
Info: bootstrap does not exist
Stderr of child process:
Exit process with return code: 1
-------------------------------------Warning
Matrix bootstrap does not exist.
Please copy a valid bootstrap to /qausr/Enovia_V6R2011x.
Error stack:
Error code: Owner: 30a
Actions:
[1] OK
-------------------------------------Please choose an action: 1
Installation can continue, but the Live Collaboration Server will not operate without a
valid connection file.
12. Setup then asks you to select a deployment option:
*****V6R2011x ENOVIA Live Collaboration Server Select Deployment
Option*****
Please select deployment option
Click Next to continue the installation.
-2 End selection
1 (*) J2EE (build EAR and WAR archives)
2 ( ) None (Collaboration Kernel only)
Enter selection (default Next):
Type 1 (the default), or simply press Enter, for all supported J2EE Application
Servers. If you intend to install Advanced Search on a dedicated machine, this option
is required. See also Running the WAR Utility on UNIX or Linux in Chapter 10.
180
ENOVIA Live Collaboration Installation Guide
Select 2 if you will only use custom Studio Customization Toolkit applets or
applications that do not use the servlets. In this case an Application Server is not
required, but you must configure the Live Collaboration Server for RIP mode.
13. Setup then asks you to select a Java heap size.
*****V6R2011x ENOVIA Live Collaboration Server Java Heap
Size*****
Please select Java heap size.
This setting affects the options for Java memory allocation.
Click Next to continue the installation.
-2 End selection
1 ( ) Small - Java heap
2 (*) Medium - Java heap
3 ( ) Large - Java heap
Enter selection (default
size 256m
size 640m
size 1024m
Next):
Select a Java heap size based on what your system will support.
Java Heap Size
For 32-Bit Systems
For 64-Bit Systems
Small:
256m
256m
Medium:
640m
960m
1024m
2048m
Large:
Software version V6R2011x supports only the 64-bit version of Live Collaboration Server
on both Windows and UNIX. The 32-bit version of Live Collaboration Server for Windows
is supported only for non-production use.
14. Setup then asks you to select a type of character encoding.
*****V6R2011x ENOVIA Live Collaboration Server Select Character
Encoding*****
Please select server character encoding.
Check UTF8 if this server needs to support multiple non-English
languages.
If selecting UTF8, please ensure that your database character
set is also UTF8.
See the Installation Guide for more details.
Click Next to continue.
-2 End selection
1 (*) UTF8
2 ( ) Not UTF8
Enter selection (default Next):
The options are:
•
UTF8—Type 1 (the default) if the server needs to support multiple non-English
languages. In this case, ensure that your database character set is also UTF8.
•
Not UTF8—Type 2 if the server does not need to support multiple non-English
languages.
Press Enter to continue.
15. Setup then asks you for the location of your Application Server’s startup script.
Chapter 8: Installing the Live Collaboration Server
181
*****V6R2011x ENOVIA Live Collaboration Server Application
Server Path*****
Where is the Application Server installed (location of start up
script)?
Must be a valid directory
Default [./]: /app/apache-tomcat-6.0.26/bin
The following are some examples of Application Server startup script locations:
Application Server
Location of Startup Script
WebLogic:
WebSphere:
/app/weblogic/user_projects/
domains/base_domain
/app/WebSphere/AppServer/bin
Sun Java System Application Server:
/app/SUNWappserver7/bin
Tomcat:
/app/tomcat/bin
16. Setup then asks you to end the name of the Application Server startup script.
The following are some examples of Application Server startup script names:
Application Server
Startup Script Name
WebLogic:
startWebLogic.sh
WebSphere:
startServer.sh
Sun Java System Application Server:
asadmin
Tomcat:
startup.sh
•
If you press Enter without entering any script name (the default), Setup will take
this to mean that you are not configuring the Application Server.
•
If you do enter a script name, Setup invokes it to start the Application Server
process and verify that the path and script name are valid.
Default []: startup.sh
Start Process:
"/usr/jdk/jdk1.6.0_19/bin/java -cp ./inst/solaris_a64/install/
installerutil/installerUtil.jar installer.util.check.FileCheck
/app/apache-tomcat-6.0.26/bin startup.sh"
Arguments:
"/usr/jdk/jdk1.6.0_19/bin/java"
"-cp"
"./inst/solaris_a64/install/installerutil/installerUtil.jar"
"installer.util.check.FileCheck"
"/app/apache-tomcat-6.0.26/bin"
"startup.sh"
End of arguments
Waiting for pid 25619
Stdout of child process:
Stderr of child process:
Exit process with return code: 0
17. Setup then asks if you want to install the kernal in RIP mode (see RIP: RMI
In-process).
182
ENOVIA Live Collaboration Installation Guide
*****V6R2011x ENOVIA Live Collaboration Server Matrix RMI In
Process (RIP)*****
Do you want to install the kernel in RIP mode?
Install RIP mode to run the kernel in the same process space as
the application server.
Select No to setup the standard RMI.
Once you have made your selection, click to continue the
installation.
-2 End selection
1 (*) Yes (RIP mode)
2 ( ) No (RMID mode)
Enter selection (default Next):
Moving logs from "/tmp/InstallData/log/CODE/solaris_a64/
ENOVIA_CSR.media-2010_08_12-111607/" to "/qausr/
Enovia_V6R2011x/Server/InstallData/log/CODE/solaris_a64/
ENOVIA_CSR.media-2010_08_12-111607/"
•
If you want to install the kernel in RIP mode, type 1 for Yes (RIP mode). In this
mode, the kernel runs in the same process space as the Application Server. This is
the default and the recommended configuration. See RIP: RMI In-process for
details.
•
If you want to set up the standard RMI mode, type 2 for No (RMID mode). See
RMI Gateway for details.
a ) If you select no to RIP mode, Setup then asks if you will use the RMI
Gateway, or multiple RMI servers.
b1 ) If you select yes (Multiple RMI servers), Setup asks how many additional
server processes will be used. The default (and minimum allowed) is 2.
c1 ) Enter the number of additional server processes you want to use for the RMI
Gateway.
b2 ) If you select no (Single RMI Server), or RMI Gateway, you must specify the
RMI port number.
If you are configuring the Gateway, Setup will assign sequential port
numbers to each secondary server process used. For example, if you
accepted the default of 2 for additional RMI processes, the RMI port number
entered here (such as 1099) will be for the Gateway, and the other processes
will use the next 2 ports (that is, 1100 and 1101).
c2 ) Enter the RMI port number, then press Enter.
18. Setup now has enough information to start copying the program files. If you want to
change any settings, type the letter 'b' (for Back) and press Enter, then make the
desired corrections. When you are satisfied with the displayed settings, press Enter to
start the installation.
*****V6R2011x ENOVIA Live Collaboration Server Start Copying
Files*****
Setup has enough information to start copying the program files.
If you want to review or change any settings, click Back.
If you are satisfied with the settings, click Install to begin
copying files.
Chapter 8: Installing the Live Collaboration Server
183
Files will be installed in the following directory: /qausr/
Enovia_V6R2011x/Server
Selected products: All
DSYInsControler.JavaPath.Resume(/usr/jdk/jdk1.6.0_19)
Database type: Oracle
TNS_ADMIN directory: /app/oracle/product/11.2.0/network/admin
MatrixHome Location: /qausr/Enovia_V6R2011x/Server
Deployment option: J2EE (build EAR and WAR archives)
Java heap size: Medium - Java heap size 640m
Character encoding: UTF8
Application Server Path: /app/apache-tomcat-6.0.26/bin
Startup Script: startup.sh
Kernel in RIP mode: Yes (RIP mode)
Enter your choice (default Install):
CODE/solaris_a64/InsServerOnly (960 b)
..............................
CODE/solaris_a64/InsOracleClient_PRFX-Common (147 Mb)
..............................
CODE/solaris_a64/ENODataBaseAbstract (14 Kb)
..............................
.
.
.
Setup displays the status of the installation while it is in progress.
19. Setup informs you when the Live Collaboration Server installation is finished.
*****V6R2011x ENOVIA Live Collaboration Server Setup
Complete*****
Setup has finished installing V6R2011x ENOVIA Live Collaboration
Server on your computer.
CSR - ENOVIA Live Collaboration Server: installed.
-2 End selection
Enter selection (default: Next) :
Press Enter to exit Setup and close the console window.
Be sure to place a working bootstrap file in the location specified in step 11 on page 180.
To install the Live Collaboration Server on UNIX/Linux in silent mode
Silent mode requires completion of the Live Collaboration Server installation in one of the
other two modes (graphical or console). After installation, the files needed for silent mode
are created under SERVERHOME/InstallData/. In this directory, there is a file called
UserIntentions.xml.
If you want to allow the installer to run on a non-empty directory, you must manually
modify the TARGET_PATH variable in the UserIntentions.xml and InstallData.xml files,
both of which are located in the InstallData subdirectory of the SERVERHOME directory.
1. Open a console window.
184
ENOVIA Live Collaboration Installation Guide
2. Change to the <media_name>/1/ subdirectory, and then run the Setup program in
silent mode as follows:
% cd /<media_name>/1
% ./StartTUI.bat --silent <full_path>/UserIntentions.xml
where <full_path> is the path to the InstallData/ subdirectory under the
SERVERHOME directory.
Chapter 8: Installing the Live Collaboration Server
185
Installing ENOVIA Live Collaboration Server on
Windows
Before installing the Live Collaboration Server on Windows you must:
•
Remove any old versions of the ENOVIA Live Collaboration Servers.
•
Install a qualified Application Server (or other Web server, if you will not be using the
servlets or will only be setting up Web Navigator) and ensure that it is operational.
•
Make sure you know:
•
The path where the Application server is installed and the name of the startup
script
•
The path for the HTTP server’s document root directory
•
The path for the JDK
The ENOVIA Live Collaboration Server Setup program can be run in one of three
modes—graphical, console, or silent:
•
To install the Live Collaboration Server on Windows in graphical mode, see page 186.
•
To install the Live Collaboration Server on Windows in console mode, see page 196.
•
To install the Live Collaboration Server on Windows in silent mode, see page 205.
To install the Live Collaboration Server on Windows in graphical mode
Live Collaboration Server installation on Windows may optionally be executed multiple
times when more than one database will be accessed via one WebLogic server. The MQL
executable is installed together with the Live Collaboration Server on Windows.
1. Log into Windows as a user with Administrator privileges.
2. Copy the <media_name>.zip file, where <media_name> is the name of the media for
your platform (for example, ENOVIALiveCollaborationServer-V6R2011x.Windows64), from the CD or ENOVIA Download page to a
temporary directory.
Please note that when transferring .zip files from the internet, executable files may
silently be excluded when unzipping due to Windows security behaviour. To prevent
this from happening, before unzipping the file, right click in the file, select
Properties, then click Unblock.
3. Unzip the <media_name>.zip file to a temporary directory. Change to the
ENOVIA_CSR.media\1\ subdirectory, and then run the Setup program in graphical
mode as follows:
> cd \ENOVIA_CSR.media\1
> setupV6
The ENOVIA Live Collaboration Studio graphical Setup program starts.
186
ENOVIA Live Collaboration Installation Guide
4. Setup displays the directory where the ENOVIA Live Collaboration Server software
will be installed. The default is C:\enoviaV6R2011x\server. If you want to
choose a different location, click Browse and navigate to the desired directory or type
in the path. Click Next.
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
5. Setup then asks you to select the components you want to install in the specified
directory. CSR - ENOVIA Live Collaboration Server is selected by default. If you
want to cancel the installation at this point, click Cancel. Otherwise, click Next.
6. Enter (or Browse to) the location of your Java Home path.
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
Chapter 8: Installing the Live Collaboration Server
187
Click Next.
7. Setup then asks you to choose the database type:
•
Select Oracle if you want to be connected to an Oracle database. This selection
installs the Oracle Instant Client 10g, which is distributed with the Platform
software. This means that the Oracle client software no longer needs to be
installed separately.
•
Select Others if you want to be connected to any other type of database. If your
platform supports multiple types of databases, Oracle is the default.
Select the desired database type. Click Next.
188
ENOVIA Live Collaboration Installation Guide
8. If you select Oracle, enter the location of the TNS_ADMIN directory. This is the
directory where your tnsnames.ora file is located. The default is
c:\oracle\product\10g\NETWORK\ADMIN. To install to a different location,
click Browse and select another directory, or type it in. Click Next.
9. Setup then asks you to read and accept the terms in the Oracle Instant Client License
agreement. Read the agreement and select the I have read and accept the license
terms radio button. Click Next.
Chapter 8: Installing the Live Collaboration Server
189
10. Setup then asks you to enter the directory of your connection file (MATRIX-R file).
The default is C:\enoviaV6R2011x\server. If you want to choose a different
location, click Browse and navigate to the desired directory or type in the path. Click
Next.
11. Setup then asks you to select one of the following deployment options. Select one of
these options based on the Application Server you are using:
•
J2EE (build EAR and WAR archives)—Select this option to use any of the
supported Application Servers. If you intend to install advanced search on a
dedicated machine, this option is required. See also Running the WAR utility on
Windows in Chapter 10.
•
None (Collaboration Kernel only)—Select this option if you will use only
custom Studio Customization Toolkit applications that do not use the Servlets. In
this case, an Application Server is not required.
Click Next.
12. Setup then asks you to select a Java heap size. This setting affects the options for Java
memory allocation.
190
ENOVIA Live Collaboration Installation Guide
Select a Java heap size based on what your system will support.
Java Heap Size
For 32-Bit Systems
For 64-Bit Systems
Small:
256m
256m
Medium:
640m
960m
1024m
2048m
Large:
Software version V6R2011x supports only the 64-bit version of Live Collaboration Server
on both Windows and UNIX. The 32-bit version of Live Collaboration Server for Windows
is supported only for non-production use.
Chapter 8: Installing the Live Collaboration Server
191
13. Setup then asks you to select the server character encoding. Choose one of the
following options:
•
UTF8—Select this option if the server needs to support multiple non-English
languages. In this case, ensure that your database character set is also UTF8.
•
Not UTF8—Select this option if the server does not need to support multiple
non-English languages.
Click Next.
14. Setup then asks whether you want to install the kernel in RIP mode.
•
192
If you want to install the kernel in RIP mode, select Yes (RIP mode). In this
mode, the kernel runs in the same process space as the Application Server. This is
the default and the recommended configuration. See RIP: RMI In-process for
details. Click Next.
ENOVIA Live Collaboration Installation Guide
•
If you want to set up the standard RMI mode, select No (RMID mode). See RMI
Gateway for details.
a ) If you select no to RIP mode, Setup then asks if you will use the RMI
Gateway, or multiple RMI servers.
Chapter 8: Installing the Live Collaboration Server
193
b1 ) If you select yes (Multiple RMI servers), Setup then asks how many
additional server processes will be used. The default (and minimum allowed)
is 2.
c1 ) Enter the number of additional server processes you want to use for the RMI
Gateway, then click Next.
b2 ) If you select no (Single RMI Server), or RMI Gateway, you must specify the
RMI port number.
If you are configuring the Gateway, Setup will assign sequential port
numbers to each secondary server process used. For example, if you
accepted the default of 2 for additional RMI processes, the RMI port number
entered here (such as 1099) will be for the Gateway, and the other processes
will use the next 2 ports (that is, 1100 and 1101).
c2 ) Enter the RMI port number, then click Next.
194
ENOVIA Live Collaboration Installation Guide
15. Setup now has enough information to start copying the program files. It asks you to
review all the settings you have made, and gives you the opportunity to make changes
by selecting Back and re-entering the information. Once you have approved all the
settings, click Next to complete the setup and install the Live Collaboration Server.
Setup displays the status of the installation while it is in progress.
Chapter 8: Installing the Live Collaboration Server
195
16. Once the installation is complete, Setup informs you that the "CSR - ENOVIA Live
Collaboration Server" has been successfully installed. Click End to close the setup
dialog.
Setup also creates program shortcuts under the "Dassault Systemes Software
V6R2011x" program folder on the Start menu.
17. Reboot your Windows system.
18. Continue with next step in General Installation for ENOVIA Live Collaboration
Server.
Be sure to place a working bootstrap file in the location specified in step 10 on page 190.
To install the Live Collaboration Server on Windows in console mode
Live Collaboration Server installation on Windows may optionally be executed multiple
times when more than one database will be accessed via one WebLogic server. The MQL
executable is installed together with the Live Collaboration Server on Windows.
1. Log into Windows as a user with Administrator privileges.
2. Copy the <media_name>.zip file, where <media_name> is the name of the media for
your platform (for example, ENOVIALiveCollaborationServer-V6R2011x.Windows64), from the CD or ENOVIA Download page to a temporary directory.
196
ENOVIA Live Collaboration Installation Guide
Please note that when transferring .zip files from the internet, executable files may
silently be excluded when unzipping due to Windows security behaviour. To prevent
this from happening, before unzipping the file, right click in the file, select
Properties, then click Unblock.
3. Unzip the <media_name>.zip file to a temporary directory. Change to the
ENOVIA_CSR.media\1\ subdirectory, and then run the Setup script in console
mode as follows:
> cd \ENOVIA_CSR.media\1
> StartTUI.bat
The ENOVIA Live Collaboration Server text-based Setup program starts.
In the console window, Setup first displays the directory where the ENOVIA Live
Collaboration Server software will be installed. The default is
C:\enoviaV6R2011x\server.
Setup does not check for the existence of a previous version. The software must be
installed to a new location, and the installation directory may not include any spaces.
The installation directory must also be different from the distribution directory.
4. Specify the installation directory and then press Enter, or simply press Enter to
accept the default.
Chapter 8: Installing the Live Collaboration Server
197
Setup then asks you to select the components you want to install in the specified
directory. CSR - ENOVIA Live Collaboration Server is the only available option.
5. Select one of the following options:
•
Type 2 if you want to end your selection, then press Enter.
•
Type 1 or simply press Enter to select CSR - ENOVIA Live Collaboration
Server.
Setup then asks you to enter the Java Home path.
Incorrect Java home path selection may abort the installation without a message
indicating the reason for the failure. Failing to provide a 64-bit JDK for a 64-bit install
will also cause the installation to abort.
6. Change the location, if desired, or press Enter to accept the default path. Press Enter
to continue.
198
ENOVIA Live Collaboration Installation Guide
Setup then asks you to choose the database type.
7. Select one of the following options:
•
Type 1 or simply press Enter to select Oracle (the default). This option installs
Oracle Instant Client 10g, which is distributed with the Live Collaboration Server
software. The Oracle client software does not need to be installed separately.
•
Type 2 to select Others, then press Enter. If you select this option, Setup displays
a different set of questions:
•
For DB2, you are asked to enter the DB2 product directory and the DB2
Instance Name.
•
For MSQL, you are asked to enter the directory where the ODBC
initialization files reside.
If you selected Oracle, Setup then asks you to enter the TNS_ADMIN directory. This
is the directory where your tnsnames.ora file is located. The default is
c:\oracle\product\10g\NETWORK\ADMIN\.
8. Change the TNS_ADMIN directory, if desired, or press Enter to accept the default.
Chapter 8: Installing the Live Collaboration Server
199
Setup then asks you to read and accept the terms in the Oracle Instant Client License
agreement.
9. Read the Oracle Instant Client License agreement, then select one of these options:
•
Type 1 to confirm that you have read and accept the license terms.
•
Type 2 if you do not accept the license terms. If you choose this option, Setup
will end.
Press Enter to continue.
Setup then asks you to enter the directory of your connection file (MATRIX-R file).
The default is C:\enoviaV6R2011x\server. If you want to choose a different
location, type in the path. Click Next.
10. Change the location, if desired, or simply press Enter to accept the default.
If a Matrix bootstrap file does not exist in the specified directory, Setup displays a
warning message instructing you to copy a valid bootstrap file to that location. You
must type 1 and then press Enter to continue.
200
ENOVIA Live Collaboration Installation Guide
Setup then asks you to select a deployment option.
11. Select one of the following options based on the Application Server you are using:
•
J2EE (build EAR and WAR archives)—Type 1 or simply press Enter to use any
of the supported Application Servers. If you intend to install Advanced Search on
a dedicated machine, this option is required. See also Running the WAR utility on
Windows in Chapter 10.
•
None (Collaboration Kernel only)—Type 2 if you will use only custom Studio
Customization Toolkit applications that do not use the Servlets. In this case, an
Application Server is not required. Press Enter.
Setup then asks you to select a Java heap size. This setting affects the options for Java
memory allocation.
12. Select a Java heap size based on what your system will support:
Java Heap Size
For 32-Bit Systems
For 64-Bit Systems
Small:
256m
256m
Medium:
640m
960m
1024m
2048m
Large:
Chapter 8: Installing the Live Collaboration Server
201
•
Type 1 for a Small Java heap size. Then press Enter.
•
Type 2 or simply press Enter for a Medium Java heap size (the default).
•
Type 3 for a Large Java heap size. Then press Enter.
Software version V6R2011x supports only the 64-bit version of Live Collaboration Server
on both Windows and UNIX. The 32-bit version of Live Collaboration Server for Windows
is supported only for non-production use.
Setup then asks you to choose the server character encoding.
13. Select one of the following options:
•
UTF8—Type 1 or simply press Enter to select this option if the server needs to
support multiple non-English languages (the default). In this case, ensure that
your database character set is also UTF8.
•
Not UTF8—Type 2 to select this option if the server does not need to support
multiple non-English languages. Then press Enter.
Setup then asks whether you want to install the kernel in RIP mode.
14. Select one of the following options:
202
ENOVIA Live Collaboration Installation Guide
•
RIP mode—Type 1 or simply press Enter if you want to install the kernel in RIP
mode (the default). In this mode, the kernel runs in the same process space as the
Application Server. This is the recommended configuration. See RIP: RMI
In-process for details.
•
RMID mode—Type 2 if you want to set up the standard RMI mode. Then press
Enter. See RMI Gateway for details.
a ) If you select no to RIP mode, Setup then asks if you will use the RMI Gateway,
or multiple RMI servers.
b1 )If you select yes (Multiple RMI servers), Setup then asks how many additional
server processes will be used. The default (and minimum allowed) is 2.
c1 )Enter the number of additional server processes you want to use for the RMI
Gateway. Then press Enter.
b2 )If you select no (Single RMI Server), or RMI Gateway, you must specify the
RMI port number.
If you are configuring the Gateway, Setup will assign sequential port numbers to
each secondary server process used. For example, if you accepted the default of 2
for additional RMI processes, the RMI port number entered here (such as 1099)
will be for the Gateway, and the other processes will use the next 2 ports (that is,
1100 and 1101).
c2 )Enter the RMI port number. Then press Enter.
Setup now has enough information to start copying the program files. It asks you to
review all the settings you have made, and gives you the opportunity to make changes.
15. Review the settings, then press Enter to complete the setup and install the Live
Collaboration Server.
Chapter 8: Installing the Live Collaboration Server
203
Setup displays the status of the installation while it is in progress.
Setup informs you when the ENOVIA Live Collaboration Server installation is
finished.
16. Press Enter to end Setup and close the console window.
17. Reboot your Windows system.
18. Continue with next step in General Installation for ENOVIA Live Collaboration
Server.
Be sure to place a working bootstrap file in the location specified in step 10 on page 200.
204
ENOVIA Live Collaboration Installation Guide
To install the Live Collaboration Server on Windows in silent mode
Live Collaboration Server installation on Windows may optionally be executed multiple
times when more than one database will be accessed via one WebLogic server. The MQL
executable is installed together with the Live Collaboration Server on Windows.
Silent mode requires completion of the Live Collaboration Server installation in one of the
other two modes (graphical or console). After installation, the files needed for silent mode
are created under SERVER_INSTALL\InstallData\. In this directory, there is a file
called UserIntentions.xml.
If you want to allow the installer to run on a non-empty directory, you must manually
modify the TARGET_PATH variable in the UserIntentions.xml and InstallData.xml files,
both of which are located in the InstallData subdirectory of the Live Collaboration Server
installation.
1. Log into Windows as a user with Administrator privileges.
2. Change to the ENOVIA_CSR.media\1\ subdirectory, and then run the Setup script
in silent mode as follows:
> cd \ENOVIA_CSR.media\1
> StartTUI.bat --silent <full_path>\UserIntentions.xml
where <full_path> is the path to the InstallData\ subdirectory under the
SERVER_INSTALL directory.
Chapter 8: Installing the Live Collaboration Server
205
Installing a Live Collaboration Server Service
Pack
Service pack installation installs only the Live Collaboration server components, without
modifying startup scripts and property files. Service pack installation does not make any
UTF-8 changes to files in your environment. It is recommended that you check your
UTF-8 settings, as described in UTF-8 Settings.
Prerequisite: Prior successful installation of a Live Collaboration Server major release.
Service pack installation is intended only for upgrading from a major release to a
maintenance release. For example, from V6R2011x to V6R2011x.HF1, but not from a
pre-V6R2011x release or any release to V6R2011x. If you are performing a new
installation of ENOVIA Live Collaboration Server or upgrading from a prior major
release, follow the instructions for full installation (Installing ENOVIA Live Collaboration
Server on UNIX/Linux or Installing ENOVIA Live Collaboration Server on Windows).
To install a service pack in graphical mode
1. Run the Setup program in graphical mode:
•
UNIX: ./StartGUI.sh
•
Windows: setupV6.exe
2. Setup prompts for the installation directory.
UNIX:
The installation directory must be the location of your existing ENOVIA Live
Collaboration Server installation.
206
ENOVIA Live Collaboration Installation Guide
Windows:
Click Next to continue.
3. Setup has enough information to begin copying the program files.
Unix:
Chapter 8: Installing the Live Collaboration Server
207
Windows:
Click Install.
4. Setup informs you when the service pack installation is finished.
Unix:
208
ENOVIA Live Collaboration Installation Guide
Windows:
Click Close or press Enter to exit Setup.
5. After the installation completes, you must run the WAR Utility and then deploy the
archive file, as described in Chapter 10, Deploying J2EE.
To install a service pack in console mode
1. Run the Setup program in console mode:
•
UNIX: ./StartTUI.sh
•
Windows: StartTUI.bat
2. Setup prompts for the installation directory.
Unix:
*****V6R2011x.HF1 ENOVIA Live Collaboration Server Choose
Destination Location*****
Setup will upgrade ENOVIA Live Collaboration Server to
V6R2011x.HF1 in the following directory:
Default []:
/qausr/Enovia_v6R2011x/Server
Windows:
The installation directory must be the location of your existing ENOVIA Live
Collaboration Server installation.
Press Enter to continue.
Chapter 8: Installing the Live Collaboration Server
209
3. Setup now has enough information to start copying the program files. If you want to
change any settings, type the letter 'b' (for Back) and press Enter, then make the
desired corrections. When you are satisfied with the displayed settings, press Enter to
start the installation.
Unix:
*****V6R2011x.HF1 ENOVIA Live Collaboration Server Start Copying
Files*****
Setup has enough information to start copying the program files.
If you want to review or change any settings, click Back.
If you are satisfied with the settings, click Install to begin
copying files.
Files will be installed in the following directory: /qausr/
Enovia_v6R2011x/Server
Enter your choice (default Install):
Windows:
4. Setup informs you when the service pack installation is finished.
Unix:
*****V6R2011x.HF1 ENOVIA Live Collaboration Server Setup
Complete*****
Setup has finished installing V6R2011x.HF1 ENOVIA Live
Collaboration Server on your computer.
CSR - ENOVIA Live Collaboration Server: installed.
-2 End selection
Enter selection (default: Next) :
210
ENOVIA Live Collaboration Installation Guide
Windows:
5. Press Enter to exit Setup.
6. After the installation completes, you must run the WAR Utility and then deploy the
archive file, as described in Chapter 10, Deploying J2EE.
Chapter 8: Installing the Live Collaboration Server
211
Configuring the ENOVIA Live Collaboration
Server
The ENOVIA Live Collaboration Server may be configured in several ways:
•
Using RIP mode, which is the default and recommended configuration.
•
As a single process server.
•
As an RMI Gateway
•
Installing Multiple ENOVIA Live Collaboration Servers (RIP only) to point to
different databases.
•
As a File Collaboration Server
The default installation handles RIP mode. Optionally, the installation program may
configure the single process server or the RMI Gateway with its default configuration. For
installation procedures, refer to the Preparing to Install the ENOVIA Live Collaboration
Server. The sections that follow provide information on re-configuring the Live
Collaboration Server.
When the Live Collaboration Server is installed, a server configuration audit tool is run to
evaluate system and java resources and settings. These configuration settings can be
crucial to a successful deployment and are discussed in Server Startup Configuration
Checker in Chapter 20.
Reconfiguring the
ENOVIA Live
Collaboration
Server Windows
Service
By default, the ENOVIA Live Collaboration Server is configured in RIP mode, and
therefore does not need to be configured as a service (it is available to the Application
Server whenever it needs to be). On Windows, when the standalone or RMI gateway
ENOVIA Live Collaboration Server is installed, it is installed as a Service, called
RMIService.exe, which is configured during installation with the following command line
arguments:
Arguments
Description
-inidir INIDIR
INIDIR is the directory that holds the enovia.ini (previously ematrix.ini) file for
the Live Collaboration Server. For example:
RMIService.exe -config "ENOVIA Live Collaboration
Server" -inidir
c:\enoviaV6R2011x\server\intel_a\code\bin
-javahome JDKDIR
JDKDIR is the directory that holds the installed Java Development Kit.
-matrixhome BOOTFILEPATH
BOOTFILEPATH represents the bootstrap location for this server or gateway. The
entry in the enovia.ini file takes precedence over this specification, so you should
remove it from there if you will use a different location.
-matrixinstall INSTALLDIR
INSTALLDIR represents the location where the ENOVIA Live Collaboration
Server was installed.
-bootfile BOOTFILENAME
Name of the connection file. Defaults to MATRIX-R.
212
ENOVIA Live Collaboration Installation Guide
Arguments
Description
-bosroot
The root location for the Live Collaboration kernel.
-logdir
The location of the Matrix log files.
-port PORT
PORT is the RMI port number for this instance. Could be RMI Single server or
Gateway port. Default is 1099.
-minheap
The minimum heap size (in megabytes) passed to the Java Virtual Machine.
-maxheap
The maximum heap size (in megabytes) passed to the Java Virtual Machine.
-javaoptions
Used to specify any of the standard Java options settings that will be sent to the
Java virtual machine, such as minheap, maxheap, Java stack size, etc. For
example, the following sets the stack size to 256k:
rmiservice -config "eMatrix RMI Server" -javaoptions
"-C-Xss256k"
-servers SERVERS
Used only if the RMI Gateway is configured. SERVERS is a list of secondary
server hosts, including port numbers, separated by commas, but no spaces. For
example:
-servers //HOST:1100,//HOST:1101,//HOST:1102
By default, HOST is always localhost. HOST can be the same or different
machine names for each server process.
-flashdir
Used to specify the location for flash cache files or more specifically, to set the
MX_FLASH_CACHE variable for the server. For gateway configurations (where
-servers has been specified), -flashdir may be configured with comma separated
directories to be used as flash cache directory for each respective server. The
number of flash directories specified should match the number of servers, but if
less flash directories are specified than servers, the last flash directory specified
will be used for all remaining servers.
-setenv
Used to set or delete environment variables in the format: -setenv
variable=[string]. In cases where there are multiple RMI services with different
environment variable settings, you should delete the environment variable setting
from enovia.ini, which takes precedence, and create the environment variable
settings on the RMI service level. There can be several -setenv parameters on a
command line that modify several environment variables, for example:
rmiservice -config "eMatrix RMI Server" -setenv
MX_MQL_TRACE=TRUE -setenv MX_SQL_TRACE=
The above command will update MX_MQL_TRACE in the registry with a TRUE
value and delete MX_SQL_TRACE.
If you need to configure an environment variable with spaces in its value, you
should enclose the value in double quotes.
Once the server is installed, these parameters are stored in the Windows registry for future
reference by the service when it actually runs.
Chapter 8: Installing the Live Collaboration Server
213
When modifications are required, you may run RMIService.exe from the command line,
setting or resetting arguments. When running from the command line you must set the
“mode” for the command using one of the following flags:
Argument
Description
-install NAME
Used to install a new RMI service with the NAME specified. When run by the setup program,
NAME is ENOVIA RMI Server.
-config NAME
Used to modify the existing named RMI service.
-remove NAME
Used to remove the existing named RMI service. Before executing in this mode, you must stop
the service.
-query NAME
Used to query the current service settings.
-help NAME
Used to print help on the service.
When NAME includes spaces, as is the case with the default, you must enclose it with quotes.
When installing a new service with the -install flag, you must include ALL required
arguments (that is, those in the first table above).
Configuring the Gateway for Quiesce on Windows
The arguments listed below are for use with the RMI Gateway, and are unset upon
installation. These arguments are mutually exclusive—exactly one or none of them may
be set at a time. Setting any of them makes use of the Quiesce function.
Argument
Description
-ops OPS
OPS is the number of operations to perform before switching to another server when the RMI
Gateway is in use.
-hours HOURS
HOURS is the number of hours to wait before switching to another server when the RMI
Gateway is in use.
-days DAYS
DAYS is the number of days to wait before switching to another server when the RMI Gateway
is in use.
-minutes MINUTES
MINUTES is the number of minutes to wait before switching to another server when the RMI
Gateway is in use.
To modify the RMI Service on Windows
1. From the Start menu, choose Run.
2. Enter the command with the required changes in the Open: text box. For example:
RMIService.exe -config "eMatrix RMI Server" -port 7200 -servers
localhost:7201,localhost:7202,localhost:7203 -days 1
214
ENOVIA Live Collaboration Installation Guide
Assigning a port number for the RMID RMI server
The ENOVIA Live Collaboration Server associated with the RMID (in a standalone or
gateway configuration; that is, non-RIP) is typically “exported” on an anonymous
(random) port. This is the port on which the The ENOVIA Live Collaboration Server is
listening for connections. With a firewall in place, you need to be able to specify a port
number for the The ENOVIA Live Collaboration Server (as opposed to the RMID) that is
open on the firewall. You can assign the listening port for an The ENOVIA Live
Collaboration Server to allow the The ENOVIA Live Collaboration Server connections to
traverse a firewall by adding the following argument to the The ENOVIA Live
Collaboration Server command line in the rmireg.sh or rmireg.bat file:
-port <port#>
The port number specified must be a valid port that is not used by another process. Below
are example entries in rmireg.sh, which specify the port numbers for two The ENOVIA
Live Collaboration Servers (RMI gateway configuration):
${JAVA_PATH}/java $JAVA_SECURITY
-Djava.rmi.server.codebase=file:$CODEBASE
-Djava.rmi.activation.port=1100 com.matrixone.jdl.eMatrix //
localhost:1100 -port 2000 &
${JAVA_PATH}/java $JAVA_SECURITY
-Djava.rmi.server.codebase=file:$CODEBASE
-Djava.rmi.activation.port=1101 com.matrixone.jdl.eMatrix //
localhost:1101 -port 3001 &
Reconfiguring the
ENOVIA Live
Collaboration
Server on UNIX
When installed on UNIX, the configuration is set by environment variables. To change the
configuration after the initial installation, modify the rmireg.sh shell script. The following
environment variables may be modified:
Environment Variable
Description
JAVA_PATH JDKDIR
JDKDIR is the directory that holds the installed
Java Development Kit.
MATRIXHOME BOOTFILEPATH
BOOTFILEPATH represents the bootstrap location
for this server or gateway.
Portions of the section of the rmireg.sh script that sets environment variables are shown
below. You can reconfigure the lines that are shown in bold.
# rmireg.sh -- Bourne shell script for eMatrixServletRMI
# Registry
#
# Usage:- rmireg.sh
#
###############################################################
#
# Set up Matrix Environment Variables
#
MATRIXHOME=/acme1/ematrixRMI
export MATRIXHOME
CLASSPATH=/acme1/weblogic/myserver/servletclasses/
eMatrixServletRMI.jar
Chapter 8: Installing the Live Collaboration Server
215
export CLASSPATH
MX_ARCH=solarisb64
export MX_ARCH JAVA_OPTIONS JAVA_PATH JAVA_LIB JAVA_SECURITY
Confifuring the Gateway for Quiesce on UNIX
The variables listed below are for use with the RMI Gateway, and are unset upon
installation. These arguments are mutually exclusive—exactly one or none of them may
be set at a time. Setting any of them makes use of the Quiesce function.
Reconfiguring
ENOVIA Live
Collaboration
Server Port
Numbers
RMI Gateway Variable
Description
OPS #_OF_OPS
The number of operations to perform before switching to
another server when the RMI Gateway is in use.
HOURS #_OF_HOURS
The number of hours to wait before switching to another
server when the RMI Gateway is in use.
DAYS #_OF_DAYS
The number of days to wait before switching to another
server when the RMI Gateway is in use.
If you want to change port numbers, you must change them in a few different places in the
rmireg.sh file. The default setup initiates a log file that uses the port number in the file
name. The easiest way to change the port numbers consistently is to search on the number
itself, knowing which new number will replace the originally configured port. For
example, assume the original installation took the default ENOVIA Live Collaboration
Server port number and installed the Gateway with the default number of server processes.
Now you want to change the ports to use 2000, 2001, and 2002. You could search for 1099
and change all occurrences to 2000, then find 1100 and change all to 2001, and finally all
1101 and change to 2002. Below is a sample portion of the rmireg.sh file that would
require editing to reconfigure the server’s ENOVIA Live Collaboration Server port
number(s):
echo "Starting RMI Daemons"
echo $JAVA_PATH/rmid $JAVA_OPTIONS $JAVA_LIB -J$JAVA_SECURITY
-port 1099 -log /acme1/ematrixRMI/logs/RMI1099 &
$JAVA_PATH/rmid $JAVA_OPTIONS $JAVA_LIB -J$JAVA_SECURITY -port
1099 -log /acme1/ematrixRMI/logs/RMI1099 &
echo $JAVA_PATH/rmid $JAVA_OPTIONS $JAVA_LIB -J$JAVA_SECURITY
-port 1100 -log /acme1/ematrixRMI/logs/RMI1100 &
$JAVA_PATH/rmid $JAVA_OPTIONS $JAVA_LIB -J$JAVA_SECURITY -port
1100 -log /acme1/ematrixRMI/logs/RMI1100 &
echo $JAVA_PATH/rmid $JAVA_OPTIONS $JAVA_LIB -J$JAVA_SECURITY
-port 1101 -log /acme1/ematrixRMI/logs/RMI1101 &
$JAVA_PATH/rmid $JAVA_OPTIONS $JAVA_LIB -J$JAVA_SECURITY -port
1101 -log /acme1/ematrixRMI/logs/RMI1101 &
echo "Starting RMI Gateway"
216
ENOVIA Live Collaboration Installation Guide
$JAVA_PATH/java $JAVA_SECURITY
-Djava.rmi.server.codebase=file:$CLASSPATH
-Djava.rmi.activation.port=1099 com.matrixone.jdl.eMatrix
-servers //localhost:1100,//localhost:1101 //localhost:1099&
echo "Starting Secondary RMI Servers"
$JAVA_PATH/java $JAVA_SECURITY
-Djava.rmi.server.codebase=file:$CLASSPATH
-Djava.rmi.activation.port=1100 com.matrixone.jdl.eMatrix //
localhost:1100 &
$JAVA_PATH/java $JAVA_SECURITY
-Djava.rmi.server.codebase=file:$CLASSPATH
-Djava.rmi.activation.port=1101 com.matrixone.jdl.eMatrix //
localhost:1101 &
Implementing the
Security Wrapper
on RMI Gateway
The security wrapper is a wrapper class for the ENOVIA Live Collaboration Server that
provides the ability to restrict which IP addresses are allowed to connect to the ENOVIA
Live Collaboration Server. The RMI gateway can be configured to allow only trusted hosts
to be connected. A file contains a list of the host IP addresses that are either accepted or
denied.
The new Java classes that implement the security wrapper are built into the
eMatrixServletRMI.jar file, which is part of the Live Collaboration installation.
To enable the security wrapper
1. Create a trusted host list file.The host list file contains a list of the host IP addresses
that are trusted or denied by the RMI gateway. A typical way is to define a list of
trusted host addresses and let all others be denied access.
The host file name and location are user-created, but it is recommended you create the
file in the SERVER_INSTALL\java\properties\ directory. You can create the
file using any ASCII text editor.
Note the following rules:
•
The list contains either trusted or denied host IP addresses, but not both. A list of
trusted hosts will deny access to any host not listed. A list of denied hosts will
allow access to any host not in the denied list.
•
There should be a line break after each line.
•
The # character can be used to indicate a comment.
•
The * character can be used to indicate all trusted hosts, but cannot be used to
indicate denied hosts.
•
For a list of denied IP addresses, the word deny must be in lowercase.
•
Only numerical IP addresses are accepted.
For example, a file containing trusted machines named 10.1.5.60, 10.1.5.61,
and 10.1.5.62 would look like this:
# Trusted hosts
10.1.5.60
10.1.5.61
Chapter 8: Installing the Live Collaboration Server
217
10.1.5.62
Conversely, to deny access from hosts, the file would contain the keyword “deny” and
then list the denied IP addresses. Below is an example where hosts 10.1.5.60 and
10.1.5.61 are denied:
# Deny hosts
deny
10.1.5.60
10.1.5.61
In the example above, any host except 10.1.5.60 and 10.1.5.61 would be
granted access.
Whenever you make a change to the host list file, you must restart the Live Collaboration
Server.
2. Specify the path to the host list file, by adding the system property
com.matrixone.rmi.hostList, which defines the full path to the host list file.
In UNIX, this setting is preferably set in the JAVA_OPTIONS in the rmireg.sh
file. For example, it would look like:
JAVA_OPTIONS="-C-Xss256k -C-Xms256m -C-Xmx256m
-C-Dcom.matrixone.rmi.hostList=/usr/rmi/java/properties/
hosts.txt"
Make sure to change the JAVA_OPTIONS for the appropriate operating system in the
rmireg.sh file.
For Windows, the command would look something like:
C:\>rmiservice -config "eMatrix RMI Server" -JAVAOPTIONS
"-C-Dcom.matrixone.rmi.hostList=c:/rmi/java/properties/
hosts.txt -C-Dfile.encoding=UTF8"
3. Verify the Configuration by inverting the list of trusted hosts to be a list of denied
hosts as follows:
a ) Add the keyword deny in the host list file.
b ) Restart the Live Collaboration Server.
c ) Start Matrix Navigator or the ENOVIA product you use to access the database,
and log into the system.
You should be denied access.
You can also check that any Studio Customization Toolkit clients are not able to
connect
d ) Open the web server log file and search for a RemoteException.
The RemoteException will describe the denied access, for example:
Mon Dec 16 20:08:25 EST 2002:<I> <ServletContext-General>
servlet/login: init
java.rmi.ServerException: RemoteException occurred in server
thread; nested exception is:
java.rmi.RemoteException: Host 10.1.5.39 is not authorized to
connect to the server
218
ENOVIA Live Collaboration Installation Guide
ENOVIA Live Collaboration Server Environment
Settings
When the Live Collaboration Server is installed, the environment is set with the same
variables as needed for other ENOVIA Live Collaboration clients (as discussed in
Configuring ENOVIA Live Collaboration in Chapter 9). In addition, the following are
added for Live Collaboration Server:
MX_NUL_COURTESY_MSG. When a user attempts to use the ENOVIA Live
Collaboration Server without an appropriate product assigned, a CPF product will
automatically be assigned to that user as a courtesy. When this variable is set to true
(by default), a message will also be sent to mxtrace.log indicating that a CPF product
has been assigned to the user as a courtesy.
MX_BOS_ALLOW_SHARED_CONTEXT may be set to TRUE in order to allow
processing of a session that is shared by multiple threads. When this occurs, a
message stating “Session [SESSION ID] in use by multiple threads” is written to the
mxtrace.log file. This message is only a warning and the threads will continue
processing. By default, MX_BOS_ALLOW_SHARED_CONTEXT is set to false,
which means a session cannot be shared by multiple threads. The same message,
“Session [SESSION ID] in use by multiple threads,” is written to the mxtrace.log file
but this time, the second thread using the shared session ID will stop processing. For
an explanation of context object problems, see the “Context Object User Access”
topic in the Creating a Login Page chapter of the Programming Guide.
MX_BOS_ROOT is the same as the WWW document root directory.
MX_BOS_WORKSPACE is the directory below $MX_BOS_ROOT that is created
by the Live Collaboration Server installation. The directory is used as a location for
file access for all logged on users. Subdirectories are created for users as they log into
the server, and automatically removed when they log out. The value is matrix/
workspace.
MX_CONNECTION_POOL_SIZE dictates how many database connections are
pre-initialized. This helps in cases where a multi-threaded Studio Customization
Toolkit application tries to initiate multiple contexts at the same time. Without the
pre-initialized database connections configured, connect failures may occur if the
network or database are slow to respond. The default value is determined by the Java
heap size selected during installation of the Live Collaboration Server (on UNIX that
is small = 10, medium = 20, large = 30).
For more information on this setting, see System Scaling in Chapter 20.
MX_TRACE_FILE_PATH sets the location where the mxtrace.log file is
generated. Defaults to $SERVER_INSTALL\logs.
MX_ABORT_DANGLING_TRANSACTION is set to True. Refer to Optional
Variables for the description of this setting.
On UNIX these settings are added as environment variables in the Live Collaboration
Server startup script.
On Windows, an enovia.ini file for the Live Collaboration Server is created (or updated)
with the settings shown above. A typical Windows enovia.ini file is shown below:
[MATRIX]
MX_BOS_ROOT=C:\enoviaV6R2011x\server\
MX_BOS_WORKSPACE=workspace
Chapter 8: Installing the Live Collaboration Server
219
MX_TRACE_FILE_PATH=C:\enoviaV6R2011x\server\logs
MX_ABORT_DANGLING_TRANSACTION=true
MX_SESSION_TIMEOUT=60
MX_BOS_ALLOW_SHARED_CONTEXT=false
MATRIXHOME=C:\enoviaV6R2011x\server\
MATRIXINSTALL=C:\enoviaV6R2011x\server\
MX_FLASH_PATH=C:\enoviaV6R2011x\server\mxcache
PIXMAPPATH=C:\enoviaV6R2011x\server\intel_a\pixmaps\app\
COLORPATH=C:\enoviaV6R2011x\server\intel_a\code\lib
MATRIXPATH=C:\enoviaV6R2011x\server\intel_a\code\bin
MX_TCL_SHLIB=
TCL_LIBRARY=C:\enoviaV6R2011x\server\intel_a\tcl85\lib\tcl8.5
TK_LIBRARY=C:\enoviaV6R2011x\server\intel_a\tcl85\lib\tk8.5
TMPDIR=C:\DOCUME~1\<user>\LOCALS~1\Temp
MX_DEFAULT_KERNEL=
MX_JVM_DIR=C:\Java\jdk1.6.0_19\jre\bin\client\
MX_JDK_DIR=C:\Java\jdk1.6.0_19\
MX_JAVAC=C:\Java\jdk1.6.0_19\bin\javac.exe
MX_CLASSPATH=C:\Java\jdk1.6.0_19\lib;C:\enoviaV6R2011x\server\
managed\properties;C:\enoviaV6R2011x\server\intel_a\docs\java
common;C:\enoviaV6R2011x\server\intel_a\docs\javaserver;C:\eno
viaV6R2011x\server\intel_a\docs\custom;
MX_CHARSET=UTF8
LANG=C
NLS_LANG=_UTF8
MX_CONNECTION_POOL_SIZE=20
MX_MEMORY_SYSTEM_LIMIT=640m
Refer to Configuring ENOVIA Live Collaboration in Chapter 9 for information on
Matrix-specific variables.
Optional Settings
In addition, the following variables are available:
MX_BOS_BLOCKSIZE sets the size of the data blocks that are transferred between
the server and the client. This setting is in bytes and defaults to 65536 (64k). It can be
adjusted to a maximum of 131072 (128k).
MX_BOS_EXPAND_LIMIT can be set to a positive integer value. When set,
browsers in Indented and Star modes display that number of connections in each
direction at a maximum. The default is to show all connections. The following is
added to the environment by default; however, notice it is commented out:
# MX_BOS_EXPAND_LIMIT=500
Refer to the Programming Guide for use of limits in Studio Customization Toolkit
programs.
MX_BOS_FIND_LIMIT can be set to a positive integer value. When set, find
operations load no more than that number of found objects. Users can override this
number by using the Limit field in the Find dialog box. The default is to load all
objects that meet the search criteria. The following is added to the environment by
default; however, notice that it is commented out:
# MX_BOS_FIND_LIMIT=500
220
ENOVIA Live Collaboration Installation Guide
Refer to the Programming Guide for use of limits in Studio Customization Toolkit
programs.
MX_MAX_THREAD may be set in the enovia.ini file for the Live Collaboration
Server (previously ematrix.ini) only to indicate the maximum number of threads
allowed to run inside the Live Collaboration kernel at one time. Default is 200.
MX_SITE_PREFERENCE can be set to establish the preferred site for file checkin
and checkout in a distributed database that makes use of replicated stores. This
adjustment overrides the setting in the Person or Group definition for the site
preference. This ensures that all Web clients will use the site preference of the Live
Collaboration Server, providing optimum performance.
MX_TRANSACTION_TIMEOUT sets the time interval in seconds after which idle
transactions started through the Live Collaboration Server are subject to being
cleaned up. A transaction is considered “idle” if the Studio Customization Toolkit call
has completed (for example, verbose parameter tracing would show “dispatch
complete”), but the session that originated the Studio Customization Toolkit call is
still holding the Database connection open. This could happen due to improperly
handled transaction boundaries (a “start transaction” without “commit” or “abort”), or
if there is a large amount of work being performed by the session, but outside of the
Live Collaboration kernel (such as JSP code that is performing operations over a large
return set of objects). Note that a JPO is executed in the Live Collaboration kernel, so
a session executing a JPO will not be considered “idle” while the JPO is executing.
This does not mean that the transaction abort and cleanup is performed immediately
when the time expires, but rather means that the transaction becomes subject to being
aborted after that time. The actual transaction abort and cleanup occurs only when a
session accesses the same server as follows:
When any session enters the Live Collaboration kernel, one of the first things it does
is look for transactions idle for more than the MX_TRANSACTION_TIMEOUT
time. If such an idle transaction is detected, then the transaction will be aborted and
the database connection released. So, the cleanup mechanism relies on the fact that
other client sessions are trying to access the Live Collaboration kernel, meaning that
this variable is only useful in multi-server environments such as the Live
Collaboration Server.
If the original session was actually performing a long running operation, when it tries
to access the database connection a “transaction not started” error will be thrown.
A suggested setting is 300 (5 minutes). If not set (or set to 0), no transaction timeout is
in place. This setting is completely independent of existing session timeout methods
available in the xml/http version of the Studio Customization Toolkit.
These settings can be added to the enovia.ini file for both UNIX and Windows:
•
On Windows, this file exists in the SERVER_INSTALL\intel_a\code\bin\
directory, where it is created during installation.
•
On UNIX, typical settings are in the default startup scripts. Optional settings can be
set in one of the following ways:
•
•
UNIX start up shell scripts can be modified to include optional settings as
environment variables (startup scripts call mxEnv.sh).
The settings can be added to the enovia.ini initialization file. This file exists in the
SERVERHOME/<platform>/code/bin/ directory, where it is created during
installation.
If a setting is in both the startup shell script and the .ini file, the value in the shell
script is used.
Chapter 8: Installing the Live Collaboration Server
221
Most of the Optional Variables, Date/Time Format variables, and server diagnostic
variables of the enovia.ini file used for the Studio Modeling Platform or desktop
applications, can also be used in the enovia.ini for the Live Collaboration Server. The
variables that are NOT used by the Live Collaboration Server are:
•
those that are listed in Dynamically Updated Variables and are updated via Session/
Preferences;
•
those that are used for dialog placement and shown in Application Sections;
•
those that used for Customizing Help;
•
Font and Color Variables;
•
those that are user specific or have to do with the Graphical User Interface, as listed
below:
•
USER and MX_HOME_VAULT are user-specific and would not be desirable for
all Web clients.
•
FIND_LIMIT—server uses MX_BOS_FIND_LIMIT instead.
•
MQLWINDOWDISPLAY and MX_BACKGROUND_OPEN are used for
debugging programs, which shouldn’t be done on the Web.
•
MX_BACKGROUND_OPEN and MX_WIN_MIN_ON_LAUNCH have to do
with launching applications, which is a completely different mechanism on the
Web.
•
MX_EXPAND_ALL is not used—by default, formats are not expanded to show
files checked in when the Formats dialog box is displayed.
•
MX_RESTRICT_EXPAND—server uses MX_BOS_EXPAND_LIMIT instead.
Refer to Configuring ENOVIA Live Collaboration in Chapter 9 for more information.
Time Zones
through ENOVIA
Live Collaboration
Server
ENOVIA Live Collaboration stores times in Greenwich Mean Time (GMT) and performs
a run time conversion to display them in the client’s local time zone. However, times
displayed on Web clients (Web Navigator users as well as users of other programs that
connect via a Live Collaboration Server) will be in the time zone available to the server,
and not necessarily in the time zone of the Web client. For example, if a user in California
connects to a Live Collaboration Server in Connecticut that uses eastern time, times
displayed for that user will be in eastern time. Also, if that same user creates objects, the
create time will be stored in the database based on the eastern time converted to GMT.
The Live Collaboration Server gets its time zone in the same manner as other ENOVIA
Live Collaboration clients, and passes time information to a Web client in the time zone it
knows about.
222
ENOVIA Live Collaboration Installation Guide
UTF-8 Settings
UTF-8 encoding is recommended for supporting any language(s)—multiple non-English
languages or English-only. In addition, the database layer must use a character set (that is,
“content type”) that is a superset of all character requirements. Refer to Chapter 3,
Installing an Oracle Database for database configuration recommendations.
In order to support multiple languages, it is recommended that UTF-8 encoding is used on
all tiers. Therefore, even if you currently have no requirements to support other languages,
new implementations should establish a UTF-8 environment so that future flexibility is
simplified. If you are working in a legacy environment with a different content type (such
as csWindows31j), UTF-8 may be used on the top tiers but stored in the legacy character
set. However, in this scenario, you will not be able to support data content in other
non-English languages. Data migration to UTF-8 is possible via database tools; however,
for large databases the task is not trivial. Contact your database vendor for more
information.
You select UTF-8 support during Live Collaboration Server installation, which
automatically creates UTF-8 settings in your environment. For a description of these
settings see Automated UTF-8 Settings.
To finish enabling UTF-8, you must make additional changes to your configuration, as
described in Additional Manual UTF-8 Settings.
Automated UTF-8
Settings
This section describes the changes that automatically occur when UTF-8 support is
selected in Live Collaboration Server installations.
Changes for all J2EE application servers
•
The startup scripts for the Application Servers set the following:
MX_CHARSET=UTF8
LANG=C
NLS_LANG=_UTF8
On UNIX, these settings are made in mxEnv.sh and are exported as required. The
Application Server startup script runs this file. On Windows, these variables are set in
the enovia.ini file.
•
The following setting is added to web.xml:
ematrix.encoding=UTF8
RMI Standalone (non-RIP) changes
•
Both the rmid startup script as well as the RMIService set the following:
LANG=C
MX_CHARSET=UTF8
On UNIX the settings are exported as required. On Windows these variables are set in
the enovia.ini file.
Chapter 8: Installing the Live Collaboration Server
223
WebLogic changes
The following lines in weblogic.xml are uncommented:
<charset-params>
<input-charset>
<resource-path>/*</resource-path>
<java-charset-name>UTF8</java-charset-name>
</input-charset>
</charset-params>
WebSphere changes
In ibm-web-ext.xmi, which is located in SERVERHOME/ematrixwarutil/, the
autoRequestEncoding and autoResponseEncoding settings are enabled in
<webappext>. For example:
<webappext:WebAppExtension xmi:version="2.0" xmlns:xmi="http://
www.omg.org/XMI" xmlns:webappext="webappext.xmi"
xmlns:webapplication="webapplication.xmi" xmlns:xsi="http://
www.w3.org/2001/XMLSchema-instance" xmi:id="WebApp_1_Ext"
reloadInterval="60" reloadingEnabled="false"
fileServingEnabled="true" directoryBrowsingEnabled="false"
serveServletsByClassnameEnabled="false"
autoRequestEncoding="true" autoResponseEncoding="true">
Sun Java System Application Server changes
The sun-web.xml file has the following entries added:
<sun-web-app>
<locale-charset-info default-locale="en_US">
<locale-charset-map locale="en" charset="ISO-8859-1"/>
<locale-charset-map locale="en_US" charset="ISO-8859-1"/>
<locale-charset-map locale="ja" charset="UTF-8"/>
<locale-charset-map locale="ja_JP" charset="UTF-8"/>
<locale-charset-map locale="fr" charset="UTF-8"/>
<locale-charset-map locale="fr_FR" charset="UTF-8"/>
<locale-charset-map locale="de" charset="UTF-8"/>
<locale-charset-map locale="de_DE" charset="UTF-8"/>
<locale-charset-map locale="it" charset="UTF-8"/>
<locale-charset-map locale="it_IT" charset="UTF-8"/>
<locale-charset-map locale="ko" charset="UTF-8"/>
<locale-charset-map locale="ko_KR" charset="UTF-8"/>
<locale-charset-map locale="ko_KP" charset="UTF-8"/>
<locale-charset-map locale="zh" charset="UTF-8"/>
<locale-charset-map locale="zh_CN" charset="UTF-8"/>
<locale-charset-map locale="zh_TW" charset="UTF-8"/>
</locale-charset-info>
</sun-web-app>
224
ENOVIA Live Collaboration Installation Guide
Additional Manual
UTF-8 Settings
This section describes changes you must make to your Application Server environment
after selecting UTF-8 support during Live Collaboration Server installation. These
changes are for all platforms besides AIX. For AIX changes, see Additional Manual
UTF-8 Settings for AIX. Manual changes are required for all application.
To make manual changes for WebLogic
Edit the startWebLogic.sh/startWLS.sh (UNIX) or startWebLogic.cmd/startWLS.cmd
(Windows) file, located in the WebLogic installation directory. In $JAVA_OPTIONS or
the line that starts up the Java process add the following after the classpath:
-Dfile.encoding=ENCODING
WHERE:
ENCODING is the character encoding that the JVM will run in. This needs to be
equal to UTF-8.
For example, the line should read:
$JAVA $JAVA_OPTIONS -ms128m -mx128m -classpath
$JAVACLASSPATH -Dfile.encoding=UTF-8 ...weblogic.Server
Java accepts both “UTF-8” or “UTF8”.
To make manual changes for WebSphere
1. Open the WebSphere admin console (http://machinename:9090/admin) and log in.
2. Click Servers in the left-side tree.
3. Click Application Servers under Servers.
4. Click the server name in the right-side frame.
5. Scroll down and click the Process Definition link in the right-side frame.
6. Click the Java Virtual Machine link in the right-side frame.
7. Scroll down to the Generic JVM arguments field and add the following:
-Dclient.encoding.override=UTF-8
-Ddefault.client.encoding=UTF-8
-Dfile.encoding=UTF-8
For AIX you also need:
-Xmso1152k -Xss1024k
8. Click OK and then click the Save link at the top of the page.
9. Stop and restart the server.
To manual changes for Sun Java System Application Server
Using the Sun Java System Application Server Administrator’s console, add the following
JVM options on the JVM settings tab:
-Dfile.encoding=UTF-8
To make manual changes for Tomcat
1. In TOMCATINSTALLDIR/bin/startup.sh, add the following setting in
startup.sh
CATALINA_OPTS="-Dfile.encoding=UTF-8 -server"
Chapter 8: Installing the Live Collaboration Server
225
2. In TOMCATINSTALLDIR/webapps/enovia/WEB-INF/web.xml,
uncomment the Tomcat UTF-8 settings:
<!--
TomCat UTF-8 settings
<filter>
<filter-name>Set Character Encoding</filter-name>
<filter-class>com.matrixone.servlet.SetCharacterEncodingFilter</filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Set Character Encoding</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
-->
3. In TOMCATINSTALLDIR/conf/server.xml, add the URIEncoding parameter
to the connector as shown below in bold:
<Connector acceptCount="100" connectionTimeout="20000"
disableUploadTimeout="true" port="8080" redirectPort="8443"
URIEncoding="UTF-8">
</Connector>
Additional Manual
UTF-8 Settings for
AIX
This section describes changes you must make to your Application Server environment
after selecting UTF-8 support during Live Collaboration Server installation with an AIX
platform.
To make manual changes for WebLogic
1. Edit the web.xml file located in SERVERHOME/distrib/enovia/WEB-INF/ by
adding the following lines under ContextParam 11:
<context-param id="ContextParam_12">
<param-name>weblogic.httpd.inputCharset./*</param-name>
<param-value>UTF-8</param-value>
</context-param>
2. Add the following without quotes to the startWebLogic.sh/startWLS.sh (UNIX) or
startWebLogic.cmd/startWLS.cmd (Windows) file located in the WebLogic
installation directory:
MEM_ARGS="-Xms512m -Xmx512m -Dfile.encoding=UTF-8 -Xss1024k
-XX:NewSize=80m -XX:MaxNewSize=80m -XX:MaxPermSize=128m:-Xnocl
assgc -XX:+DisableExplicitGC"
On Windows, you must add “set” (without quotes) in front of MEM_ARGS.
226
ENOVIA Live Collaboration Installation Guide
To make manual changes for WebSphere
1. Open the WebSphere admin console (http://machinename:9060/ibm/console and log
in.
2. Click Servers in the left-side tree.
3. Click Application Servers under Servers.
4. Click the server name in the right-side frame to open the configuration page.
5. Click Java and Process Management under Server Infrastructure.
6. Click Process Definition.
7. Click Java Virtual Machine under Additional Properties.
8. Scroll down to the Generic JVM arguments field and add the following:
-Dclient.encoding.override=UTF-8
-Ddefault.client.encoding=UTF-8
-Dfile.encoding=UTF-8
For AIX you also need:
-Xmso1152k -Xss1024k
9. Click Apply and then click the Save link at the top of the page.
10. Stop and restart the server.
To make manual changes for Sun Java System Application Server
Using the Sun Java System Application Server Administrator’s console, add the following
JVM options on the JVM settings tab:
-Dfile.encoding=UTF-8
To make manual changes for Tomcat
1. In TOMCATINSTALLDIR/webapps/enovia/WEB-INF/web.xml,
uncomment the Tomcat UTF-8 settings:
<!--
TomCat UTF-8 settings
<filter>
<filter-name>Set Character Encoding</filter-name>
<filter-class>com.matrixone.servlet.SetCharacterEncodingFilter</filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>UTF-8</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>Set Character Encoding</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
-->
Chapter 8: Installing the Live Collaboration Server
227
2. Add the following without quotes to catalina.sh or .bat on Windows located in
TOMCATINSTALLDIR/bin:
CATALINA_OPTS="-Xms512m -Xmx512m -Xss1024k -XX:NewSize=230m
-XX:MaxNewSize=230m -XX:SurvivorRatio=2 -XX:MaxPermSize=128m
-Dfile.encoding=UTF-8 -server"
On Windows, you must add “set” (without quotes) in front of CATALINA_OPTS.
228
ENOVIA Live Collaboration Installation Guide
File Collaboration Server
The ENOVIA Live Collaboration Server may be installed on the same host or a host in the
same LAN as those used for your file stores. When installed in this way, it acts as a File
Collaboration Server (FCS) to provide better performance for file operations to remote
sites. File Collaboration Servers require an Application Server and JDK. Your stores and
locations should reference the URL to their closest FCS server.
Refer to the System Manager Guide and the Application Development Guide for more
information on FCS.
Setting Up the FCS
Synchronization
Server
The File Collaboration Server (FCS) Synchronization Server is an ENOVIA V6
administration tool used to monitor and plan replicated store synchronization, and
facilitate production data management.
For customers deploying the ENOVIA V6 server with a multi-site configuration, this tool
makes location synchronization easy and efficient. It is a centralized administration server
for multi-site deployment.
A few definitions
File Collaboration
Server (FCS)
The File Collaboration Server (FCS) is the ENOVIA V6 server component in charge of
file storage.
Store
A store is a logical view of a storage location for checked-in files. A store typically
comprises, among other features, an FCS URL and a storage path (which can be
considered to be the default location).
Location
A location references alternate FCSs to be used by a store when distributing and
replicating files. The location specifies the URL of an FCS and a storage path.
Site
A site is an administrative object referencing one or more locations. The site is then added
to the definition of a group or person, to reference FCSs that are physically located closest
to persons concerned. Sites are created by System Administrators, and are needed
primarily when using multiple, distributed FCSs for performance purposes, leading to a
need for replication.
Replicated store
Stores can be distributed using asynchronous replication. Data is duplicated to all mirrored
locations only when commands are executed instructing the database to do so. Therefore,
when files are checked in, they are written to the location for the store that is also part of
the user's preferred site, or if no match is found, to the store's default location. They are not
replicated to alternate locations until specifically instructed to do so.
Store replication makes sense when an ENOVIA V6 deployment spans through network
links with low bandwidth and/or high latency.
Multi-site Installation
A multi-site installation is an ENOVIA V6 deployment containing at least two sites and
two locations with replicated stores.
Overview of FCS Synchronization Server functionality
The FCS Synchronization Server performs synchronization between two locations of the
same store or a location and its store based on customer-defined synchronization rules.
Chapter 8: Installing the Live Collaboration Server
229
The FCS Synchronization Server monitors the progression of these synchronization rules
and returns information on the amount of synchronized data and the locations concerned.
FCS Synchronization Server deployment
The FCS Synchronization Server is deployed as a daemon program, running on the central
site, connected to the database.
How the FCS Synchronization Server components work
The FCS Synchronization Server daemon is a multi-threaded stand-alone process in
charge of selecting and executing the synchronization rules. Its activity is traced in three
rotating log files.
The synchronization server periodically sends HTTP FCS “ping” requests to the FCS
servers managing locations involved in synchronization rules.
Supported synchronization rules
All rules perform synchronization between two locations of the same store or a location
and its store.
•
Rules executed periodically: the specific parameter for this rule is the time interval
between two executions. For example, synchronize two locations every two hours,
means that two hours must elapse between two executions of this rule.
•
Rules executed daily, weekly, monthly: the specific parameter for those rules is a date.
•
Rules executed when the amount of non up-to-date data files between two locations or
a location and store reaches a fixed value: for example, synchronize a store and one of
its location when the size of non up-to-date data files is above 100m.
These synchronization rules can also contain compression, concurrency, and business
object list definitions.
Configuring Synchronization Server daemon parameters
Configure as follows:
• Rules check frequency: the synchronization server daemon periodically checks for rules
to be executed. This parameter defines the frequency of those checks.
• Max-retry: the synchronization server daemon counts the number of times a business
object file synchronization fails. When this count reaches max-retry, the bus will be
excluded from all synchronization rule execution. In this case, the bus is listed on the log.
• Rule declaration: synchronization rules are declared in the <syncrules> section of
Synchronization Server xml rule file.
Here is the DTD of the syncrules section:
<!ELEMENT syncrules ( syncrule+ ) >
<!ELEMENT syncrule ( store , source , dest ,
daily | weekly | monthly | size | delay ) >
<!ATTLIST syncrules locale CDATA >
<!ATTLIST syncrule name CDATA #REQUIRED >
<!ELEMENT daily ( synctime ), zip? | concurrency? | buslist? >
230
ENOVIA Live Collaboration Installation Guide
<!ELEMENT weekly ( synctime ), zip? | concurrency? | buslist? >
<!ELEMENT monthly ( synctime), zip? | concurrency? | buslist? >
<!ELEMENT size ( syncsize ), zip? | concurrency? >
<!ELEMENT delay ( syncdelay ), zip? | concurrency? | buslist? >
<!ELEMENT synctime (#PCDATA)>
<!ELEMENT syncsize (#PCDATA)>
<!ELEMENT syncdelay (#PCDATA)>
<!ELEMENT zip>
<!ELEMENT concurrency (#PCDATA)>
<!ELEMENT buslist (class , param+ )>
<!ELEMENT class (#PCDATA)>
<!ELEMENT param (#PCDATA)>
<!ATTLIST param
name CDATA #REQUIRED
value CDATA #REQUIRED>
Here is a sample <syncrules> section:
<?xml version="1.0"?>
<syncrules locale="en_US">
<syncrule name="rule1">
<store>plmx</store>
<source>dali4dsy</source>
<dest>plmx</dest>
<daily>
<synctime>16:00</synctime>
</daily>
<zip/>
<concurrency>4</concurrency>
</syncrule>
<syncrule name="rule2">
<store>plmx</store>
<source>dali4dsy</source>
<dest>plmx</dest>
<weekly>
<synctime>Monday 11:00</synctime>
</weekly>
</syncrule>
<syncrule name="rule3">
<store>plmx</store>
<source>dali4dsy</source>
<dest>plmx</dest>
<monthly>
<synctime>13 16:00</synctime>
</monthly>
</syncrule>
<syncrule name="rule4">
Chapter 8: Installing the Live Collaboration Server
231
<store>plmx</store>
<source>dali4dsy</source>
<dest>plmx</dest>
<size>
<syncsize>150</syncsize>
</size>
</syncrule>
<syncrule name="rule5">
<store>plmx</store>
<source>plmx</source>
<dest>gagny2dsy</dest>
<delay>
<syncdelay>05:00</syncdelay>
</delay>
</syncrule>
<syncrule name="rule6">
<store>plmx</store>
<source>gagny2dsy</source>
<dest>plmx</dest>
<delay>
<syncdelay>03 12:00</syncdelay>
</delay>
</syncrule>
<syncrule name="rule7">
<store>plmx</store>
<source>gagny2dsy</source>
<dest>plmx</dest>
<daily>
<synctime>11:00</synctime>
</daily>
<buslist>
<class>com.dassault_systemes.fcs.syncserver.FileBus
ListTNRIterator</class>
<param name="path" value="E:\path_to_buslist_file\
buslist.txt" />
</buslist>
</syncrule>
</syncrules>
In the above sample:
232
•
Rule “rule1” will be launched at 16:00 (tea time) every day and executed on four
concurrent threads. The file synchronization streams generated by the rule will be
compressed.
•
Rule “rule2” will be launched at 11:00 AM every Monday.
•
Rule “rule3” will be launched at 16:00 (tea time) every 13th of the month.
ENOVIA Live Collaboration Installation Guide
•
Rule “rule4” will be launched when the amount of data to synchronize reaches
150 MB.
•
Rule “rule5” will be launched 5 hours after the last “rule5” run finished.
•
Rule “rule6” will be launched 3 days and 12 hours after the last “rule6” run finished.
•
Rule “rule7” will be launched at 11:00 AM every day and synchronize only the files
of the business objects listed in buslist.txt.
The locale attribute of the <syncrules> node defines the locale in which time and
dates is expressed in the rule definition file. This locale attribute is optional. If not
provided, the synchronization server hosting system's locale is used for date and time
parsing.
Accepted values for the locale attribute follow the pattern “aa_BB”:
•
“aa” expresses language encoded by two lowercase letters using the ISO-639 code
•
“BB” expresses country with two upper case letters using the ISO-3166 code.
Samples: “fr_FR” French locale and France, “en_UK” English locale for the United
Kingdom.
Time and date values in rule definitions
All time values are locale dependant, using jvm default local.
For daily rules <daily>, accepted sync time is “HH:mm” in 24h. As usual, “H” stands
for an hour digit, “m” stands for a minute digit, and “s” for a second digit.
For weekly rules <weekly>, accepted sync time format is “EEEE HH:mm” where “E”
stands for day-in-week letter. For example, with the German locale, “di 14:30” stands for
“Dienstag, 14:30”. Writing “dienstag 14:30” is recommended.
Using the French locale, to create a weekly rule starting every Friday a 8:30 PM, you can
set synctime value to “vendredi 20:30”.
For monthly rules <monthly>, accepted sync time format is “dd HH:mm”, where “d”
stands for a day-in-month digit.
For delay rules <delay>, accepted sync delay formats are “dd HH:mm” and “HH:mm”.
For size rules <size>, a positive non-zero integer is expected, ranging from 1 to 2 147
483 648. This size is implicitly expressed in megabytes (m). Size rules cannot contain
business object list definitions.
WARNING: A size below 100m might impair MCS performance.
Compression definitions
The zip flag <zip/> can be used in any rule to compress the file synchronization streams
generated by the rule. Compressed synchronization should only be used in a WAN
environment (the underlying network should have more than 1ms of latency) and when the
files involved are not already in a compressed format (for example, zip, jpg, gif, gz, etc.).
Concurrency definitions
The concurrency flag <concurrency> can be used in any rule to execute the rule on
more than one thread. Executing a rule on multiple threads increases synchronization
Chapter 8: Installing the Live Collaboration Server
233
performance in WAN environments by using more bandwidth for file synchronization.
The FCS Synchronization Server uses a smart dispatcher to prevent dead-locks and to
distribute the file synchronization operations evenly across the available threads. It is
recommended that no more than six threads be used to execute a rule. Concurrency should
only be used in a WAN environment.
Business object list definitions
The business object list flag <buslist> can be used in any rule except size rules to
restrict file synchronization to only the files of the business objects listed in a text file. The
public sync server interface, com.dassault_systemes.fcs.syncserver.BusTNRIterator, is
used to implement this restrictive list. This interface is found in FCSSyncServer.jar.
The text file containing the list of business objects should contain a line for each business
object. Each line must contain a type, name, and revision separated by the pipe character
(type|name|revision). The type, name, and revision combination should uniquely identify
the business object. For example:
VPLMtyp/PLMRepresentationDS|Fermoir Long_CENTRAL1806Representation87|--VPLMtyp/PLMRepresentationDS|Maintien court_CENTRAL1806Representation88|--VPLMtyp/PLMRepresentationDS|Maintien long_CENTRAL1806Representation89|--VPLMtyp/PLMRepresentationDS|Fermoir_CENTRAL1806Representation90|--VPLMtyp/PLMRepresentationDS|CouronneRonde_CENTRAL1806Representation91|--VPLMtyp/MaterialDomainDS|CENTRAL1806_Aluminium_MATERIAL_4MATERIAL|--VPLMtyp/PLMRepresentationDS|CENTRAL1806Representation47|--VPLMtyp/PLMRepresentationDS|Aiguilles_CENTRAL1806Representation94|--VPLMtyp/PLMRepresentationDS|Verre Saphir_CENTRAL1806Representation96|--VPLMtyp/PLMRepresentationDS|Corps_CENTRAL1806Representation97|---
Running the FCS
Synchronization
Server
The synchronization server daemon is launched via the VPMSyncDaemon.bat and
VPMSyncDaemon.sh scripts. This script starts a Java process running. Process behaviour
is defined by the XML rule file passed (among other arguments) to the starting shell.
The FCS synchronization server daemon process should run in a server environment as it
needs to access the MATRIX-R bootstrap file.
You can monitor synchronization server daemon activity in the generated logs. See the
-logPath and -logSize arguments below.
EV6 system administrator privileges are required to run the FCS Synchronization Server.
To run the FCS Synchronization Server on Windows
1. Go the installation folder:
SERVER_INSTALL\Apps\VPMMultiDiscipline\V6R2011x\bin\winnt\
2. Run the following command with the appropriate command-line parameters:
VPMSyncDaemon.bat
To run the FCS Synchronization Server on AIX
1. Go the installation folder:
SERVERHOME/Apps/VPMMultiDiscipline/V6R2011x/scripts/
2. Run the following command with the appropriate command-line parameters:
VPMSyncDaemon.sh
234
ENOVIA Live Collaboration Installation Guide
Command-line parameters
This is the full list of command-line parameters:
Parameter
Mandatory (M)/
Optional (O)
Description
-url MATRIXURL
M
URL of the ENOVIA V6 server or MCS Server, http://host:port/
root-uri/
-user USER
M
ENOVIA V6 connection user with system privileges
-password PASSWORD
M
Password of the ENOVIA V6 connection user, no scrambling.
-role ROLE
M
Role of the ENOVIA V6 connection user
-ruleFiles FILE1
[FILE2 [...]]
M
Sync Server configuration rules file, full path required
[-maxRetries NNN]
O
If a business object file synchronization fails more than NNN times it
will be discarded from further sync operations. Traces of this issue are
in the log file, with the ID of the failing business object. So the VPLM
system administrator should look (using MQL) at business object
history to see which file operation went wrong, or apply the checker.
Default: 5.
[-maxSyncRunner
Threads NNN]
O
Maximum number of threads used by the SyncRunner.
[-rulesCheckSecond
Elapse NNN]
O
Seconds elapsed between two checks of sync rule execution. Daily,
weekly, monthly rule execution time must not exceed <synctime>
value + 2*NNN. Default: 300.
[-logPath
path_of_the_log_
files]
O
A directory path. This directory will contain log files of the
SyncDaemon. Logs are written to three log files, fcssyncd0.out,
fcssync1.out and fcssyncd3.out. These logs are rotating logs, only one
is active at a time.
[-logSize
logfile_max_size_
in_megabytes
default 5]
O
Maximum size of an fcssyncX.out file.
[-proxyHost]
O
Host name of a proxy server
[-proxyPort]
O
Port number of a proxy server
[-nonProxyHosts]
O
Indicates the hosts which should be connected to directly and not
through the proxy server. The value can be a list of hosts, each
separated by a |, and in addition a wildcard character (*) can be used
for matching. For example: -nonProxyHosts="*.foo.com|localhost".
[-h] [-help]
O
Displays command line options help.
Chapter 8: Installing the Live Collaboration Server
235
Validating and
Debugging an FCS
System Administrators can validate an FCS installation by accessing the FCS About page.
The FCS About page shows important information about the FCS and is useful in
debugging operations. Additionally, accessing this page triggers the FCS to re-calibrate
any time differences that may exist between it and the MCS. A time is recorded for an FCS
and when the time is changed for a time change event like daylight savings time, this
recorded value is no longer correct and needs to be re-calibrated.
To access the FCS About page, run the following command from a web browser:
http://FCShost:Port/enovia/servlet/fcs/about
FCShost is the IP address or hostname of the machine on which the FCS is installed. Port
is the port where the FCS is located. For example: http://localhost:8089/enovia/servlet/fcs/
about.
236
ENOVIA Live Collaboration Installation Guide
Installing Multiple ENOVIA Live Collaboration
Servers (RIP only)
If you wish to provide access to more than one database via the same Web server host, you
need to install multiple instances of your Application Server, each with an RMI (RIP) Live
Collaboration Server pointing to a different ENOVIA schema. Refer to the following for
each instance:
•
Installing a Web or Application Server
•
Preparing to Install the ENOVIA Live Collaboration Server
•
Configuring the ENOVIA Live Collaboration Server
•
Chapter 10, Deploying J2EE
Use of one host machine for Web Access to multiple ENOVIA databases is supported by
the RIP Live Collaboration Server only.
Keep in mind for backup and maintenance purposes, that all servers must come down prior
to the database server.
Chapter 8: Installing the Live Collaboration Server
237
Interface for Downstream Installers, E4All, and
other Automated Installers
For downstream installers to be able to add their files into a previously installed ENOVIA
kernel installation, both the Live Collaboration Server and Studio Modeling Platform
Setup programs deposit a file named enovia.install into the top-level directory of the
respective installation to describe where various categories of files are to be found.
Internal Directory
Structure Defined
in enovia.install
Downstream installers must deposit their files in the correct locations. In order to do this,
they must do all of the following:
•
Request the kernel install directory as part of their installation process.
•
Use the directories specified in the enovia.install file, which can be found in the
top-level kernel installation directory:
•
•
SERVERHOME on UNIXor SERVER_INSTALL on Windows (Live
Collaboration Server)
•
ENOVIAHOME on UNIX or ENOVIA_INSTALL on Windows (Studio
Modeling Platform)
Construct the file target location based on the retrieved entries. The following are
some key paths that may need to be updated:
Old path (hard-coded)
New path (dynamically generated)
MQL Command
server\bin\winnt\mql.exe
<MQL_COMMAND>
Java Properties Path
server\java\properties\
<MANAGED_PATH>\properties\
Managed Path
server\managed\
<MANAGED_PATH>\
Staging Path
server\STAGING\ematrix\
<STAGING_PATH>\
Jar Path
server\java\lib\
Either:
<JAVA_COMMON_PATH>\ or
<JAVA_SERVER_PATH>\
Apps Path
studio\Apps\
<APP_INSTALL_PATH>\
The enovia.install file provides both necessary file names and absolute paths.
Example
enovia.install Files
238
The following is an example of a typical Server enovia.install file (on Windows):
ENOVIA_INI=C:\enoviaV6R2011x\server\intel_a\code\bin\enovia.ini
MQL_COMMAND=C:\enoviaV6R2011x\server\intel_a\code\bin\mql.exe
BIN_PATH=C:\enoviaV6R2011x\server\intel_a\code\bin
LIB_PATH=C:\enoviaV6R2011x\server\intel_a\code\bin
JAVA_COMMON_PATH=C:\enoviaV6R2011x\server\intel_a\docs\javacommon
JAVA_SERVER_PATH=C:\enoviaV6R2011x\server\intel_a\docs\javaserver
JAVA_CLIENT_PATH=C:\enoviaV6R2011x\server\intel_a\docs\java
JAVA_CUSTOM_PATH=C:\enoviaV6R2011x\server\intel_a\docs\custom
ENOVIA Live Collaboration Installation Guide
MANAGED_PATH=C:\enoviaV6R2011x\server\managed
DISTRIB_PATH=C:\enoviaV6R2011x\server\distrib
STAGING_PATH=C:\enoviaV6R2011x\server\STAGING\ematrix
APP_INSTALL_PATH=C:\enoviaV6R2011x\server\Apps
JAVA_CLASSPATH=C:\enoviaV6R2011x\server\intel_a\docs\javacommon;
C:\enoviaV6R2011x\server\intel_a\docs\javaserver;C:\enoviaV6R2011x\server\intel_a\docs\custom
JDK_PATH=C:\Java\jdk1.6.0_19
The Apps directory has been moved from ENOVIA_INSTALL\Apps\ (studio install tree)
to SERVER_INSTALL\Apps\ (server install tree).
The following is an example of a typical Studio enovia.install file (on Windows):
ENOVIA_INI=C:\enoviaV6R2011x\studio\intel_a\code\bin\enovia.ini
BIN_PATH=C:\enoviaV6R2011x\studio\intel_a\code\bin
LIB_PATH=C:\enoviaV6R2011x\studio\intel_a\code\bin
JAVA_COMMON_PATH=C:\enoviaV6R2011x\studio\intel_a\docs\javacommon
JAVA_SERVER_PATH=C:\enoviaV6R2011x\studio\intel_a\docs\javaserver
JAVA_CLIENT_PATH=C:\enoviaV6R2011x\studio\intel_a\docs\java
JAVA_CUSTOM_PATH=C:\enoviaV6R2011x\studio\intel_a\docs\custom
MANAGED_PATH=C:\enoviaV6R2011x\studio\managed
Matrix.ini and
eMatrix.ini File
Dependency
Removed
Both the Matrix.ini and eMatrix.ini files (formerly located in C:\WINDOWS\) have been
eliminated in ENOVIA sofware version V6R2011x. Rather than depending on these file to
determine the default ENOVIA core installation root path, downstream installers should
pop up a question and explicitly prompt the user to enter the core installation root path.
Studio Version of
MQL Command
Removed
Rather than using MQL from the Studio Modeling Platform installation
(ENOVIA_INSTALL on Windows or ENOVIAHOME on UNIX), downstream installers
should use MQL from the Live Collaboration Server installation (SERVER_INSTALL on
Windows or SERVERHOME on UNIX) in order to perform schema installation.
Uninstalling ENOVIA Live Collaboration Server
on UNIX/Linux
To uninstall the ENOVIA Live Collaboration Server software on UNIX/Linux
1. Back up the SERVERHOME\scripts\mxEnv.sh file and the
SERVERHOME\STAGING\ directory, if needed.
2. Remove the following ENOVIA server settings from the application server startup
script:
# MatrixOne
...
# MatrixOne
3. Delete the SERVERHOME directory.
Chapter 8: Installing the Live Collaboration Server
239
Uninstalling ENOVIA Live Collaboration Server
on Windows
To uninstall the ENOVIA Live Collaboration Server software on Windows
1. Back up the SERVER_INSTALL\<platform>\code\bin\enovia.ini file and
the SERVER_INSTALL\STAGING\ directory, if needed.
2. Stop the ENOVIA Server by clicking Start > All Programs > Dassault Systemes
Software V6R2011x > Stop ENOVIA Live Collaboration Server.
3. Remove the RMI window service as follows:
a ) Open a command prompt window.
b ) Enter the command:
> SERVER_INSTALL\<platform>\code\bin\RMIService.exe
-remove “ENOVIA Live Collaboration Server”
4. Remove the ENOVIA Live Collaboration Server-related shortcuts from the Start >
All Programs > Dassault Systemes Software V6R2011x menu.
5. Remove “SERVER_INSTALL\<platform>\code\bin” from the PATH
environment variable.
6. Delete the SERVER_INSTALL directory.
240
ENOVIA Live Collaboration Installation Guide
9
Configuring ENOVIA Live
Collaboration
Configuring ENOVIA Live Collaboration
ENOVIA Live Collaboration can be configured for each user’s environment. Environment
variables can be set in several ways:
1. By adding options to the command line of the application executable files.
2. By editing the initialization file in use (enovia.ini).
3. By editing the UNIX startup scripts that contain the variable settings for locating the
database and setting up the environment.
4. By adding personal properties to a person object.
5. By creating a program object called MatrixIniDefaults, which is designed to set
optional settings not set elsewhere.
6. By creating a program object called MatrixSystemDefaults, which is designed to set
those variables that must be set consistently between all users.
When ENOVIA Live Collaboration needs to read the value for a variable (with the
exception of the variables needed before a connection to the database is made), it checks if
the variable is allowed to be set locally (as described in Overriding Settings, below). If it
can be, it looks until it finds the setting in the following places:
241
•
first for properties on the current context person object, if it can be stored there (refer
to Setting Personal Preferences). If the person has a property of the same name as the
desired environment variable, its value is set.
•
next for the variable in the appropriate .ini file (enovia.ini) or shell script. If found, its
value is set.
•
next for a program in the database named MatrixIniDefaults. If it exists and sets a
value for the desired environment variable, its value is set.
•
in the case of a site preference, for the site on the group object.
If it cannot be locally set, its value is looked for in the Matrix System Defaults Program. If
not found there it uses the default value.
Wherever they are set, variables must be spelled correctly and set to appropriate values or
they are ignored.
Command Line
Options
You can append options to the command lines that run Studio Modeling Platform
applications. For example, MQL has a -v option that causes MQL to operate in verbose
mode. To use this option with Windows, create a shortcut for MQL and then bring up its
properties. The Properties window box shows the target path for the shortcut. For
example:
c:\enoviaV6R2011x\studio\intel_a\code\bin\mql.exe
Change the command line as follows:
c:\enoviaV6R2011x\studio\intel_a\code\bin\mql.exe -v
Save your changes by clicking OK. All Studio Modeling Platform command line options
can be set in this way. For a list of the command line options available, use the -help
option. For example:
c:\enoviaV6R2011x\studio\intel_a\code\bin\mql.exe -help
To see the command line options for the other desktop applications include a filename. For
example:
c:\enoviaV6R2011x\studio\intel_a\code\bin\matrix.exe -help
-stdout FILENAME
The file named FILENAME is written to the ENOVIA_INSTALL directory.
The Initialization
File/Startup
Scripts
Most software products that run under Windows use an .ini file to set environment
variables. UNIX uses startup scripts and sometimes ini files.
Windows
In Windows environments, Studio Modeling Platform applications read the enovia.ini file
upon startup to determine the location of the database and to set up the program
environment. During Studio Modeling Platform installation on Windows, the enovia.ini
file is placed in ENOVIA_INSTALL\studio\intel_a\code\bin\. The
applications then access the enovia.ini file as needed during the session. For example, the
pixmappath setting is read when the Studio Modeling Platform needs to display a .gif
image for the first time. When preferences or the size and location of a window are altered,
the changes are written to the enovia.ini file, and it is saved when the session is closed.
242
ENOVIA Live Collaboration Installation Guide
A typical Windows version of the enovia.ini file is as follows:
[MATRIX]
MATRIXHOME=C:\enoviaV6R2011x\studio\
MATRIXINSTALL=C:\enoviaV6R2011x\studio\
MX_FLASH_PATH=C:\enoviaV6R2011x\studio\mxcache
PIXMAPPATH=C:\enoviaV6R2011x\studio\intel_a\pixmaps\app\
COLORPATH=C:\enoviaV6R2011x\studio\intel_a\code\lib
MATRIXPATH=C:\enoviaV6R2011x\studio\intel_a\code\bin
MX_TCL_SHLIB=
TCL_LIBRARY=C:\enoviaV6R2011x\studio\intel_a\tcl85\lib\tcl8.5
TK_LIBRARY=C:\enoviaV6R2011x\studio\intel_a\tcl85\lib\tk8.5
TMPDIR=C:\DOCUME~1\ay8\LOCALS~1\Temp
MX_DEFAULT_KERNEL=
MX_JVM_DIR=C:\Program Files\Java\jdk1.6.0_19\jre\bin\client\
MX_JDK_DIR=C:\Program Files\Java\jdk1.6.0_19\
MX_JAVAC=C:\Program Files\Java\jdk1.6.0_19\bin\javac.exe
MX_CLASSPATH=C:\Program Files\Java\jdk1.6.0_19\lib;C:\
enoviaV6R2011x\studio\managed\properties;C:\enoviaV6R2011x\studio\
intel_a\docs\javacommon;C:\enoviaV6R2011x\studio\intel_a\docs\java
server;C:\enoviaV6R2011x\studio\intel_a\docs\custom;
LANG=C
UNIX
On UNIX, startup scripts are used to set up the program environment and establish the
location of the database. For the Live Collaboration Server, the variables are in mxEnv.sh.
The .ini file is created on UNIX upon closing the Studio Modeling Platform for the first
time. It is used to store optional settings, preferences, and changes to window size and
location. The file is stored in the user’s home directory, where it is referred to for
subsequent Studio Modeling Platform sessions. As on Windows, when preferences or the
size and location of a window are altered, the changes are written to the file, and it is saved
when the session is closed.
Live Collaboration Server Environment
When installing the Live Collaboration server to provide access to ENOVIA Live
Collaboration via Matrix Web Navigator or other Web-based applications, it must be set
up as any other ENOVIA Live Collaboration client. This means that it must not only have
a connection file (MATRIX-R file) and a database alias established, but it also requires an
initialization file on Windows. A separate file, also called enovia.ini is created and
installed when the ENOVIA Live Collaboration Server is installed on Windows platforms.
During Live Collaboration Server installation, the enovia.ini file is placed in
SERVER_INSTALL\intel_a\code\bin\ (previously C:\WINDOWS\). The
server’s enovia.ini file can (and should) contain most of the settings that have been added
to the enovia.ini file for your Studio Modeling Platform clients.
Chapter 9: Configuring ENOVIA Live Collaboration
243
On UNIX, “typical” settings are part of the default start up scripts for the server
(rmireg.sh, startweblogic.sh) in the same way as other ENOVIA Live Collaboration
clients. Likewise, “optional” variables may be set in the other configuration vehicles
available to every UNIX client: start up shell scripts, .ini file, or MatrixIniDefaults
program. Keep in mind that these settings on the server will be used for all Web users.
Refer to ENOVIA Live Collaboration Server Environment Settings in Chapter 8 for more
information on variables that apply only to the servers.
Setting the Location of the enovia.ini File on Windows
In Windows environments, it is highly recommended that the enovia.ini file (previously
matrix.ini) for the Studio Modeling Platform and the enovia.ini file (previously
ematrix.ini) for the Live Collaboration Server not be located in the Windows installation
directory or C:\WINDOWS. You can choose to put these files in any directory, however
enhanced Windows security does not permit applications to modify files in this directory.
Also, it is important to note that the enovia.ini file installed with the Studio Modeling
Platform and the enovia.ini file installed with the Live Collaboration Server are not
interchangeable and should not be placed in the same directory.
An enovia.ini file directory can be set in any of the following ways:
•
Appending the -inidir option to the command lines that run the Studio Modeling
Platform applications. For example:
mql.exe -inidir c:\enovia
For details on appending options, see Command Line Options.
•
When installing the Live Collaboration Server as a Windows service, the directory
can be set with the RMIService.exe config option. For example:
RMIService.exe -config "ENOVIA Live Collaboration Server"
-inidir c:\enovia
For details, see Reconfiguring the ENOVIA Live Collaboration Server Windows
Service.
•
Setting the Windows environment variable, ENOVIAINIDIR. For details, see Typical
Environment Variables.
•
Setting the enovia.inidir variable in the web.xml file. For details, see Web.xml.
•
When developing a custom Studio Customization Toolkit application, you can call the
static method, MatrixSession.setIniDirPath(PathToIni), to set the directory. This must
be done before any other Studio Customization Toolkit call is made.
•
When running a custom Studio Customization Toolkit application based on
eMatrixServletRMI or when using any Java based application server (e.g. Tomcat),
you can set the directory using the JAVA_OPTS: “-Denovia.inidir=PathToIniDir.” For
example:
java.exe -Denovia.inidir=c:\enovia myApp
The JAVA_OPTS must also be applied to the matrix.util.ComputedClassPath.
If you are running the RMI service in a command window (rmireg.bat), the
JAVA_OPTS must be applied to rmid.exe using “-C-Denovia.inidir=PathToIniDir.”
Since copies of the enovia.ini files can exist in more than one location on the same
machine, the system uses a lookup order to determine which files to use. This lookup order
is used to determine which file to use. It is not used to determine which values in that file
to use.
244
ENOVIA Live Collaboration Installation Guide
The table below lists the lookup order used. The system will attempt to use the directory
defined by the first method on the list. If no directory is defined, it moves on to the next
method down to the default directory, C:\WINDOWS. If the directory defined by a method
does not exist, the system will NOT move to the next method.
ENOVIA Studio
Modeling Platform
Applications
Web Server
ENOVIA Live
Collaboration
Server
Studio
Customization
Toolkit Application
Set directly to
MatrixSession
-inidir Argument.
Java Options
For Windows Service:
RMIService.exe config
(-inidir). For
Rmireg.bat: Java
Options enovia.inidir
Java Options
enovia.inidir.
web.xml file
Environment Variable
Environment Variable
Environment Variable
Environment Variable
Executable Location
eMatrix.jni.dll or
eMatrix.net.dll location
eMatrix.jni.dll location
eMatrix.jni.dll or
eMatrix.net.dll location
C:\WINDOWS
C:\WINDOWS
C:\WINDOWS
C:\WINDOWS
Setting Personal
Preferences
For .ini settings that are intended to express a personal preference, properties can be added
on person objects for Web users to override values set for the server. Only a few
environment variables are appropriate to set as person properties for Web Navigator users,
as well as users of other ENOVIA products. They are:
MX_DECIMAL_SYMBOL
MX_SITE_PREFERENCE
MX_ALIASNAME_PREFERENCE
MX_LANGUAGE_PREFERENCE
Language aliases are not supported for use with ENOVIA applications. Translations of
schema are handled via Java resource bundles. Therefore,
MX_ALIASNAME_PREFERENCE and MX_LANGUAGE_PREFERENCE should not be
set in the enovia.ini file for the Live Collaboration Server.
Refer to the Business Modeler or MQL Guide for more information on adding properties
to persons.
MatrixIniDefaults
Administrators can write a program called MatrixIniDefaults, that is designed to set
system-wide variables that should not be set elsewhere. The MatrixIniDefaults program
can be created in MQL or Business Modeler, to hold variable values using the same syntax
as the .ini file. No other logic is required. The settings in the program are used if the
variables are not set on either the current context object as a personal preference, or in the
applicable .ini file. For example, a MatrixIniDefaults program might include the following
code:
MX_NORMAL_DATETIME_FORMAT=moy/dom/yr4 h12:min:sec mer
Chapter 9: Configuring ENOVIA Live Collaboration
245
Since the MatrixIniDefaults program is in the database, it is shared by all users of the
system, regardless of the ini file they are referencing on their desktop or to which server
location they connect. This makes it a convenient place in which to manage settings which
should be in force for all users. Generally, only a very few (but crucial) variables are set in
this manner.
If the same variables are set locally (via .ini file) and globally (via MatrixIniDefaults),
local values override global values. This allows variables to be set locally as required for
administrative tasks such as running batch jobs, development tests, or diagnostics.
However, in most cases, there should be no duplication of settings between configuration
vehicles.
Certain settings are not suitable for MatrixIniDefaults, because they are required during
system startup, when no database connections exists. The following settings CANNOT be
set with MatrixIniDefaults and must be set through either the environment or the
enovia.ini file for the Live Collaboration Server (previously ematrix.ini):
Matrix System
Defaults Program
246
bootfile
MX_MEMORY_KEEP_LIMIT
COLORPATH
MX_MEMORY_SYSTEM_LIMIT
MATRIXHOME
MX_MEMORY_TRACE
MX_BOS_EXPAND_LIMIT
MX_SESSION_SILENT_TIMEOUT
MX_BOS_FIND_LIMIT
MX_SESSION_TIMEOUT
MX_BOS_ROOT
MX_SQL_TRACE
MX_BOS_WORKSPACE
MX_TRACE_FILE_PATH
MX_CHARSET
MX_VERBOSE_TRACE
MX_CLASSPATH
root
MX_CONNECTION_POOL_SIZE
workspace
MX_MAX_THREAD
.
MatrixSystemDefaults program is designed to allow administrators to centrally control
MX_ settings in a manner that cannot be overridden by local environment/ini-file settings.
This program is read as soon as a database connection is obtained, and used to initialize
the MX_ variables it contains. If this program exists, any variables not set in it, or not
allowed to be overridden use their default values. If no MatrixSystemDefaults program
exists, the system functions as described above. The diagram below describes the logic
used for setting variables.
ENOVIA Live Collaboration Installation Guide
Similar to the MatrixIniDefaults program, the format of the code section of the program
object named MatrixSystemDefaults must be identical to an ini file with one
NAME=VALUE per line. Comments can be indicated with ‘#’. However, the
MatrixSystemDefaults program can include any number of local sections so that servers or
groups of users can be pointed at specific configurations for each of them, by including the
name of the local section they need in their environment. The system defaults program can
also include a list of variables that are allowed to be overridden locally, using a variable
called MX_SYSTEM_OVERRIDE_ALLOWED. The sections that follow describe these
novelties of the MatrixSystemDefaults program.
Global and Local Sections
You can include section markers in square brackets to split the file into global settings,
which will apply to all users connecting to the database, and any number of local sections.
A section marked in brackets by something other than “Global” is considered to define a
set of local settings whose name is the set of characters in the brackets. Users connecting
Chapter 9: Configuring ENOVIA Live Collaboration
247
with the variable MATRIX_LOCAL_SETTINGS set (in the operating system
environment or the ini file) to text included in square brackets in the
MatrixSystemDefaults program, will use the settings in that section. If a setting is in both
the [Global] and [Local] sections, the value in the Local section will override the value in
the Global section.
It is not necessary to explicitly label a section as Global, but the Global section must
always be first. If the MatrixSystemDefaults program starts with lines of the form
NAME=VALUE that precede any section heading, they will be considered to constitute
the global settings. This section will terminate with the first section heading. If there is
more than one section with the same name, all but the first is ignored.
Overriding Settings
All variables with names beginning with “MX_” can be set somewhere other than in the
MatrixSystemDefaults program only if they are explicitly allowed by the
MX_SYSTEM_OVERRIDE_ALLOWED variable. This variable, which can only be set
in the global or activated local section of the MatrixSystemDefaults program, should be
set to a comma-delimited list of MX_ variable names. In this list, you can use the “*”
wildcard to match any number of characters. Other than variables that must be read before
the database can be started (see Initialization Settings), if there is a MatrixSystemDefaults
program, only those MX_ variables matching those in this list can be set in any way other
than through this program. If the MatrixSystemDefaults program exists, any variables not
set in it, or not allowed to be overridden use their default values.
In a Live Collaboration server environment, be sure to include MX_CLASSPATH in the
list of variables in MX_SYSTEM_OVERRIDE_ALLOWED in MatrixSystemDefaults
program object.
MX_SYSTEM_OVERRIDE_ALLOWED is only valid when set in the
MatrixSystemDefaults program. If set elsewhere, it is ignored.
Note that in a typical developer environment, when work is done against a development or
test version of the database, you may want to remove the MatrixSystemDefaults program
to allow the developers significant local control.
Initialization Settings
The following MX_ settings are read before the database is initialized and therefore
cannot be set in MatrixSystemDefaults:
MX_CHARSET
MX_MAX_THREAD
MX_MEMORY_KEEP_LIMIT
MX_MEMORY_SYSTEM_LIMIT
MX_MEMORY_TRACE
MX_SESSION_SILENT_TIMEOUT
MX_SESSION_TIMEOUT
In addition, MX_CONNECTION_POOL_SIZE must be read to create initial connections,
but could be overridden in MatrixSystemDefaults for subsequent connections.
248
ENOVIA Live Collaboration Installation Guide
Sample Program
The following is a commented version of a sample MatrixSystemDefaults program object:
[Global]
#
# This lists the variables that may be overridden by OS
environment or ini file settings
MX_SYSTEM_OVERRIDE_ALLOWED=
MX_CLASSPATH,*TRACE*,MX_EDITOR*,MX_TCL*
#
# These settings will be enforced for all users
MX_RESTORE_CONTEXT=FALSE
MX_RESTORE_TRIGGERS=TRUE
MX_NESTED_TRIGGER_MACROS=TRUE
MX_CONNECTION_POOL_SIZE=10
#
# These settings will be enforced for users who connect to an
# executable that was started with the variable
# MATRIX_LOCAL_SETTINGS=Paris (set in environment or ini file)
[Paris]
MX_LDAP_HOST=mxs1am
MX_LDAP_AUTHENTICATOR=xxx
MX_LDAP_BIND_DN=xxx
MX_LDAP_BIND_PASSWORD=xxx
…
# These settings will be enforced for users who connect to an
# executable that was started with the variable
# MATRIX_LOCAL_SETTINGS=Boston (set in environment or ini file)
[Boston]
MX_LDAP_HOST=mxmlsun1
MX_LDAP_AUTHENTICATOR=xxx
MX_LDAP_BIND_DN=xxx
MX_LDAP_BIND_PASSWORD=xxx
…
Protecting Against Locking All Users out
It is possible for a situation to develop in which no user can login. For example, consider
the case where an LDAP server is in use and the MatrixSystemDefaults program is set up
in such a way that users are not permitted to override the LDAP settings in their own ini
file or environment. In this case, the LDAP settings will be in the MatrixSystemDefaults
file, either in the global or a local section. Now consider what might happen if the LDAP
settings need to be modified, say, because the server is now on another machine. If the
settings have not been changed in the MatrixSystemDefaults program, LDAP will not
work and no further logins will be possible, including for System Administrators.
To protect against such problems, it is recommended to have a local settings section for
use by system administrators that allow any MX_ variables to be set. You will want to
make sure that no one other than system administrators know the name of this section. In
this regard, it is important to remember that if a program is set to hidden, the MQL
command print program will not print out the code of the program except for
business administrators who have program administrative access.
Chapter 9: Configuring ENOVIA Live Collaboration
249
If for some reason you are stuck and even administrators cannot login to fix the system, a
last resort is to change the name of the program in the database using a database tool such
as sqlplus to modify the database. The sql needed to accomplish this task is:
update mxProgram set mxName='MatrixSystemDefaults-bak' where
mxName='MatrixSystemDefaults';
Once the MatrixSystemDefaults program no longer exists, all users can set any MX_*
variables in their ini file or environment. An administrator can then login and fix the
MatrixSystemDefaults-bak program and rename it back to original name so that it controls
the appropriate settings.
250
ENOVIA Live Collaboration Installation Guide
ENOVIA Live Collaboration Settings
By adding or changing entries to the enovia.ini file for the Studio Modeling Platform,
certain settings can be adjusted or added in order for ENOVIA Live Collaboration to
perform properly in your environment. Other changes enhance the appearance of the
Studio Modeling Platform. All changes to the enovia.ini file must be done on each
machine requiring the specific modifications. The variables are described below.
ini/script settings can be up to be 4096 bytes long. However in Windows, the cmd shell
limitation on command line length is 2048 bytes. Refer to MX_CLASSPATH for an
explanation of the ComputedClassPath, which also must not exceed 2048 bytes in
Windows.
Refer to ENOVIA Live Collaboration Server Environment Settings in Chapter 8 for details
on which variables apply to the server.
Typical
Environment
Variables
The following are some of the variables specified in the [matrix] section of enovia.ini:
MATRIXHOME specifies the location of the connection file (MATRIX-R file).
After the installation is complete and Matrix is operational, the connection file
manages where the database resides.
MATRIXINSTALL is the root installation directory for Studio Modeling Platform or
Live Collaboration Server, as defined in the installation procedure. For example,
C:\enoviav6r2011x\studio\ or C:\enoviav6r2011\server\.
ENOVIAINIDIR is a Windows environment variable that specifies the location of
the enovia.ini file. For example: ENOVIAINIDIR=C:\enoviaV6R2011x\server\intel_a\code\bin. For details, see Setting the Location of
the enovia.ini File on Windows.
PIXMAPPATH is where Matrix looks for icons as images. If you have a library of
icons to use with Matrix, you can append the location of your icons to this value.
COLORPATH is the path to the RGB.txt file which defines the color mixtures to the
system.
MATRIXPATH is the execution directory, as defined in the installation procedure.
For example, <MATRIXINSTALL>\<platform>\code\bin\.
TCL_LIBRARY sets the path to the Tcl script, init.tcl, which initializes Tcl for use
with MQL.
TK_LIBRARY sets the path to the Tcl script tk.tcl, which initializes Tk for use with
MQL.
TMPDIR is a directory that ENOVIA Live Collaboration will use for temporary files.
Because each operating system also has its own environment setting for this use, you
should set TMPDIR to the same value as the TMP operating system variable for
predictable results. Once a transaction is completed, the files are removed from this
directory. If space is limited on the disk where ENOVIA Live Collaboration is
installed, you may want to change this to point to a disk with more free space.
On Windows, if TMPDIR is not set, it defaults to the value of the TEMP environment
variable setting. If one does not exist or is invalid, TMPDIR is set to the same
directory as MATRIXINSTALL. On UNIX, there is no default setting for TMPDIR
but the Live Collaboration kernel uses /usr/tmp/ if the variable is not set.
Chapter 9: Configuring ENOVIA Live Collaboration
251
MX_JVM_DIR specifies specifies the location of the Java Virtual Machine.
MX_JDK_DIR specifies specifies the location of the Java Development Kit.
MX_JAVAC specifies the location of the javac compiler.
MX_CLASSPATH contains the path to the Java compiler that is specified during the
ENOVIA Live Collaboration installation. It is used by the Studio Modeling Platform
and the ENOVIA Live Collaboration Server service when starting the Java Virtual
Machine (JVM) for both compiling and executing JPOs. With the Studio Modeling
Platform, if you are running JPOs that are provided with ENOVIA Businss Process
Services or other ENOVIA products, MX_CLASSPATH must include the path to the
Business Process Services jar files.
ComputedClassPath is a routine called by rmireg in RMI non-RIP setups that builds
the classpath by combining the environment classpath + MX_CLASSPATH + all .jar
files and all .zip files in each directory listed in MX_CLASSPATH. On Windows, if
the Computed Class Path exceeds 2048 bytes, errors will occur in the application
server or ENOVIA Live Collaboration Server service. If classpath errors occur due to
this Windows limitation, you should remove any references to unnecessary jar or zip
files in MX_CLASSPATH.
MX_ARCH specifies the Dassault Systèmes-defined architecture value (one of
intel_a, win_b64, aix_a64, linux_a64, linux_b64, solaris_a64, or solaris_b64). This
variable was previously named ARCH. It is automatically set in the rmireg.sh script.
FlashDB variables
FlashDB is a next generation caching technology that improves the stability and
scalability of the ENOVIA Live Collaboration Server. It replaces the c-tree engine
(“Turbocache”) used in Matrix since Version 7 with a more modern design. Stability
improvements are achieved limiting in-process memory use for caching database
information and using an embedded database on disk for working with large data sets that
require more memory. Also, FlashDB uses background threads for database reads and
writes, taking advantage of multi/hyper threaded machines, thereby improving scalability.
The following variables are used to configure FlashDB.
MX_FLASH_PATH sets the directory that KeyDB uses to store its temporary files.
Installation programs for the Live Collaboration server set this to SERVER_HOME/
mxcache and for Studio Modeling Platform to MATRIXHOME/mxcache.
Subdirectories beginning with “flash” (followed by 20 hex digits) are created to hold
each KeyDB instance, one for each session. A KeyDB instance is just a set of flat
files, so the depth of the directory tree is the depth of MX_FLASH_PATH + 1.
On UNIX servers, the mxcache directory is given 770 permissions (drwxrwx---) by
default. For the Studio Modeling Platform on UNIX, the permissions are set to 777
(drwxrwxrwx). Permissions can be adjusted as appropriate for your environment.
For the Studio Modeling Platform, this directory is cleaned up automatically when the
client exits. For the Live Collaboration server, the files are typically left behind when
the server exits. A purge of this directory should be implemented at regular intervals
to avoid waste of excessive disk space. Each application server should have a separate
setting for MX_FLASH_PATH to allow these temporary files to be cleaned up as part
of server startup and/or server maintenance, similar to how log files are maintained on
multiple servers.
252
ENOVIA Live Collaboration Installation Guide
For the ENOVIA Live Collaboration Server, there must be ample disk space available at
this directory location for these temporary files. The requirement will vary, but a good
starting point is to assume you will need 10% of the diskspace used by the database
tablespaces.
MX_HYPER_THREADED may be set to false in a server environment to turn off
the use of a background thread for communication to the database server. The default
is true. The default allows Flash to take advantage of multi-cpu’s during the
processing of a single transaction. This setting is ignored by the Studio Modeling
Platform, but is always false.
By following best practices (especially in the definition of queries and expands) you
should be able to avoid the need for the server to handle result sets so large that they need
to use disk I/O for most interactive operations. Any interactive operation that has high
memory requirements should be reviewed to reduce the size of the data set. However,
recognizing that there are use cases (such as report generation) that must process
extremely large datasets, FlashDB provides some controls on how much memory should
be used to cache database rows to process requests. If these limits are exceeded, FlashDB
will use local disk files for temporary storage of such data, so correctly setting these limits
can be important to prevent two serious consequences of excessive memory consumption:
•
If memory usage reaches the MX_MEMORY_SYSTEM_LIMIT, ENOVIA Live
Collaboration will start to produce “insufficient memory” errors and abort
transactions. See “Memory variables” below.
•
If the memory usage reaches the operating system limit, the process will shutdown.
By default, FlashDB does not use disk space for caching.
Memory variables
The following memory settings should be configured for your environment based on
installed server memory. Thread limits should be emphasized over system limits so only
long running operations are affected. As a best practice to increase server stability, data
should be paged to disk. Paging reduces in-process memory usage for large datasets. If
you periodically see “insufficient memory” errors in your mxtrace log, you need to
re-adjusted these settings to support larger in-process memory usage.
MX_CACHE_SYSTEM_LIMIT sets a threshhold on memory consumption for all
threads, before using KeyDB. If the number of bytes of in-process memory being
used by all active sessions exceeds this setting, FlashDB will start paging the database
rows for all sessions to disk. The default is 0, meaning unlimited, so no paging will
occur. MX_CACHE_SYSTEM_LIMIT should be set to no more than 80% of
MX_MEMORY_SYSTEM_LIMIT, in order to force paging to disk to occur
BEFORE the system memory limit is reached.
MX_CACHE_THREAD_LIMIT applies to a single thread only. If the number of
bytes of in-process memory being used by a single session exceeds this setting,
FlashDB will start paging the database rows for that single session to disk. No other
threads are affected. The default is 0, meaning unlimited, so no paging will occur.
MX_CACHE_THREAD_LIMIT should be set somewhat lower than
MX_CACHE_SYSTEM_LIMIT to minimize the likelihood that a single thread,
processing a large request, will affect the performance of other threads by consuming
all the memory. Use of this setting means that greedy threads will page data to disk,
Chapter 9: Configuring ENOVIA Live Collaboration
253
thereby slowing their processing, but also leaving more memory available for other
threads to use. A reasonable setting is 50% of the value of
MX_MEMORY_SYSTEM_LIMIT.
MX_MEMORY_SYSTEM_LIMIT is meant to be the high water mark of allowable
memory allocation for the native Live Collaboration kernel. The ENOVIA Live
Collaboration memory manager tracks the number of bytes allocated and will issue
warnings for every allocation over the MX_MEMORY_SYSTEM_LIMIT. There are
several areas in the Live Collaboration kernel that will also look for allocations over
the MX_MEMORY_SYSTEM_LIMIT and abort the transaction. These checks are
places in functional areas that are known to be memory intensive (database rowset
loading, queries, expands and history lookups). The goal is to have the Live
Collaboration kernel abort the transaction that is consuming large amounts of
memory while allowing the other threads to continue working.
MX_MEMORY_THREAD_LIMIT sets the maximum amount of memory that may
be used for a single ENOVIA Live Collaboration thread. The default is 1GB. Should
allocation attempts be made beyond this size, warning messages will be written to the
server log that identify the program file name and line number.
Optional Variables
The following variables are not required to be set in order for ENOVIA Live Collaboration
to function. When the variable is not explicitly set in the environment, ENOVIA Live
Collaboration uses the default values. If required, these values should be added to the
[matrix] section of the .ini file (or for UNIX, the startup script).
USER can be used with another optional variable, MX_HOME_VAULT, to let you
set a default context for ENOVIA Live Collaboration for Windows. USER is the
default user name and MX_HOME_VAULT is your default vault. If you are using
Windows, when a Studio Modeling Platform application is opened, the context
window comes up with the user name as it appears in SYSTEM.INI, unless the USER
variable is set here.
HOME is your default home directory.
FINDLIMIT sets the default limit field in ENOVIA Live Collaboration Find
window. Defaults to 0 or no limit. Does not affect MQL queries. The results of some
queries will load faster in the details view if a limit is specified. Setting FINDLIMIT
allows you to establish a default value to optimize performance in case no limit is set
in the query. When limits are set in the query, this value is ignored, and the new value
does not change this setting. To optimize performance, but still find all objects that
meet the criteria, you may want to make this value very large, for example,
FINDLIMIT=100000.
MQLWINDOWDISPLAY when set to true, displays an MQL window when running
eMatrixMQL/MQLIO that may be used to diagnose and debug these programs and
applications. The default is false, which means that the MQL session appears as a
button on the Windows task bar for eMatrixMQL/MQLIO, matrix -wizard, matrix -c,
mql -c -d, and openedit, but cannot be opened. (Note: use of mql -c without '-d' does
display the window).
MX_ANNOTATION_TYPE sets the non-English word used for Annotations. A
business object type of the name specified here must be defined in order for the
Annotation function to operate properly when used in a non-English setting. The
default is Annotation.
254
ENOVIA Live Collaboration Installation Guide
MX_ATTACHMENT_TYPE sets the non-English word used for Attachments. A
business object type of the name specified here must be defined in order for the
Attachment function to operate properly when used in a non-English setting. The
default is Attachment.
MX_REPORT_TYPE sets the non-English word used for Reports. A business
object type of the name specified here must be defined in order for the Report
function to operate properly when used in a non-English setting. The default is
Report.
MX_ABORT_DANGLING_TRANSACTION, when set to TRUE, tells a top-level
program to abort any uncommitted transactions upon exiting, as long as the
transaction was not already open when the program was started. This prevents
transactions from being left hanging, with its table locks intact, until the Live
Collaboration server or Studio Modeling Platform application is shut down and
restarted. On the Live Collaboration server, this is set to TRUE by the default
installations.
MX_ACCESS_LOG may be enabled by setting this variable to true. Access logging
provides auditing of all access right grants and denials. UNIX systems make use of
the UNIX syslog(3) interface to log, write, or forward messages to designated files or
users; on Windows systems, the Application Event Log is used. The default is false,
meaning logging of access is off. Refer to the MQL Guide for more information on
access logging.
MX_BACKGROUND_OPEN allows background processes to be launched (for
example, Open for Edit or View) while still allowing the Studio Modeling Platform to
operate. The default is true, but may be disabled by setting this value to false. You
may wish to set this to false while debugging Open for Edit or View programs.
MX_CHARSET is set to enable multiple double-byte languages through the same
ENOVIA Live Collaboration instance on a server machine with an English O/S.
When needed, set to UTF8. At this time, if you want to run two or more languages
other than English concurrently you need to run an on an English O/S. (Other
language O/S’s can run English and that language.) For applications that display
Japanese characters with a WebLogic server, set this to either MS932 for Windows
applications or csWindows31j for UNIX applications.
MX_CHECK_DUPLICATE_NAMES may be set to false to prevent ENOVIA Live
Collaboration from checking all vaults for name collisions, which will improve
performance. Even when set to false, objects of the same type, name, and revision
may not exist within the same vault. Default is true, preventing duplicate names
throughout all vaults. This setting should not be changed if your company does not
use auto naming techniques for all objects that have a name uniqueness requirement.
Turning off name uniqueness checking allows objects to be migrated to ENOVIA
Live Collaboration via a change vault command when an Adaplet is in migrate mode.
Changing to false may also be advantageous in an exchange environment, such as
Sourcing Central, where each Company is assigned their own vault. If applications try
to create objects with duplicate type, name, and revision and this setting is true, an
Oracle constraint violation error occurs instead of the ENOVIA Live Collaboration
error.
MX_JAVA_DEBUG when set to true allows the thick client to attach to a
JPDA-enabled Java IDE, such as NetBeans or Eclipse. When true, this sets
JAVAC_FLAGS=G, which will compile Java classes with debug information. When
true, the libjdwp.so file needs to be in the path specified in the library path variable for
the specific platform, as given below:
Chapter 9: Configuring ENOVIA Live Collaboration
255
Solaris - LD_LIBRARY_PATH
AIX - LIBPATH
Windows - PATH
For example, on Solaris: LD_LIBRARY_PATH=/usr/lib/lwp;/usr/java/lib/sparc.
MX_JAVAC_FLAGS allows the passing of extra flags to the Java compiler. For
example, when set to “G”, Java classes are compiled with debug information.
MX_JAVA_OPTIONS sets Java options for desktop use of JPOs. For example:
MX_JAVA_OPTIONS="-Xss512k [-Xmso768k (IBM JDK on AIX)]
-Xmx256m -Xms256m -XX:NewSize=128m -XX:MaxNewSize=128m
-XX:MaxPermSize=128m -XX:SurvivorRatio=3"
When the ENOVIA Live Collaboration Server is installed, recommended Java options
are set by default. Refer to JVM Options for details.
MX_JIT_TRIGGER_MACROS should be set to true if you want environment
variables looked up dynamically (Just In Time) as needed in triggers. The default is
false, which means that macros are static, defined before any trigger program is
executed, and the same values are passed into all trigger types (check override action).
Refer to the Macros appendix in the Application Development Guide for more
information.
MX_NESTED_TRIGGER_MACROS is set to true to enable programs to save their
local RPE settings (that is, trigger macros) when they start, and restore them when
they exit. The default is false in order to leave user-defined RPE variable definitions
alone, and thereby minimizing the impact on legacy programs.
MX_NESTED_TRIGGER_MACROS is intended to be used in concert with the
environment variable MX_JIT_TRIGGER_MACRO; for optimum performance of
trigger programs, both values must be set to true. The ENOVIA Live Collaboration
trigger manager relies on the true setting to dramatically improve application
performance.
MX_DECIMAL_SYMBOL is used to set the user’s preference for displaying the
decimal symbol. For example, with the database configured with a “.” decimal
character and the user’s MX_DECIMAL_SYMBOL set to “,”, ENOVIA Live
Collaboration will always display numbers to that user with a comma and always
write them to the database with a period, regardless of how the user enters the number.
The same is true for the reverse; if the database is set to a comma and the user’s
preference is set to a period, numbers are displayed with a period but saved with a
comma. The default value is a period (.). For more information, refer to Localized
Decimal Character Settings in Chapter 20. Setup for supporting the viewing of
multiple languages and cultural symbol conventions is also discussed in Configuring
Oracle for Non-English Languages in Chapter 3.
MX_TCL_ANSI_NUMERIC may be set to true on desktop systems only when
ENOVIA Live Collaboration should override the LC_NUMERIC setting during
execution of Tcl programs to establish a period (.) as the decimal setting. This causes
operating system utilities to return floating point values in a form that is suitable for
performing arithmetic using the Tcl “expr” procedure. Values obtained from
ENOVIA Live Collaboration MQL commands will continue to be returned using the
character defined as MX_DECIMAL_SYMBOL. If set to false, (the default) the
setting for LC_NUMERIC is used and Tcl calls to the operating system will return
floating point values according to this setting.
256
ENOVIA Live Collaboration Installation Guide
This setting is designed for use in a thick client tcl environment only. Do not use this
setting in the Live Collaboration server environment, as it changes the process locale
across all threads.
For more information, refer to Localized Decimal Character Settings in Chapter 20.
Set up for supporting the viewing of multiple languages and cultural symbol
conventions is also discussed in Configuring Oracle for Non-English Languages in
Chapter 3.
MX_TCL_STRIP_NEWLINE allows the user to change the default behavior for
MQL commands issued from within Tcl. By default, output requested from MQL
does not have a carriage return at the end of the output string. Setting this variable to
false adds a carriage return at the end of the output for MQL commands called from
Tcl mode only. The default setting is true, which means that a new line is not
generated.
MX_TCL_SHLIB is set to reflect the tcl path and library file name (without the
extension), when a non default tcl version is used. For example, for Windows:
MX_TCL_SHLIB=ENOVIA_INSTALL\intel_a\code\bin\tcl85
For UNIX: MX_TCL_SHLIB=ENOVIAHOME/<platform>/code/bin/tcl85
When setting this variable, you must also reset the TCL_LIBRARY and
TK_LIBRARY settings to reflect the path to the new library versions.
MX_EXPAND_ALL when set to true, displays checked in files beneath formats
when the Formats browser is displayed. If many files are typically checked in, this
may be set to false to improve performance. The default is true.
MX_EDITOR code can be entered into the Code tab of the program object using the
ENOVIA Live Collaboration user interface, or it can be written in an external editor
and automatically imported into the program object. The button text is the value of
MX_EDITOR.
MX_EDITOR=Notepad
MX_EDITOR_PATH the external editor button is included on the Code tab only
when the MX_EDITOR and MX_EDITOR_PATH variables are set in the ENOVIA
Live Collaboration initialization (.ini) file.
MX_EDITOR_PATH=c:\winnt\system32\notepad.exe
When specifying WordPad, use wordpad.exe instead of write.exe.
MX_FCS_ENABLED when set to TRUE enables the Studio Customization Toolkit
to use FCS for checkin/checkout without using Matrix Web Navigator. When set to
FALSE, the FCS is not used by the Studio Customization Toolkit without Matrix Web
Navigator.
MX_FULL_TEXT_LIMIT sets the limit on the number of files to find in a full text
search. This value is passed to the index server and used by the search engine. The
default is 0 or no limit.
MX_FULL_TEXT_MODE sets the search mode of full text search. This value is
passed to the index server and used by the search engine.
MX_FULL_TEXT_MINSCORE sets the minscore for full text search. This value is
passed to the index server and is used by the search engine.
Chapter 9: Configuring ENOVIA Live Collaboration
257
MX_ALIASNAME_PREFERENCE determines the alias to use. An alias refers to
the different names that can be given to the same administrative objects according to
the audience. These are defined via MQL. This setting must match the alias name.
The alias preference takes precedence over the language preference if both are
specified. Refer to the MQL Guide for information on defining aliases.
MX_LANGUAGE_PREFERENCE determines the language to use. A language
applies to all words presented to the user through a GUI: buttons, labels, messages,
etc. It will also refer to an alternate language for schema, if an alias of this name
exists. Schema aliases are defined via MQL. Refer to the MQL Guide for more
information.
MX_LCD_EXTERNAL_AUTHENTICATION when set to true, tells ENOVIA
Live Collaboration not to attempt to verify the user’s password before accessing
objects in a remote vault. The default is false, which enables a more secure
environment.
MX_PROGRAM_POOL_SIZE sets the initial size of the interpreter pool used by
Tcl programs. This setting is also used to extend the pool size when all the interpreters
in the pool are allocated and another is requested. The default is 10.
MX_NFS_MAX_DATA specifies the amount of data transferred in one packet on the
network. The default value is set at 1024 on PC’s, 8192 on UNIX. These numbers
reflect the differences in the TCP/IP products for each platform. If you have a network
interface that supports large datagrams, you can achieve modest performance
improvements on PCs by increasing this value up to a maximum of 8192. In the
majority of installations, there is little or no benefit in altering this value.
MX_NFS_UID is used to change the user ID setting. The default is 100. This setting
applies to PCs only.
MX_NFS_GID is used to change the group ID setting. The default is 99. This setting
applies to PCs only.
MX_QUERY_PAGE_SIZE may be set to enable system-wide streaming of queries
and expands and sets the number of objects per page of returned items. The data is
returned when the first page is available, resulting in improvement in performance
and potentially in memory consumption as well.
Streaming can be enabled for all queries and expands through this environment
variable, through classes in the Studio Customization Toolkit, or at runtime by using
the size clause in MQL temporary query or expand business object commands. Some
operations, such as expression evaluation operations, use the expand operation
internally and the only way to enable streaming for these operations is though this
environment variable. You can override any value set for streaming in temporary
queries and expands by using the size clause. Enabling streaming through the Java
classes usually provides the greatest improvement in performance and memory
consumption. See “Streaming Query and Expand” in the Application Development
Guide.
When processing selectables in a streaming query, memory consumption is not
necessarily reduced versus not using streaming. Although paging is used when the
selectables are processed, the entire result set is still buffered in memory. For
example:
temp query bus T N R size 1000 select to.from;
This retrieves business objects 1000 at a time, and only 1000 will ever be held in
memory at one time. However, the evaluation of to.from for ALL of the found objects
will be held in memory until the query has completed.
258
ENOVIA Live Collaboration Installation Guide
MX_REMOTE_TIMEOUT defines the length of time, in seconds, that ENOVIA
Live Collaboration will persist in attempting to perform a file operation (e.g., checkin,
checkout, delete) in an NFS store. The default is 60 seconds. The code performs the
check every 5 seconds.
MX_RESTORE_CONTEXT is used to disable the security mechanism that ensures
that if context is changed during program execution, it is restored to the original
setting when finished. The default is true, which enables the security mechanism, but
may be set to false if required.
MX_RESTORE_TRIGGERS defaults to false. However, when set to true,
whenever a program is finished executing, ENOVIA Live Collaboration will set
triggers on. This provides protection in case of failure in a program that turns triggers
off before terminating.
MX_RESTRICT_EXPAND by default is set to true. If users attempt a full expand
on an object in an indented browser (shift+click with no filters on to or from) an error
message is generated. This is because full expands in both directions are extremely
time consuming, and it will often seem as if the system has stopped responding.
However, full expands may be enabled and the error suppressed by setting this
variable to false.
MX_SESSION_SILENT_TIMEOUT sets the time interval in minutes for allowed
inactivity for a session of Matrix Navigator or Business Modeler, before the
connection to the database is terminated. Once the user begins to work again, the
system will reconnect and attempt to continue from where it left off, without requiring
reauthentication. The default setting is 30 with a minimum setting of 5. If an invalid
value is specified (such as 3 or a negative number), the minimum will be enforced.
MX_SESSION_TIMEOUT sets the time interval in minutes for allowed inactivity
for a session of Matrix Navigator or Business Modeler, before the connection to the
database is terminated, and the user is forced to login again to resume Matrix
operations. Once reconnected, the system will attempt to continue from where it left
off. The minimum setting is 5. If an invalid value is specified (such as 3 or a negative
number), the minimum will be enforced. If not set, no session time out is place.
Timeout settings may be used alone or together, and are not used in MQL, System or
Matrix operating in MQL or Wizard mode. In Web Navigator and other ENOVIA
environments, session timeouts are handled by application server settings.
MX_SERVER_DST is used to tell ENOVIA Live Collaboration to override its
current algorithm for converting times to GMT. You should set this value to true if
you are using GMT or a GMT offset value in your server’s timezone setting, and your
Oracle server takes DST into account when determining the current time. Set this to
false for those rare Oracle servers that do not take DST into account. When this
setting is not in place at all, ENOVIA Live Collaboration will use the default
algorithm that uses the timezone setting in the ENOVIA Live Collaboration database
to determine whether or not the times provided by the Oracle server take DST into
account.
MX_SET_SORT_KEY sets any number of basic select items (type, name, revision,
owner, locker, originated, modified, current, and policy) by which objects in sets will
be presented. By default the value is type|name|revision. You can specify
ascending or descending order by prefixing the select with + or - (ascending (+) is the
default.) To disable sorting, you can set this variable to a single '|' character. Disabling
sorting improves response time of loading the first page of a set. Can be disabled in
conjunction with programming techniques to improve performance. Refer to the
Programming Guide for more information.
Chapter 9: Configuring ENOVIA Live Collaboration
259
MX_SHOW_HIDDEN_TYPE_OBJECTS sets the behavior preference for the
display of objects and connections whose business type or relationship is marked
hidden. The default is FALSE, which means that hidden objects and connections are
not displayed in query or expand results in the ENOVIA Live Collaboration or Web
Navigator, and are not returned by Studio Customization Toolkit query/expand
methods. When set to TRUE, objects with hidden business types and connections of
hidden relationships are displayed when found or navigated to, and they are returned
by the original Studio Customization Toolkit query/expand methods. Additional
expand methods are also available to override this system setting and retrieve all
objects/relationships, including those whose type is marked hidden. In MQL,
regardless of this setting, hidden type objects and connections are always listed.
MX_SMTP_HOST must be specified on each client (UNIX or PC), including the
Live Collaboration server, in order to send e-mail via ENOVIA Live Collaboration
from all machines. The named host must be setup as an SMTP server (not POP). This
setting is important for use with the ENOVIA Business Process Services and other
ENOVIA products, in order for business process notifications to be sent.
MX_SMTP_TIMEOUT sets the time allowed for connecting to the SMTP server
when sending e-mail. The default is 60 seconds.
MX_CHECK_MAIL specifies (for Matrix Navigator only) how often Matrix
Navigator checks for new IconMail in order to effect the new mail indicator. The
value is in minutes, and defaults to every 15 minutes. You can set the value to 0 to
disable the new mail indicator for Matrix Navigator users, as well as to disable the
sending of IconMail. When disabled, mail sent via Matrix Navigator, MQL, Web
Navigator, Studio Customization Toolkit IconMail, or other ENOVIA products will
be sent as email to those recipients with email enabled, but NO IconMail will be
created, sent, or stored in the database.
MX_SMTP_CONTINUE is used to tell ENOVIA Live Collaboration how to
establish communication with the SMTP server. The default is true, which means
ENOVIA Live Collaboration checks for a continuation character, “-”, in the current
line, allowing multiline messages. If set to false, no check for a continuation character
is done, which means that the current line is assumed to be the only line in the
message.
MX_TRACE_FILE_PATH is the location of the ENOVIA Live Collaboration error
log file. If this variable is not set, the default location is the ENOVIAHOME
directory.
MX_TRIGGER_RECURSION_DETECTION is used to specify the type of test
the system should employ to check for recursion of trigger programs. Most recursion
is not a single program calling itself (indirectly through triggers firing) but more of a
ping pong effect where a program calls another program, which calls back to the
original eventually (again, through the firing of triggers). The default is “name”,
which means that the system does not allow a program to be executed if it is already
executing. The variable may also be set to “signature”, which checks for the
uniqueness of five properties of the program: Program Name, Input arguments,
Trigger event, Trigger type, and Target object ID; or “none” to turn off detection
altogether. You must use “signature” when configuring for use with ENOVIA
products.
This setting is used in conjunction with MX_TRIGGER_RECURSION_LIMIT.
MX_TRIGGER_RECURSION_LIMIT is set to an integer to indicate the
maximum number of trigger programs that can be placed on the trigger stack, helping
to avoid server crashes due to the host system running out of stack space. The default
value is 30. When the limit is reached, a warning is added to the trigger trace file, and
260
ENOVIA Live Collaboration Installation Guide
the trigger stack is unwound. The limit is used in conjunction with
MX_TRIGGER_RECURSION_DETECTION, no matter what its value is, but it is
particularly important to set an appropriate limit for your server when trigger
recursion is disabled with the “none” setting.
MX_USE_SCHEMA_NAMES when set to true, improves performance when
multiple Live Collaboration servers are defined that point to different schemas in the
same Oracle Instance (that is, different Oracle Users.) Default is false.
MX_WHERE_MAX_COUNT controls how complex a where clause can be. This
setting approximately corresponds to the number of operands allowed in any where
clause. ENOVIA Live Collaboration produces an error if it reaches the limit specified.
The default is 512, which shouldn’t need changing in a server environment, since it is
comparable to the stack size used by the server's JVM. However, when using the
Studio Modeling Platform to run JPOs, which use the default JVM setting for stack
size, you may want to lower the value of MX_WHERE_MAX_COUNT (to
correspond with the JVM size) if very complex where clauses are used on the Studio
Modeling Platform system.
MX_WIN_APP_WAIT controls how long the Studio Modeling Platform waits for
the launched application’s primary window to appear. The value assigned is the
number of seconds to wait. The default value is zero.
MX_WIN_MIN_ON_LAUNCH is used to minimize all Studio Modeling Platform
windows during the execution of a launched application. The default is false. When
set to true, the Studio Modeling Platform windows are minimized, and when the
launched application terminates, the Studio Modeling Platform windows are restored.
MX_LEGACY_RELRULE=FALSE to revert to pre V6R2009 rule behavior on
relationships, set to true.
Windows Desktop File Associations
You can specify how Studio Modeling Platform Windows clients should open edit or open
view a file. In the absence of a format program, the Studio Modeling Platform will read
the enovia.ini file for the following settings. Then, if nothing is in the ini file, Windows file
associations are used. This is not supported on UNIX.
Depending on the action—edit, view or print—the Studio Modeling Platform looks in the
[EditExtensions], [ViewExtensions], or [PrintExtensions] section for
a line that starts with the extension of the file that the client is respectively editing,
viewing, or printing. For example, if a Windows client were to open edit a file called
changes.txt, and the Studio Modeling Platform had the following enovia.ini setting:
[EditExtensions]
txt=notepad.exe ^.txt
The Studio Modeling Platform would try to launch “notepad.exe” as the command line to
the open edit function. Everything after the ^character is ignored.
Dynamically
Updated Variables
The following variables may be set in the Session>Preferences menu of Matrix Navigator,
as well as by manually editing the [matrix] section of the .ini file. Any changes made
during a Navigator session (with the preferences option) will be reflected in these settings.
Any changes made to session preferences with Matrix Web Navigator are reflected in the
matrix.properties file for the Web client machine.
Chapter 9: Configuring ENOVIA Live Collaboration
261
BROWSEBY may be set to Icons or Details, and indicates what mode the Matrix
browser uses when first displayed. The default is Icons.
CHECKINAPPEND is a toggle switch for the checkin options, append or replace.
The default is false, which means that existing files are replaced by newly checked-in
files.
CHECKINCONFIRM is a toggle switch for the appearance of a confirmation
window when the replace button is selected on checkin. The default is false, meaning
that no warning is presented.
CHECKINDELETE is a toggle switch for the checkin option, delete files after
checkin. The default is false.
CHECKINUNLOCK tells Matrix if objects should be unlocked after files are
checked into it. The default is false.
CHECKOUTCONFIRM is a toggle switch for the appearance of a warning screen
when a checkout would overwrite a file with the same name. The default is false,
which means the warning does not appear.
CHECKOUTLOCK tells Matrix if objects should be locked after files are checked
out of it. The default is false.
CHECKOUTOVERWRITE is a toggle switch for the checkout option overwrite
existing files. The default is false.
CONNECTBAR is a toggle switch for displaying the relationship listbox in a
Navigator browser for use with the drop connect feature. The default is false.
DROPRELATION specifies the relationship to use for the drop connect feature. It
may be set to any valid relationship name.
FILEPATH is the default path for both checkin and checkout. The default is the path
defined as HOME in the ini file.
FILTERBAR may be displayed or not based on this setting. The default is true.
NAVIGATEBY may be set to Star, Indented, or Details, and indicates what mode the
Navigator browser uses when displayed. The default is Star.
OPEN sets the behavior of the double-click action on an object. The default is Edit
and can alternatively be set to View.
ROLEBAR may be displayed or not based on this setting. The role bar let the user
use visuals for one of the roles that they are assigned. The default is true, which
displays the role bar.
REVISIONWARN is a toggle switch for the appearance of a notification of a later
revision. The default is true, which means the warning appears when an object for
which there is a higher revision is opened or printed, or a checkin or checkout is
attempted.
VIEWBY sets the appearance of objects in Matrix, with Icon being the default. Other
options are Image or Name.
Application Sections
Sections for each Studio Modeling Platform application are added to the enovia.ini file
whenever one of the Studio Modeling Platform programs (except MQL) are closed. When
Matrix Web Navigator is used, they are saved in the matrix.properties file. The settings
indicate the geometry of all windows that were displayed in the session. For example:
262
ENOVIA Live Collaboration Installation Guide
[MatrixApplication]
SplashDialog=576,432,352,296
MainApplicationDialog=949,895,210,97
ContextDialog=680,288,300,368
FindObjectsDialog=900,693,234,198
AttributesDialog=800,260,282,362
The numbers indicate the width, height, and x and y coordinates respectively. In this way,
any resizing or replacing is “remembered” by ENOVIA Live Collaboration, so that
adjustments need not be made for every session. However, even if no resizing or
replacement is done, all windows (with the exception of the SplashWindow), will
“cascade” down and to the right each time they are opened, adding 10 to the X coordinate
and 20 to the Y coordinate. The last-used coordinates are then saved to the .ini file and
incremented for the next display.
If a user uses both Matrix Navigator and Matrix Web Navigator, these settings are not
persistent between the two.
Configuring Help
Administrators may configure the options available under the Help menu by setting
several environment variables in the .ini file. In this way, administrators may add their own
help files, providing the ability to deliver pertinent information specific to their
implementation to users. Refer to Installing the Documentation in Chapter 11 for more
information.
Font and Color
Variables
When color and font choices are not entered in the .ini file (or set as environment variables
on the command line), ENOVIA Live Collaboration uses the operating system settings for
fonts and colors. Since O/S settings tend to be optimum, it may be best not to set any of
these environment variables.
If different colors or fonts are desired, the variables listed below may be used to override
the system settings. This is helpful, for example, to differentiate two databases. The list of
color options on Windows is contained in
ENOVIA_INSTALL\studio\intel_a\code\lib\rgb.txt.
Font variables
Foreground variables
Background variables
font
foreground
background
dialogfont
dialogforeground
dialogbackground
menubarfont
menubarforeground
menubarbackground
iconbarfont
iconbarforeground
iconbarbackground
labelfont
labelforeground
labelbackground
fieldfont
fieldforeground
fieldbackground
buttonfont
buttonforeground
buttonbackground
browserfont
browserforeground
browserbackground
Chapter 9: Configuring ENOVIA Live Collaboration
263
Font variables
Foreground variables
Background variables
browserlinecolor
browserhighlightforeground
browserhighlightbackground
For example:
browserfont=times-bold-14
browserbackground=yellow
LDAP Variables
264
You integrate ENOVIA Live Collaboration with an LDAP server by setting environment
variables. Refer to Integrating with LDAP and External Authentication Tools in
Chapter 13 for more information.
ENOVIA Live Collaboration Installation Guide
Configuring Date and Time Formats
ENOVIA Live Collaboration uses dates and times in a variety of places: history, originated
and modified Basic values, for scheduling and tracking actual dates of state changes, and
as date attributes. The display, as well as the required entry elements, of dates and times
may be configured. This lets two users have different presentations of the same date and
time value. In addition, users see all dates and times in their own local time zone.
Internally, dates and times are stored in Greenwich Mean Time (GMT) independently of
the display format selected. Then, when dates are displayed, a runtime conversion is
performed so users see all date and time information in their own local time zone. For
example, assume a company has users in San Jose, Boston, and Bonn. A user in San Jose
promotes an object on December 11, 1998, 4:45 pm pacific time. Clients in Boston will
read the Actual Date in eastern time (December 11, 1998, 7:45 pm) and clients in Bonn
will read it in German local time (December 12, 1998, 1:45 am). This is assuming that
each location logs onto a local database server with a correctly-configured time zone
setting. Refer to the System Manager Guide for information on creating servers and
establishing a time zone.
Matrix provides six different variables that define formats for the display and entry of
dates and times. The six formats with their meanings and default settings are described
below:.
Variable (format)
Meaning/Usage
Default Tokens
MX_NORMAL_DATETIME_FORMAT
Normal (long) date/time. Used for displaying all
dates. Also, the system first attempts to parse
entered dates using this pattern.
+day mon dom+, +yr4
h12:min:sec +mer +tz
MX_NORMAL_DATE_FORMAT
Normal (long) date only. Used for displaying
date-only entries, like date attributes.
+day mon dom+, +yr4
MX_NORMAL_TIME_FORMAT
Normal (long) time only. Currently not used.
h12:min:sec +mer +tz
MX_TERSE_DATETIME_FORMAT
Terse (short) date/time. Provides additional format
for date/time input.
moy/dom-/-yr2
h12:min-:-sec +mer
MX_TERSE_DATE_FORMAT
Terse (short) date only. Provides additional format
for date input.
moy/dom-/-yr2
MX_TERSE_TIME_FORMAT
Terse (short) time only. Currently not used.
hr12:min-:-sec +mer
Note that “day”, “yr4”, “mer” and “tz” by default are normally displayed in date/time strings, but are not required input when
entering a date (as denoted by the “+” preceding these tokens). Also, “yr2” and “sec” are required as input in the terse
formats, but are not displayed in corresponding formatted strings.
These formats are used for both displaying dates in Studio Modeling Platform applications
and Matrix Web Navigator and for parsing dates input to the system. (These formats do
not affect the format of displayed dates/times in ENOVIA products.) The “normal”
formats are used for displaying and/or entering dates and times, while the “terse” formats
may optionally be used for input. In other words, when a date/time is entered, the system
Chapter 9: Configuring ENOVIA Live Collaboration
265
attempts to parse it with the “normal” format first. If that doesn’t work, the system tries the
“terse” format.
When using ENOVIA products, the normal and terse datetime formats are set in the
MatrixIniDefaults program, which is installed with the framework. These settings must be
in sync with properties in emxSystem.properties. Do not adjust these settings in the
server's .ini file because they will override the setting in the MatrixIniDefaults program.
For more information about configuring date/time formats for ENOVIA products, refer to
the “Setting Date Management Properties” section of the ENOVIA Live Collaboration
Administrator's Guide.
Date formats may be made up of any combination of the following tokens:
266
Token
Meaning
day
day of the week (mon, tue, wed,...)
DAY
day of the week, not abbreviated
mon
month (jan, feb, mar,...)
MON
month, not abbreviated
tz
time zone (edt, cdt, pdt,...)
TZ
time zone, not abbreviated
mer
time meridian (am, pm, or blank for 24 hour time)
sec
seconds, 0 - 59
min
minutes, 0 - 59
h12
hour in 12 hour format, “mer” will be non-blank
H12
hour in 12 hour format, “mer” will be non-blank. Always outputs 2
digits, for example, 05.
h24
hour in 24 hour format, “mer” will be blank
H24
hour in 24 hour format, “mer” will be blank. Always outputs 2 digits,
for example, 05.
yr2
abbreviated year (98, 99, 00...)
yr4
full year (1998, 1999, 2000..)
dom
day of month (1, 2, 3,..., 31)
DOM
day of month (1, 2, 3,..., 31). Always outputs 2 digits, for example, 04.
doy
day of year (1, 2, 3,..., 365)
ENOVIA Live Collaboration Installation Guide
Token
Meaning
DOY
day of year (1, 2, 3,..., 365). Always outputs 3 digits, for example,
January 3 would be 003.
moy
month of year (1, 2, 3,..., 12)
MOY
month of year (1, 2, 3,..., 12). Always outputs 2 digits, for example,
04.
To configure date/time formats
1. Write out a format that includes all the tokens from the table above that you would
want to include in display or input of dates and times. Include any embedded
punctuation (spaces, commas, colons, etc.). For example:
day, dom/mon/yr4
might translate to:
Monday, 4/Jan/2000
By default, each token is both displayed and required as input to the date/time parser.
2. In front of each token and punctuation mark that is not required by the input
processor, add a plus symbol (‘+’). This signifies that the specified field is displayed
in formatted output, but does not have to be input by a user when entering a date/time.
For example:
+day+, dom/mon/yr4
means that 4/Jan/2000 is acceptable input but this date would be displayed as
Monday, 4/Jan/2000.
3. In front of each token that is not desired in the display of dates and times, add a
hyphen (minus symbol, “-’). This signifies that the specified field is not displayed in
formatted date/time strings, but is required to be input by the user when specifying a
date/time field. For example:
+day+, -dom-/mon/yr4
means that 4/Jan/2000 could be entered, but this date would be displayed as Monday,
Jan/2000.
If you wish to use a hyphen as a separator for date fields (for example, to display
something like 2000-11-22), on Windows, use two hyphens:
yr4--moy--dom
For use in the mql shell script, the setting requires the use of 3 hyphens. For example:
MX_TERSE_DATETIME_FORMAT="yr4---moy---dom h24:min-:-sec"
export MX_TERSE_DATETIME_FORMAT
MX_NORMAL_DATETIME_FORMAT="yr4--moy--dom h24:min-:-sec"
export MX_NORMAL_DATETIME_FORMAT
4. Add the appropriate lines to the configuration vehicle (ini file, startup script, or
MatrixIniDefaults program). Any variables not set will use the default values as
shown in the table above. For example, you may want to add the following lines:
Chapter 9: Configuring ENOVIA Live Collaboration
267
MX_NORMAL_DATETIME_FORMAT= +day+, MON dom, yr4
h24:min:sec TZ
MX_TERSE_DATETIME_FORMAT = moy/dom/yr4
These settings allow the date to be entered in either of the following ways:
January 4, 2000 or 1/4/2000
Note that the TIME elements of a DATETIME default to 12:00 AM, if not entered. Also
note that currently, the TIME only formats are not used by ENOVIA Live Collaboration.
Date Attributes
with Ranges
All dates, including date attributes, are displayed in the format specified in the
MX_NORMAL_DATETIME_FORMAT variable. Because of this, if date attributes with range
values are used, EVERY user must use the same setting for this variable. Otherwise, when
a user creates a business object of the Type that has a date attribute with a default range
specified in a different format, the default value for that date cannot be displayed for your
business object, and so ENOVIA Live Collaboration cannot load attributes during the
creation, and you will receive the following error message:
Date format for the DateAttribute is invalid. The correct
format is: [Gives your formats].
The same is true if you just try to bring up attributes of an object that has the date attribute
set in a different format than that specified in the local .ini file. It may be easiest to use the
default setting for these variables, when date attributes with ranges will be used.
Dates in Web
Applications
The Live Collaboration server gets its time zone in the same manner as other ENOVIA
Live Collaboration clients and passes time information to a Web client in the time zone it
knows about. This means that dates and times displayed on Web clients (including Matrix
Web Navigator users and users of other programs that connect via the Live Collaboration
server) will be in the time zone available to the Live Collaboration server, and not
necessarily in the time zone of the Web client. For example, if a user in California
connects to a Live Collaboration server in Connecticut that uses eastern time, times
displayed for that user will be in eastern time. Also, if the California user creates objects,
the create time will be stored in the database based on the eastern time converted to GMT.
Summary
So, in summary, all dates in ENOVIA Live Collaboration:
268
•
Are stored in the database in Greenwich Mean Time (GMT);
•
When displayed, are converted at runtime to the user’s local time zone as specified in
the ENOVIA Live Collaboration Server Object to which they are logged on, or by the
client machine’s operating system (in a non-distributed environment);
•
Are displayed with the tokens specified in the MX_NORMAL date variables for Studio
Modeling Platform and Web Navigator. Display of dates in ENOVIA products are
determined by the browser language setting and by properties in
emxSystem.properties. The NORMAL and TERSE formats must still be defined
when running ENOVIA products but they are specified in the MatrixIniDefaults
program instead of the ini file.
•
May be entered in the format specified in either the TERSE or the NORMAL format
variables.
ENOVIA Live Collaboration Installation Guide
•
If range values for date attributes are used, all users must use the same settings for
MX_NORMAL_DATETIME_FORMAT and the attribute range values must adhere
to this specification.
•
Web applications display dates in the time zone that is known to the Live
Collaboration server, not necessarily the time zone of the Web client.
For information on setting time zones in ENOVIA Live Collaboration, and other date/time
issues, refer to the System Manager Guide.
Chapter 9: Configuring ENOVIA Live Collaboration
269
Localizing ENOVIA Live Collaboration
Language support is outlined in Language Support in Chapter 2. UTF8 configuration for
the application servers is mostly done by default with a few steps requiring that they be
done manually, as described in UTF-8 Settings in Chapter 8. This section describes how
each layer of the stack is translated.
The table below shows the files used to localize each part of ENOVIA Live Collaboration:
Studio
Modeling
Platform
Web Navigator
Other ENOVIA products
User Interface
menus, dialogs,
tips
matrix.txt, matrix.vr
Java class files that
get compiled with
Matrix Web
Navigator (no
changes in field)
emxAPPNAMEStringResource_LANG.properties
emxComponentsStringResource_LANG.properties
Java class files that get compiled with applets (such
as checkin applet, Gantt Chart applet, etc.) (no
changes in field)
Schema objects
Language Aliases
Language Aliases
emxFrameworkStringResource_LANG.properties
Lower level
schema objects
(policy states,
attribute ranges)
one language only
(administration
definition)
one language only
(administration
definition)
emxFrameworkStringResource_LANG.properties
Error messages
from the Live
Collaboration
Server
matrix.txt, matrix.vr
(file on the client)
matrix.txt,
matrix.vr (file on
the server)
matrix.txt, matrix.vr (file on the server)
APPNAME is the name of the application; LANG is the 2-digit ISO code.
ENOVIA products default to English if the translated string cannot be found. This can
occur for several reasons. The most obvious is when the Web browser is configured for a
language that is not provided. Also, MQL keywords are not localizable, and so these are
always shown in English. In some cases, most strings appear localized, with a few
showing up in English. This will occur when text is added late in the software release
cycle, and you can assume that they will be updated in a future release. However, in other
cases, the English word is preferred by the ENOVIA translation reviewer, and so will
remain untranslated. If this is the case, and you have another preference for the string, you
can modify the provided file(s). The one exception to this is for Web Navigator. The
localization is handled by Java files that must be compiled with the source code.
Note that the database and Application servers must be correctly configured to handle
UTF8 encoding.
270
ENOVIA Live Collaboration Installation Guide
Filenames
In a UTF8 environment, strings are not processed in the kernel. The Live Collaboration
Server just passes them to the database as received. However, one exception is for file
checkin through the server using the workspace directory (standard checkin, not FCS).
ENOVIA Live Collaboration hashes file names on checkout in the workspace directory,
but does not hash file names on checkin. So, an English server configured for UTF8 treats
a UTF8 encoded file with double-byte characters in the name being checked in as
consisting of extended ASCII characters and succeeds in creating a file in the workspace
directory. But the database expects UTF8 bytes and so produces an error on checkin.
However, the sequence of bytes in the file name are the same on the native and English
operating systems. Also, the file content is encoded correctly.
The workaround is to use FCS for all file checkins through a Live Collaboration server.
Studio Modeling
Platform
The Studio Modeling Platform may be used in alternative languages for menus and
messages. The software is shipped with a language file, an ASCII file which enables you
to alter or translate the names of various menus, dialog boxes, and error messages. This
file, called matrix.txt, is located in the ETC directory under the $MATRIXINSTALL/
<platform>/ directory and contains all messages used by the Matrix Navigator,
Business Modeler, and System Manager applications.
Changes to matrix.txt are for the Studio Modeling Platform only and do not affect
PowerWeb.
To translate schema definitions for the Studio Modeling Platform, you may use language
aliases, as described in the MQL Guide.
Localization files are provided already translated to various languages in the appropriate
directory beneath the ETC directory. For example, the $MATRIXINSTALL/
<platform>/etc/japanese directory contains both a matrix.txt and a
matrix.vr file for the Kanji language. By moving the .vr file to $MATRIXHOME, the
software is displayed in the new language.
The $MATRIXINSTALL and $MATRIXHOME directories could be different.
Of course, the language’s operating system and character set must also be loaded for
proper display. In addition, Oracle has localization requirements, as outlined in Chapter 3,
Installing an Oracle Database.
If refinements to the translated text are required, the matrix.txt file may be edited and a
new .vr file created as described in the System Manager Guide.
Software programs run via the ENOVIA Live Collaboration Server receive error messages
and strings in the language known to the Server. If no .vr file is available to the server, that
language is English. Note that a server may be configured with no more than 1 .vr file.
Tcl with Asian characters
Tcl 8.5.7 is the default configuration and is required for use in Asian languages. Refer to
Tcl Support for details.
Chapter 9: Configuring ENOVIA Live Collaboration
271
ENOVIA
applications
ENOVIA applications use resource files to display translated pages. These files are
installed in the ematrix/properties directory on the server.
Each application relies on 3 base files, which are always in English:
•
emxFrameworkStringResource.properties
•
emxComponentsStringResource.properties
•
emxAPPLICATION_NAMEStringResource.properties (For example, Engineering
Central uses emxEngineeringCentralStringResource.properties)
When these files are translated, the translators work with the files in their native encoding,
so that all special characters are displayed correctly. However, in order for the Java-based
Live Collaboration server to present the strings correctly, the files must be encoded in
ASCII, and the filename must include the standard abbreviation for the language (as
defined by ISO-639). This is true for all non-English languages, both double-byte and
latin-based. For each translated file, ENOVIA provides both the native and the ASCII
version, easily identified by the filename. For example, the files provided by BPS for use
in German are:
•
emxTeamCentralStringResource_de.properties
•
emxFrameworkStringResource_de.properties
•
emxComponentsStringResource_de.properties
•
emxMetricsStringResource_de.properties
•
emxTeamCentralStringResource_deNative.properties
•
emxFrameworkStringResource_deNative.properties
•
emxComponentsStringResource_deNative.properties
•
emxMetricsStringResource_deNative.properties
You only need the Native files if you want to make modifications to the out of the box
translations. When you are done with the changes, you will need to run the native files
through the native2ascii converter provided with the JDK. Refer to JDK documentation or
the ENOVIA Live Collaboration Administrator’s Guide for more information.
ENOVIA products receive error messages and strings in the language known to the
ENOVIA Live Collaboration Server. If no .vr file is available to the server, that language is
English. Note that a server may be configured with no more than 1 .vr file.
JavaScript Errors
JavaScript messages that are part of the error checking of the JSP or JPO are translated as
part of emxFrameworkStringResource.properties files. However, if the error condition is
not expected by the code, the error comes from the JDK itself. This means that the error is
displayed in the language of the operating system.
Application Applets
The applications may provide some functionality, such as checkin and Gantt charting, via
applets. Applet translations come from within the .cab or .jar file, and therefore they may
not be modified in the field.
272
ENOVIA Live Collaboration Installation Guide
Web Navigator
The “Start Matrix”pages provide access to Matrix Web Navigator, and can be configured
as required by adding parameters to the page. The Language parameter controls which
Java resource bundle translation is used to display the menus, windows, and errors of the
applet. It is also used to display schema definitions in another language, if the setting
matches a defined language alias. The provided pages use the following syntax:
props.put("PARAMNAME", "VALUE");
If you will use custom applets, your pages may use one of the following:
<PARAM name="NAME" value="VALUE">
document.writeln("<param name='NAME' value='VALUE'>");
This setting overrides the language set in the client’s native locale. For example, when
using the following on the Web Navigator start page:
props.put("Language", "fr");
the applet’s windows are displayed in French, and the fr aliases for administrative objects
are displayed for all clients. The Language parameter (and defined alias) must be a valid
ISO Language Code. These codes are the lower-case two-letter codes as defined by
ISO-639. You can find a full list of these codes at a number of sites, such as:
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
Valid values are: en (for English), fr (for French), de (for German), it (for Italian), ja
(for Japanese), tw (for traditional Chinese), cn (for simplified Chinese) and ko (for
Korean). These abbreviations must be lowercase. Java translations are provided only for
the languages listed above.
Matrix Web Navigator receives error messages from the Live Collaboration Server in the
language known to thes erver. If no .vr file is available to the server, that language is
English. Note that a server may be configured with no more than 1 .vr file.
If you set the language parameter to an ISO value for which there is no java resource
bundle translation (such as sv for Swedish), Matrix Web Navigator will be displayed in
English, but the administrative objects will be displayed in the language specified,
assuming these aliases exist. Setting the language value to something other than an ISO
value is not supported through the server (such as if you have schema aliases for
manufacturing vs. engineering).
Chapter 9: Configuring ENOVIA Live Collaboration
273
274
ENOVIA Live Collaboration Installation Guide
10
Deploying J2EE
J2EE Deployment Overview
After you’ve installed and configured the ENOVIA Live Collaboration Server and all
ENOVIA products you will use, you then deploy the J2EE application by completing steps
4 through 6 of the General Installation for ENOVIA Live Collaboration Server:
•
First Modifying J2EE Settings
•
Then, Building the J2EE Archive File
•
and finally, Deploying the J2EE Archive File
ENOVIA Live Collaboration Server install descriptor files that are used to configure the
ENOVIA web application. You can make modifications to these files based on your
requirements. Also installed is the WAR Utility, which is used to create EAR (Enterprise
Archive) or WAR (Web Archive) files based on the configured descriptor files. The J2EE
archive file is then deployed by the application server.
ENOVIA Live Collaboration Servers are generally deployed with the WAR file, using the
application server’s administrative tools to complete the configuration. However, since the
EAR file contains all information needed for deployment (including the web application
name and context root) system administrators of an ENOVIA Live Collaboration Server
may deploy the EAR file instead, so that the context root is already configured. The
context root is the relative path to the server root for a particular web application; for
example, /ematrix.
275
Directory Structure
When you install Live Collaboration Server, the following directory structure is created:
Live Collaboration Server
Install Dir
| ...... distrib
|
| ...... ematrixwarutil
|
| ...... STAGING
The Live Collaboration Server installation directory (SERVER_INSTALL on Windows or
SERVERHOME on Unix) has the name you assigned during the installation. It contains
the following three subdirectories (as well as several others):
•
distrib—Built when you run the WAR Utility (from the ematrixwarutil directory), the
distrib directory contains the EAR and/or WAR files as well as the expanded contents
of the files.
•
ematrixwarutil—Built when you install the Live Collaboration Server, this directory
contains the WAR Utility, as well as the web.xml and ematrix.xml files you can use to
adjust your J2EE settings.
•
STAGING—Built when you install the Live Collaboration Server, and added to with
each ENOVIA product, this directory contains the files necessary to run the ENOVIA
products. These become part of the EAR and/or WAR files when the WAR Utility is
run.
Supporting HTTPS/SSL Deployment
The ENOVIA V6 architecture implies http (https) communications between the Live
Collaboration Server and any FCS, as well as between two FCSs.
Prerequisites
•
Java 1.5 and above is installed.
•
Java is added to the PATH variable.
•
The path <JAVA_HOME>/jre/lib/security/ is added to the
CLASSPATH variable.
•
The application server used is Apache Tomcat or WebLogic.
•
Apache Tomcat 6.0.16/6.0.18/6.0.20 or WebLogic is installed.
•
If Apache Tomcat is used, the environment variable CATALINA_HOME is set to
the appropriate Catalina Home directory.
To configure SSL with a Tomcat Server on Windows
1. Open a command prompt.
On certain operating systems, because of OS security, you must run the command prompt
as an Administrator. To do this, change to the <OS_install_drive>:/Windows/
system32/ folder, locate cmd.exe, right-click on cmd.exe, and then select Run as
Administrator.
2. Issue the following command to generate a certificate:
276
ENOVIA Live Collaboration Installation Guide
keytool -genkey -alias tomcat -keyalg RSA -validity 360 -dname
“CN=<SERVERNAME>,o=3DPLM,ou=Platform,1=Pune,s=MH,c=IN”
-keystore <CATALINA_HOME>\.keystore
The “keytool” executable is located in the <JAVA_HOME>\bin\ folder. If you
experience any issues, ensure that:
- JAVA_HOME is correctly set.
- JAVA is added to the PATH variable as mentioned in the Prerequisites section.
- Correct values are specified for the following:
• <SERVERNAME>—This is the full computer name of the machine on which the
application server is running.
• <CATALINA_HOME>—This is the application server (Apache
Tomcat) home folder.
3. When prompted, specify a password (for example, “v6r2011x”), and note it.
Keep the store password and the key password the same.
4. On successful execution of the above command, a file named .keystore is created in
the <CATALINA_HOME>\ directory.
Verify that the .keystore file has been created in the <CATALINA_HOME>\ directory.
5. Change to the <CATALINA_HOME>\conf\ folder. Open the server.xml file in a
text editor, and then search for the string scheme=”https”. Uncomment the
definition of the SSL connect on port 8443 that has “scheme=https” as an
attribute. Update the definition as follows:
<Connector protocol=”org.apache.coyote.http11.Http11Protocol”
port=”8443” minSpareThreads=”5” maxSpareThreads=”75”
enableLookups=”true” disableUploadTimeout=”true”
acceptCount=”100” maxThreads=”200 scheme=”https” secure=”true”
SSLEnabled=”true” sslProtocol=”TLS”
keystoreFile=”<CATALINA_HOME>\.keystore”
keystorePass=”v6r2011x” clientAuth=”false”/>
The value of keystorePass in the above descriptor should be the value for the
password specified in Step 3., above.
6. Run the Tomcat server.
7. Access the link https://<SERVERNAME>:8443/. If the setup is fine, then you should
be able to view the Tomcat home page.
In the above URL, <SERVERNAME> should be the full computer name of the machine on
which the application server is running.
Settings to be configured on the FCS server
If the FCS URL is the same as the MCS URL, then the following settings should be done
on the MCS server.
1. Start the instance of the application server in which the MCS application is deployed.
2. Note the path of JAVA_HOME to which the application server in which the FCS
application is deployed is referring.
Chapter 10: Deploying J2EE
277
3. Copy the following InstallCert.java program to the
<JAVA_HOME>\jre\lib\security\ folder:
/*
* Copyright 2006 Sun Microsystems, Inc. All Rights Reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
*
- Redistributions of source code must retain the above copyright
*
notice, this list of conditions and the following disclaimer.
*
*
- Redistributions in binary form must reproduce the above copyright
*
notice, this list of conditions and the following disclaimer in the
*
documentation and/or other materials provided with the distribution.
*
*
- Neither the name of Sun Microsystems nor the names of its
*
contributors may be used to endorse or promote products derived
*
from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
* IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
* PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
* EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
* PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
* PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
* LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
* NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
* SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
import java.io.*;
import java.net.URL;
import java.security.*;
import java.security.cert.*;
import javax.net.ssl.*;
public class InstallCert {
public static void main(String[] args) throws Exception {
String host;
int port;
char[] passphrase;
if ((args.length == 1) || (args.length == 2)) {
String[] c = args[0].split(":");
host = c[0];
port = (c.length == 1) ? 443 : Integer.parseInt(c[1]);
String p = (args.length == 1) ? "changeit" : args[1];
passphrase = p.toCharArray();
} else {
System.out.println("Usage: java InstallCert
<host>[:port] [passphrase]");
return;
}
278
ENOVIA Live Collaboration Installation Guide
File file = new File("jssecacerts");
if (file.isFile() == false) {
char SEP = File.separatorChar;
File dir = new File(System.getProperty("java.home") + SEP
+ "lib" + SEP + "security");
file = new File(dir, "jssecacerts");
if (file.isFile() == false) {
file = new File(dir, "cacerts");
}
}
System.out.println("Loading KeyStore " + file + "...");
InputStream in = new FileInputStream(file);
KeyStore ks =
KeyStore.getInstance(KeyStore.getDefaultType());
ks.load(in, passphrase);
in.close();
SSLContext context = SSLContext.getInstance("TLS");
TrustManagerFactory tmf =
TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultA
lgorithm());
tmf.init(ks);
X509TrustManager defaultTrustManager =
(X509TrustManager)tmf.getTrustManagers()[0];
SavingTrustManager tm = new
SavingTrustManager(defaultTrustManager);
context.init(null, new TrustManager[] {tm}, null);
SSLSocketFactory factory = context.getSocketFactory();
System.out.println("Opening connection to " + host + ":" +
port + "...");
SSLSocket socket = (SSLSocket)factory.createSocket(host,
port);
socket.setSoTimeout(10000);
try {
System.out.println("Starting SSL handshake...");
socket.startHandshake();
socket.close();
System.out.println();
System.out.println("No errors, certificate is already
trusted");
} catch (SSLException e) {
System.out.println();
e.printStackTrace(System.out);
}
X509Certificate[] chain = tm.chain;
if (chain == null) {
System.out.println("Could not obtain server certificate
chain");
Chapter 10: Deploying J2EE
279
return;
}
BufferedReader reader =
new BufferedReader(new InputStreamReader(System.in));
System.out.println();
System.out.println("Server sent " + chain.length + "
certificate(s):");
System.out.println();
MessageDigest sha1 = MessageDigest.getInstance("SHA1");
MessageDigest md5 = MessageDigest.getInstance("MD5");
for (int i = 0; i < chain.length; i++) {
X509Certificate cert = chain[i];
System.out.println
(" " + (i + 1) + " Subject " + cert.getSubjectDN());
System.out.println("
Issuer " + cert.getIssuerDN());
sha1.update(cert.getEncoded());
System.out.println("
sha1
" +
toHexString(sha1.digest()));
md5.update(cert.getEncoded());
System.out.println("
md5
" +
toHexString(md5.digest()));
System.out.println();
}
System.out.println("Enter certificate to add to trusted
keystore or 'q' to quit: [1]");
String line = reader.readLine().trim();
int k;
try {
k = (line.length() == 0) ? 0 : Integer.parseInt(line) 1;
} catch (NumberFormatException e) {
System.out.println("KeyStore not changed");
return;
}
X509Certificate cert = chain[k];
String alias = host + "-" + (k + 1);
ks.setCertificateEntry(alias, cert);
OutputStream out = new FileOutputStream("jssecacerts");
ks.store(out, passphrase);
out.close();
System.out.println();
System.out.println(cert);
System.out.println();
System.out.println
280
ENOVIA Live Collaboration Installation Guide
("Added certificate to keystore 'jssecacerts' using alias
'"
+ alias + "'");
}
private static final char[] HEXDIGITS =
"0123456789abcdef".toCharArray();
private static String toHexString(byte[] bytes) {
StringBuilder sb = new StringBuilder(bytes.length * 3);
for (int b : bytes) {
b &= 0xff;
sb.append(HEXDIGITS[b >> 4]);
sb.append(HEXDIGITS[b & 15]);
sb.append(' ');
}
return sb.toString();
}
private static class SavingTrustManager implements
X509TrustManager {
private final X509TrustManager tm;
private X509Certificate[] chain;
SavingTrustManager(X509TrustManager tm) {
this.tm = tm;
}
public X509Certificate[] getAcceptedIssuers() {
throw new UnsupportedOperationException();
}
public void checkClientTrusted(X509Certificate[] chain,
String authType)
throws CertificateException {
throw new UnsupportedOperationException();
}
public void checkServerTrusted(X509Certificate[] chain,
String authType)
throws CertificateException {
this.chain = chain;
tm.checkServerTrusted(chain, authType);
}
}
}
4. Open a command prompt.
Chapter 10: Deploying J2EE
281
On certain operating systems, because of OS security, you must run the command prompt
as an Administrator. To do this, change to the <OS_install_drive>:/Windows/
system32/ folder, locate cmd.exe, right-click on cmd.exe, and then select Run as
Administrator.
5. Change to the <JAVA_HOME>\jre\lib\security\ folder.
6. Run the following command:
> javac InstallCert.java
The “javac” executable is located in the <JAVA_HOME>\bin\ folder. If you experience
any issues, ensure that:
- JAVA_HOME is correctly set.
- JAVA is added to the PATH variable as mentioned in the Prerequisites section.
- Go to the <JAVA_HOME>\bin\ folder and execute the above command, specifying
the complete path of InstallCert.java (that is,
<JAVA_HOME>\jre\lib\security\InstallCert.java).
After successful execution of the above command, two files are created:
InstallCert.class and InstallCert$SavingTrustManager.class.
7. Ensure that the current directory is <JAVA_HOME>\jre\lib\security\, and
then run the following command:
> java InstallCert <SERVERNAME>:<HTTPS_PORT>
The “java” executable is located in the <JAVA_HOME>\bin\ folder. If you experience
any issues, ensure that:
- JAVA_HOME is correctly set.
- JAVA is added to the PATH variable as mentioned in the Prerequisites section.
- Go to the <JAVA_HOME>\bin\ folder and execute the above command, specifying
the
complete path of InstallCert.java (i.e., <JAVA_HOME>\jre\lib\security\InstallCert.java).
8. When prompted, add the certificate to the trusted keystore by pressing the Enter key.
The following message should be displayed:
“Added certificate to keystore 'jssecacerts' using alias <SERVERNAME>-1”
9. Run the command in Step 7. again:
> java InstallCert <SERVERNAME>:<HTTPS_PORT>
10. The following message should be displayed:
“No errors, certificate is already trusted.”
To import certificates served by the Live Collaboration Server as trusted
To fully support https/SSL deployment, the certificates served by the Live Collaboration
Server must be imported as trusted certificates in each J2EE-deployed ENOVIA V6 server
(CSR/FCS/SyncServer). This should be done using the keytool program found in the JRE
of your J2EE server. The syntax is as follows:
> keytool -importcert -trustcacerts -keystore
<JREE_SERVER_JRE_PATH>\lib\security\cacerts
282
ENOVIA Live Collaboration Installation Guide
Modifying J2EE Settings
Before you run the WAR Utility, you can modify Web.xml or ematrix.xml to configure the
web environment for your J2EE web application. For example, you can modify web.xml
to add a servlet or any framework properties.
When modifying web.xml or ematrix.xml, it is important that you use the .xml file
contained in the ematrixwarutil directory. Also keep in mind that other copies of the
files may be overwritten by the WAR Utility.
Web.xml
The Live Collaboration Server installations include both the framework.properties file that
has always been used to configure ENOVIA products, and the web.xml file used in more
recent J2EE implementations. The web.xml file tells the server to look to the installation
directory for framework.properties, but it can itself include the very same property settings
as parameters. In order to remove the dependency of the J2EE archive files on this external
file, you should add all settings to web.xml instead of framework.properties. If a property
is set in both framework.properties and web.xml, the value in web.xml is used. Refer to
Framework.properties for more information on its default settings.
As installed with the Live Collaboration Server, the web.xml file is configured for use with
ENOVIA products and contains the properties and values shown below. Additional
parameters may be added. Each of these properties, along with parameters that can be
added to the file, are described in the following sections.
This is not the complete web.xml file — only the parameter and servlet definitions are
shown.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web
Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app id="WebApp_1">
<display-name>ematrix</display-name>
<context-param id="ContextParam_1">
<param-name>properties</param-name>
<param-value>@installDir@/managed/properties/
framework.properties</param-value>
</context-param>
<context-param id="ContextParam_2">
<param-name>ematrix.server.host</param-name>
<param-value></param-value>
</context-param>
<context-param id="ContextParam_3">
<param-name>ematrix.login.page</param-name>
<param-value>/emxLogin.jsp</param-value>
</context-param>
<context-param id="ContextParam_4">
<param-name>ematrix.login.failure.page</param-name>
<param-value>/emxLogin.jsp</param-value>
</context-param>
Chapter 10: Deploying J2EE
283
<context-param id="ContextParam_5">
<param-name>ematrix.web.app</param-name>
<param-value>true</param-value>
</context-param>
<context-param id="ContextParam_6">
<param-name>emxLogin.FormAction</param-name>
<param-value>/@webAppName@/servlet/login</param-value>
</context-param>
<context-param id="ContextParam_7">
<param-name>emxLogin.FrameworkTarget</param-name>
<param-value>common/emxNavigator.jsp</param-value>
</context-param>
<context-param id="ContextParam_8">
<param-name>ematrix.page.path</param-name>
<param-value>/@webAppName@</param-value>
</context-param>
<context-param id="ContextParam_9">
<param-name>ematrix.home.page</param-name>
<param-value>/common/emxNavigator.jsp</param-value>
</context-param>
<context-param id="ContextParam_10">
<param-name>ematrix.load.program</param-name>
<param-value>eServiceListSchemaNames.tcl</param-value>
</context-param>
<context-param id="ContextParam_11">
<param-name>ematrix.encoding</param-name>
<param-value>UTF8</param-value>
</context-param>
<context-param id="ContextParam_12">
<param-name>ematrix.audit.log</param-name>
<param-value>true</param-value>
</context-param>
<!-- legacy servlet properties
<context-param id="ContextParam_13">
<param-name>ematrix.servlet.ui</param-name>
<param-value>true</param-value>
</context-param>
<context-param id="ContextParam_15">
<param-name>ematrix.timer.agent</param-name>
<param-value></param-value>
</context-param>
<context-param id="ContextParam_16">
<param-name>ematrix.timer.agent.key</param-name>
<param-value></param-value>
</context-param>
<context-param id="ContextParam_17">
<param-name>ematrix.timer.interval</param-name>
<param-value>21600</param-value>
</context-param>
284
ENOVIA Live Collaboration Installation Guide
<context-param id="ContextParam_18">
<param-name>ematrix.timer.command</param-name>
<param-value>execute program emxProjectSpace -method
performTaskEscalation</param-value>
--><!-- Define our servlets -->
<servlet id="Servlet_1">
<servlet-name>Framework</servlet-name>
<servlet-class>com.matrixone.servlet.Framework</
servlet-class>
<load-on-startup>1</load-on-startup>
</servlet>
<servlet id="Servlet_2">
<servlet-name>LogoutServlet</servlet-name>
<servlet-class>com.matrixone.servlet.LogoutServlet</
servlet-class>
</servlet>
<servlet id="Servlet_4">
<servlet-name>MatrixXMLServlet</servlet-name>
<servlet-class>com.matrixone.servlet.MatrixXMLServlet</
servlet-class>
</servlet>
<servlet id="Servlet_7">
<servlet-name>MatrixExchangeServlet</servlet-name>
<servlet-class>com.matrixone.servlet.MatrixExchangeServlet</
servlet-class>
</servlet>
<servlet id="Servlet_12">
<servlet-name>LoginServlet</servlet-name>
<servlet-class>com.matrixone.servlet.LoginServlet</
servlet-class>
</servlet>
<servlet id="Servlet_15">
<servlet-name>FrameworkServlet</servlet-name>
<servlet-class>com.matrixone.servlet.FrameworkServlet</
servlet-class>
</servlet>
<servlet id="Servlet_17">
<servlet-name>WorkspaceServlet</servlet-name>
<servlet-class>com.matrixone.servlet.WorkspaceServlet</
servlet-class>
</servlet>
<servlet id="Servlet_18">
<servlet-name>fcs</servlet-name>
<servlet-class>com.matrixone.fcs.fcs.FcsServlet</
servlet-class>
Chapter 10: Deploying J2EE
285
</servlet>
<servlet id="Servlet_19">
<servlet-name>audit</servlet-name>
<servlet-class>com.matrixone.servlet.AuditServlet</
servlet-class>
<load-on-startup>2</load-on-startup>
</servlet>
This section describes the properties you can define in web.xml. When adding properties
or servlets, be sure that each has a unique id. For example, servlet id=“Servlet_20” or
context-param id= “ContextParam_30”
enovia.ini Directory Parameter
enovia.inidir specifies the directory that holds the enovia.ini file for the Live
Collaboration Server. For example:
<context-param id="ContextParam_#">
<param-name>enovia.inidir</param-name>
<param-value>c:\enovia</param-value>
</context-param>
For details on setting the directory of the ini file, see Setting the Location of the enovia.ini
File on Windows.
Connection Parameters
ematrix.server.host specifies the name and port # of the machine where the Live
Collaboration Server is running. For example:
<context-param id="ContextParam_#">
<param-name>ematrix.server.host</param-name>
<param-value>//MYHOST:1099</param-value>
</context-param>
ematrix.proxy.server can be added to specify the URL for the proxy server, including the
host name for the server, port, and directory. For example, the parameter could be:
<context-param id="ContextParam_#">
<param-name>ematrix.proxy.server</param-name>
<param-value>http://proxyserv:8088/teamcentral</
param-value>
</context-param>
When a proxy server is used, the URL for accessing an ENOVIA product contains the
value for the enovia.proxy.server property instead of the host name and port for the Web
server. For example, suppose the URL for accessing ENOVIA products without the proxy
server is:
http://webserv:7001/enovia/emxLogin.jsp
If the enovia.proxy.server property is set using the example shown above, the URL for
accessing the application with the proxy server would be:
http://proxyserv:8088/engineeringcentral/enovia/emxLogin.jsp
286
ENOVIA Live Collaboration Installation Guide
Specifying Pages to Use
Several parameters define specific pages within the application: the login page, logout
page, home page, and login failure page. There are two main uses for these parameters:
•
If a servlet calls one of these four pages, it will forward to the page specified in the
corresponding property. For example, the LoginServlet automatically forwards users
who are not logged in to the page specified in the ematrix.login.page property.
•
You can reference these pages using methods in the servlet classes. For example, the
FrameworkServlet has getHomePage, getLoginPage, getLogoutPage, and
getLoginFailurePage methods that retrieve the pages defined in these parameters.
Similarly, the LoginServlet has redirectToHomePage, redirectToLoginPage, and
redirectToLoginFailurePage methods that redirect to these pages.
ematrix.login.page Specifies the login page. If a servlet requires the user to be logged in
and they haven’t yet been authenticated, the page specified in this property is presented.
When installed, the property is set to the ENOVIA product login page:
<context-param id="ContextParam_#">
<param-name>ematrix.login.page</param-name>
<param-value>/emxLogin.jsp</param-value>
</context-param>
ematrix.home.page Specifies the page to present after the user has logged in if no target
“next” page is specified in the JSP. When installed, the property is set to the Applet page.
<context-param id="ContextParam_#">
<param-name>ematrix.home.page</param-name>
<param-value>/common/emxNavigator.jsp</param-value>
</context-param>
ematrix.logout.page Specifies the page to display when the user logs out. ENOVIA
products don’t use this property but a custom application could. For example:
<context-param id="ContextParam_#">
<param-name>ematrix.logout.page</param-name>
<param-value>/emxLogout.jsp</param-value>
</context-param>
ematrix.login.failure.page Defines the URL for the page to present if the login has failed.
If no failure page is specified, sessions that fail to login are forwarded to the home page.
ENOVIA products don’t use this property but a custom application could.
Authentication Parameters
When external authentication is set up for use with ENOVIA products, the standard login
and logout pages, emxLogin.jsp and emxLogout.jsp, are by-passed. Use one of the
following properties to define the alternative login/logout page.
<context-param id="ContextParam_#">
<param-name>ematrix.sso.logout.url</param-name>
<param-value>URL_FOR_NEW_LOGOUT_PAGE</param-value>
</context-param>
OR
<context-param id="ContextParam_#">
<param-name>ematrix.sso.absolute.logout.url</param-name>
<param-value>URL_FOR_NEW_LOGOUT_PAGE</param-value>
Chapter 10: Deploying J2EE
287
</context-param>
Use the first property to specify a relative path to the URL, use the second to specify an
absolute path. Only enter a value for one of these properties. If you enter a value for
ematrix.sso.logout.url, that value is used. The ematrix.sso.absolute.logout.url property is
only used if the first property is not set.
For more information on using external authentication with ENOVIA products, see
Chapter 13, Integrating with LDAP and External Authentication Tools as well as the
ENOVIA Live Collaboration Administrator’s Guide.
To use SSO with Tomcat
In order to make SSO work properly with the way the Apache/Tomcat server handles
iconmail attachments and page history, use the following setting in the web.xml file:
<context-param id="ContextParam_#">
<param-name>ematrix.server.domain</param-name>
<param-value>DOMAIN_NAME</param-value>
</context-param>
This setting is required only for the Tomcat/SSO environment.
To use SSO with ClearTrust
When using Cleartrust SSO, add the following parameter to web.xml:
<context-param id="ContextParam_#">
<param-name>ematrix.server.mcs.host</param-name>
<param-value>http://PROXY_SERVER_URL</param-value>
</context-param>
For example:
<context-param id="ContextParam_22">
<param-name>ematrix.server.mcs.host</param-name>
<param-value>http://cleartrust.3ds.net:8002</param-value>
</context-param>
FCS Parameters
To view and download .doc, .docx, .xls, .xlsx, .ppt, and .pptx files using
Internet Explorer (IE)
When you view a .doc, .docx, .xls, .xlsx, .ppt, and .pptx file using the View icon in IE, the
file is opened inside the browser window. If this window remains open, you will not be
able to view or download any other files because IE will bring you back to the window that
is already open. This is a limitation in IE and the work-around is to change the mime type
field in the web.xml file for each file type. For example, for .xls files, change:
<mime-mapping id="MimeMapping_2">
<extension>xls</extension>
<mime-type>application/vnd.ms-excel</mime-type>
</mime-mapping>
To:
<mime-mapping id="MimeMapping_2">
<extension>xls</extension>
<mime-type>application/octet-stream</mime-type>
</mime-mapping>
288
ENOVIA Live Collaboration Installation Guide
To configure ticket and receipt FCS settings
This section describes FCS settings in the web.xml file that allow you to configure ticket
and receipt cleanup and ticket expiration. Values are based on your usage patterns. If
required, you can also change the URL used for communication between FCS and the
MCS, and you can enable FCS to operate in two different domains with SSO.
To set expiration for a ticket
To set how long a ticket is valid (i.e. the length of time between when a ticket is issued and
when it reaches the FCS server), add the following setting on your FCS server:
<context-param id="ContextParam_19">
<param-name>ematrix.max_ticket_age</param-name>
<param-value>600</param-value>
</context-param>
For ticket expiration time-stamping, the receiver has the actual clock value of the sender.
Prior to evaluating the validity of the ticket, the time-stamp on the receiver’s end is
adjusted to the sender’s time, thus making time-stamping impervious to differences in time
zones between a receiver and sender.
Default is 600 seconds (10 minutes). You should increase this time only if your network is
very slow.
To set cleanup for tickets
To set the number of tickets to process on your FCS server before deleting tickets from
RAM:
<context-param id="ContextParam_19">
<param-name>ematrix.ticket_cleanup_count</param-name>
<param-value>1000</param-value>
</context-param>
Default is 1000. If your server is not very busy (e.g. processing approximately 100
documents per/hour), you might decrease this number.
To set cleanup for receipts
To set the number of receipts to process on your MCS before deleting receipts from RAM:
<context-param id="ContextParam_19">
<param-name>ematrix.receipt_cleanup_count</param-name>
<param-value>1000</param-value>
</context-param>
Default is 1000. If your server is not very busy (e.g. approximately 100 documents per/
hour), you might decrease this number.
To change the URL for the MCS
MCS uses its own URL (which is used to request the JSP page producing the ticket) to
compute the connect string for an FCS to communicate with the MCS. To change the URL
for the MCS, for example, when an FCS needs to communicate with the MCS on a
different port or with a different protocol (https vs. http):
<context-param id="ContextParam_19">
Chapter 10: Deploying J2EE
289
<param-name>ematrix.mcs.contextConnect</param-name>
<param-value>URL</param-value>
</context-param>
This URL value overrides the MCS URL.
To enable FCS in two different domains with SSO
The following setting allows a cookie to be sent containing the login credential between
two different domains in an FCS environment using SSO:
<context-param id="ContextParam_19">
<param-name>ematrix.mcs.packageCookies</param-name>
<param-value>TRUE</param-value>
</context-param>
To configure image caching
The following parameters can be set to configure use of image caching in ENOVIA
products.
ematrix.maxImageCookieLength can be added to increase the total allowable cookie
size, setting the threshold for when the system must use the MCS for delivering images
instead of the faster FCS. For example, the parameter could be:
<context-param id="ContextParam_#">
<param-name>ematrix.maxImageCookieLength</param-name>
<param-value>1960</param-value>
</context-param>
BACKGROUND: The image URL encodes various information about the image,
including any cookies that were presented by the browser to the MCS. If the session
cookie-string is too large, the resulting image URL exceeds the maximum URL length
supported by the browser (2048 byte limit on Internet Explorer). This is most likely to
occur when a configuration involves many cookies for the session (SSO, web server
proxies, etc.). If the total length of the cookie string exceeds this property value, ENOVIA
Live Collaboration will generate a URL that is addressed to the MCS for image delivery
(omitting the cookies) rather than generate an image URL that exceeds 2048 bytes.
You can increase the total allowable cookie size by adding this setting to web.xml on the
MCS server. By default the maximum cookie length is 1960. With this setting in place, the
system will send the image request to the MCS if the total length of all cookies is larger
than1960. The default should be fine in most circumstances, but you may want to increase
it if you are in an environment that may have many cookies and Mozilla is the browser
standard.
ematrix.isContentDispositionEnabledForImages can be added for WebLogic
implementations to allow image files to be saved in the browser. For example, the
parameter could be:
<context-param id="ContextParam_#">
<param-name>ematrix.isContentDispositionEnabledForImages</
param-name>
<param-value>True</param-value>
</context-param>
BACKGROUND: By default, the image service sets both Cache-Control and
Content-Disposition in its headers. The Cache-Control header is set to allow the browser
to cache the image. The Context-Disposition header is set to allow the browser to save the
image with the file name of the original file. WebLogic considers it an error to set both
headers. Setting ematrix.isContentDispositionEnabledForImages to false on the FCS
290
ENOVIA Live Collaboration Installation Guide
server suppresses the setting of the Content-Disposition header, which means that image
files that are saved will be named “DynamicImage”.
Timer Servlet
The Timer servlet allows a command to be executed at a specified interval. It uses the
following properties in the web.xml file:
ematrix.timer.agent The user name for the context that executes the command. User
privileges can be handled internally in the program.
ematrix.timer.agent.keyThe password for the user. User privileges can be handled
internally in the program.
ematrix.timer.interval The elapsed time, in seconds, between execution of the
command.
ematrix.timer.command The command to run. If you are using BPS, use the
command shown in the example below.
By default, the above parameters are commented-out in the web.xml file. To use one or
more of the properties, you must un-comment them before you run the WAR Utility. The
following is an example of the properties with sample values:
<context-param id="ContextParam_15">
<param-name>ematrix.timer.agent</param-name>
<param-value></param-value>
</context-param>
<context-param id="ContextParam_16">
<param-name>ematrix.timer.agent.key</param-name>
<param-value></param-value>
</context-param>
<context-param id="ContextParam_17">
<param-name>ematrix.timer.interval</param-name>
<param-value>21600</param-value>
</context-param>
<context-param id="ContextParam_18">
<param-name>ematrix.timer.command</param-name>
<param-value>execute program emxProjectSpace -method
performTaskEscalation</param-value>
</context-param>
To configure static browser content cache
Web pages typically reference a lot of fairly static content files such as images and
Javascripts, which change infrequently if ever. Web browsers are able to cache such static
content, but they conservatively keep going back to the server to check whether their
cached copy of the content is still valid. They do this by sending requests with the
If-Modified-Since: header. If the resource has been modified since it was last
transferred, it is transferred again, otherwise the browser uses the cached copy that it has.
This protocol saves having to transfer content that has not changed, but it still involves a
round trip to the server. Across a high-latency network, all these round trips to the server
result in significant degradation in user interface responsiveness.
These round trip requests can be reduced or eliminated by setting an expiration time on
content sent by the server. The server does this by adding the header Expires: or
Cache-Control: to the response. Both tell the browser that it may cache and not
Chapter 10: Deploying J2EE
291
re-check the validity of the content for a specific amount of time. When the cached content
expires, the browser once again sends an If-Modified-Since: request, receives a
new expiration time, and the cycle repeats.
The following example is the configuration provided out of the box to cache specified
static browser content for a period of 7 days. The browser will cache and not re-check the
validity of the content for a 7days.
The following example is the configuration provided out of the box to cache specified
static browser content for a period of 7 days. The browser will cache and not re-check the
validity of the content for a 7days.
<filter>
<filter-name>StaticContentCaching</filter-name>
<filter-class>com.matrixone.servlet.StaticContentCaching</filter-class>
<init-param>
<param-name>ematrix.cache-control.ResourceLifetime</param-name>
<param-value>7d</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>StaticContentCaching</filter-name>
<url-pattern>*.html</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>StaticContentCaching</filter-name>
<url-pattern>*.js</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>StaticContentCaching</filter-name>
<url-pattern>*.css</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>StaticContentCaching</filter-name>
<url-pattern>*.xsl</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>StaticContentCaching</filter-name>
<url-pattern>*.gif</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>StaticContentCaching</filter-name>
<url-pattern>*.jpg</url-pattern>
</filter-mapping>
You can modify, add, and remove filter-mapping entries in this configuration. Each entry
enables the cache control for a specific file type.
ematrix.cache-control.ResourceLifetime sets the amount of time to cache static browser
content in the configuration. For example, the parameter could be:
<init-param>
<param-name>ematrix.cache-control.ResourceLifetime</param-name>
<param-value>7d</param-value>
</init-param>
292
ENOVIA Live Collaboration Installation Guide
The default is 7d. Select a number followed by a single character, s (seconds), m
(minutes), h (hours), or d (days). A value of zero turns off the filter and no cache control is
enabled. A value of 0s means expire immediatly or after zero seconds.
Wizard Parameters
Use these parameters when running wizards using the Wizard servlet. (In the future, they
may also be used to run Forms using a servlet.)
ematrix.frame.font.width Controls the width of text field widgets in wizards by
determining the number of columns wide each widget will be. The parameter accepts any
integer and the default value is 9. The number of columns is determined by dividing the
number of pixels specified for the width of each widget (in the wizard definition) by the
number entered for this parameter. For example, suppose a widget is defined with a pixel
width of 100 and the default value of 9 is used for the font.width parameter. 100 divided
by 9 is 11, so the widget would be 11 columns wide.
<context-param id="ContextParam_#">
<param-name>ematrix.frame.font.width</param-name>
<param-value>9</param-value>
</context-param>
ematrix.frame.font.height Works the same way as the font.width parameter except this
parameter controls the height of widgets and affects multiline text fields and listboxes. The
default value is 16.
<context-param id="ContextParam_#">
<param-name>ematrix.frame.font.height</param-name>
<param-value>16</param-value>
</context-param>
ematrix.frame.warn.unsupported When set to true, the Wizard servlet displays a
warning when a wizard uses an unsupported command, such as an MQL dialog scripting
command. When set to false, the default, the Wizard servlet ignores unsupported
commands and gives no feedback.
<context-param id="ContextParam_#">
<param-name>ematrix.frame.warn.unsupported</param-name>
<param-value>false</param-value>
</context-param>
Western European languages
If you are having problems with displaying accent marks in any ENOVIA product, add the
following to web.xml in the properties section:
<context-param id="ContextParam_#">
<param-name>com.matrixone.servlet.MimeType1</
param-name>
<param-value>txt,text/plain; charset=UTF-8</
param-value>
</context-param>
Chapter 10: Deploying J2EE
293
Language Parameter
ematrix.encoding This parameter specifies the character set encoding and should be set to
UTF-8.
<context-param id="ContextParam_#">
<param-name>ematrix.encoding</param-name>
<param-value>UTF-8</param-value>
</context-param>
</context-param>
ematrix.xml
When you run the WAR Utility, by default a SERVER_INSTALL\distrib\ directory
is created on the server that contains the following:
Ear
Ear
War
War
file
directory
file
directory
However, most configurations do not require all four artifacts. The ematrix.xml file is used
by the WAR Utility as the ANT build script and can be configured to indicate what will be
needed. Three properties control what is needed:
<property name="createstaticzip" value="true"/>
<property name="createearfile" value="true"/>
<property name="staticcontentinwar" value="true"/>
These properties can be set to either “true” or “false” (case sensitive). If removed or
commented out, the value is false.
Using a Web server in addition to an application server
Many enterprise environments use a WWW server fronting the application server. This is
the default topology in WebSphere. In this environment, ideally the WWW server should
handle all of the static content and the WAR file shouldn't even contain the static content.
You can remove the “staticcontentinwar” property (setting to false does not disable it),
keeping “createstaticzip” set to true, and the static content will be separated from the WAR
file. You will also need to update your application server setting for file serving prior to
running the WAR Utility.
To move static content out of the war file
1. In ematrix.xml remove, comment out, or set to “false”, the staticcontentinwar
property. For example:
<!-- <property name="staticcontentinwar" value="true"/> -->
2. Disable file serving in the application server. For WebSphere, this is disabled in
ibm-web-ext.xmi by resetting:
fileServingEnabled="true"
to:
fileServingEnabled="false"
This change affects what is placed in plugin-cfg.xml, which governs which requests
the WWW server handles and which ones the application server handles.
3. Run the WAR Utility, as described in Building the J2EE Archive File.
294
ENOVIA Live Collaboration Installation Guide
Application servers using the ENOVIA Live Collaboration
Server without a Web server
If you are not using a WWW server to front your application server, there is no need to
create a static zip file or an ear file. You can remove the properties “createstaticzip” and
“createearfile” from ematrix.xml to create only a war directory (and a war file). This will
reduce the time to run the WAR Utility and the disk space used.
To create a war file only
1. Remove or comment out the properties “createstaticzip” and “createearfile” from
ematrix.xml. For example:
<!-- <property name="createstaticzip" value="true"/> -->
<!-- <property name="createearfile" value="true"/> -->
2. Run the WAR Utility, as described in Building the J2EE Archive File. You will be
prompted for the context root.
Framework.properties
By default, the framework.properties file includes only the following entries, to be used
for program debugging:
#
#
#
#
ematrix.origin.trace=false
ematrix.debug=false
ematrix.ftp.debug=false
ematrix.fcs.debug=false
Servlet definitions have been removed from this file and are now defined in web.xml.
ematrix.origin.trace Set to true to trace all servlets, jsps, and JPOs executed on the server.
This enables tracing globally for all context objects created. Be sure the path to
framework.properties is in your classpath, (which should already be the case for the Live
Collaboration Server).
ematrix.debug Set to true to turn on debugging output from the ENOVIA Live
Collaboration servlets. The output will be written to a log file that captures stdout. The
default is false.
ematrix.ftp.debug Set to true to turn on debugging output from FTP. The output will be
written to the server’s stdout. The default is false.
ematrix.fcs.debug Set to true to turn on debugging output from FCS. The output will be
written to the server’s stdout. The default is false.
Application Server
Files
When the Live Collaboration Server is installed with WebLogic, the following lines are
added to weblogic.xml:
<jsp-descriptor>
<jsp-param>
<param-name>workingDir</param-name>
<param-value>WEBAPPNAME/generated</param-value>
</jsp-param>
</jsp-descriptor>
Chapter 10: Deploying J2EE
295
The workingDir parameter is the directory used to store compiled JSPs. This change
allows multiple webapps to be deployed and guarantee that name conflicts do not occur
between them.
Consult your application server’s documentation for other parameters that you may want
to change before running the WAR Utility.
296
ENOVIA Live Collaboration Installation Guide
Building the J2EE Archive File
This section describes how to run the WAR Utility on the UNIX, Linux, and Windows
platforms.
The WAR Utility may take several minutes to run, depending on your machine’s processor
and the size of the staging directory.
The dos window no longer appears during the WAR Utility run and remains hidden.
Running the WAR
Utility on UNIX or
Linux
If adding an application or re-running the WAR Utility for any reason, delete the contents
of the SERVERHOME/distrib/ directory before starting.
To run the WAR Utility for ENOVIA Live Collaboration Server installations on
UNIX or Linux
1. Stop the ENOVIA Live Collaboration Server processes.
2. Change directory to SERVERHOME/ematrixwarutil/.
3. Run ./war_setup.
4. Enter the SERVERHOME directory path. This is the path where you installed the
ENOVIA Live Collaboration Server.
5. Enter the name of your web application. This is the web application name known to
your J2EE server.
6. Enter the directory where the Java Development Kit is installed. You see a message
that the system is copying files. When finished, EAR and WAR files are created in the
distrib/ subdirectory of the SERVERHOME directory.
Running the WAR
utility on Windows
If you selected "J2EE (build EAR and WAR archives)" as the deployment option when
installing the ENOVIA Live Collaboration Server, the WAR utility is installed under the
SERVER_INSTALL\ematrixwarutil\ directory, and a Start ENOVIA Live
Collaboration WAR Utility shortcut is created in the Dassault Systemes Software
V6R2011x program folder on the Start menu to launch the WAR Utility script.
To run the ENOVIA Live Collaboration WAR utility
1. Select the Start ENOVIA Live Collaboration WAR Utility shortcut from the Start >
Programs menu.
Chapter 10: Deploying J2EE
297
An interactive console appears presenting three prompts, each with its own default
value. For example:
•
Enter Collaboration Server installation directory path
[C:\enoviaV6R2011x\server]?
•
Enter the name of your web application [enovia]?
•
Enter the directory where the Java Development Kit has been installed
[C:\Java\jdk1.6.0_19]?
2. To change any item, type the desired information at the respective prompt. To accept
the default value, simply press Enter without typing any letter.
The WAR Utility creates the EAR AND WAR files are created in the distrib\ subdirectory
of the SERVER_INSTALL directory.
298
ENOVIA Live Collaboration Installation Guide
Deploying the J2EE Archive File
After you run the WAR Utility to create the J2EE archive files, you use the J2EE
application server to deploy it.
Choose the deployment procedure below for your J2EE server and platform.
An application server can only deploy one ENOVIA .war file (ematrix.war for example).
You can install as many ENOVIA applications as you would like before you run the WAR
Utility to create the .war file. If you decide to install a second set of ENOVIA applications,
you cannot use this application server to deploy this second .war file. In order to deploy
this second .war file, you must install the ENOVIA Live Collaboration Server (with an
application server) again and use this second application server to deploy it. Other
non-ENOVIA .war files can be deployed by an application server that has already
deployed an ENOVIA .war file.
Deploying on
WebSphere
To deploy using WebSphere (UNIX and Windows)
1. Start your WebSphere server. For example:
../IBM/HTTPServer/bin/apachectl start
../IBM/WebSphere/AppServer/bin/startServer.sh server1
2. Start a browser and access http://SERVER_NAME:9060/ibm/console
Login so that the changes you make are attributed to you.
3. Expand Applications and click Install New Application.
If you have previously deployed the ENOVIA application and need to update it, click
Enterprise Applications and then click ematrix in the list of installed applications.
4. If your browser is on the server machine, select Local File System. Otherwise, select
Remote File System. Click the Browse button next to your selection and browse to
the path for your ear file. Select the ear file and click Open.
5. Once the page has updated select Show me all installation options and parameters
and click Next.
6. Continue clicking Next until you get to Step 2: Map modules to servers.
7. On Step 2, select the module (such as ematrix) and continue to click Next until you
reach Step 6: Map virtual hosts for Web Modules.
8. On Step 6, select the (such as ematrix) and continue to click Next until you reach the
summary page. Then click Finish.
9. When the process finishes, you see a message stating “Application ematrix installed
successfully.” For first time deployment click the Manage Applications link to
continue editing. If you are updating your deployment click “Save to Master
Configuration” link.
10. If not already on the page for Enterprise Applications > ematrix, click Enterprise
Applications and then click ematrix in the list of applications.
11. Scroll down and click on the Class Loading and update detection link under the
Detailed Properties section.
12. Scroll down to WAR Classloader Policy.
Chapter 10: Deploying J2EE
299
13. Select Class loader for each WAR file in application (if not already selected). Click
the Apply button.
14. When the next page is displayed, click the Save link at the top of the page and then
click the Save button.
15. Expand Servers then click on Web Server. Select your web server and click on
Propagate Plug-in. This will generate the plugin-cfg.xml file and the new web
application description will be part of the file.
16. For first time deployment, start the application by clicking Enterprise Applications,
selecting the checkbox in front of ematrix, and clicking the Start button.
17. If using Matrix Web Navigator, open the httpd.conf file in IBMHttpServer/
conf and comment out the following lines, as shown below:
#AfpaEnable
#AfpaCache on
#AfpaLogFile "C:\IBMHttpServer/logs/afpalog" V-ECLF
18. Move static pages to the web server by copying the WEBAPPNAME_static.zip file
from the SERVERHOME/distrib/ directory to the doc root of your web server.
For example: ematrix_static.zip
19. Unzip WEBAPPNAME_static.zip in the doc root. The /ematrix directory is
created.
20. Add an entry for the new directories in plugin-cfg.xml in
WEBSPHEREHOME\AppServer\config\cells\ . For example:
<default_host_server1_host_Cluster_URIs">
<Uri Name="/ematrix/*/*.jsp"/>
<Uri Name="/ematrix/servlet/*"/>
<Uri Name="/ematrix/common/*"/>
<Uri Name="/ematrix/*"/>
Add this entry under <UriGroup Name=>.
21. Stop and restart the server.
Deploying on
WebLogic
To deploy using WebLogic (UNIX and Windows)
1. Start your WebLogic server.
2. Launch a supported browser and go to:
http://HOSTNAME:7001/console
3. Type your Username and Password, then click Log In.
4. On the main screen, click Configure applications under Information and
Resources.
5. If Install is grayed out, click Lock & Edit on the Summary of Deployments page.
6. Click Install under Deployments.
7. Navigate to the location of the EAR file. Select ematrix.ear and click Next.
8. Select Install this deployment as an application and click Next.
9. Click Next in the Optional Settings screen.
300
ENOVIA Live Collaboration Installation Guide
10. Select No, I will review the configuration later under Additional configuration,
then click Finish.
11. When you return to the Summary of Deployments, click Activate Changes.
12. Once the changes have been saved, select the checkbox for ematrix. Choose
Servicing all requests under Start, then click Yes to continue.
13. Logout of the WebLogic administration console.
Deploying on Sun
Java System
Application Server
The Sun Java System Application Server deployment is only for UNIX platform. On Sun
Java System Application Server, the enovia.war file is your web application’s war file.
If you re-deploy the enovia.war file, you should first remove the existing war file.
To deploy using Sun Java System Application Server (UNIX only)
1. Change the directory to /app/SUNWappserver7/bin.
2. Type asadmin.
3. Stop the server by typing stop-appserv.
4. Deploy the ear file by typing:
deploy --user admin_user --password admin_password /app/
RMI_INSTALL/distrib/ematrix.ear
5. Restart the Sun Java System Application Server server by typing
start-appserv.
To remove the enovia.war file
1. On the UNIX command line, type the following:
undeploy --user admin_user --password admin_password
WEB_APP_NAME
For example, the WEB_APP_NAME might be ematrix.
2. Stop and restart the Sun Java System Application Server.
Tips for using Sun Java System Application Server
Chapter 10: Deploying J2EE
•
The Sun Java System Application Server can be started and stopped using the
following commands:
start-appserv
stop-appserv
•
Log files are located in
/var/opt/SUNWappserver7/domains/domain1/server1/logs
and
/var/opt/SUNWappserver7/domains/domain1/admin-server/logs
•
To connect from a browser, use the following URL:
http://HOSTNAME:PORT/enovia/common/emxNavigator.jsp
301
Deploying on
Tomcat
Tomcat does not require a deployment process. Instead, you only need to copy the .war file
to the web application directory.
To deploy using Tomcat
•
Copy enovia.war from /SERVERHOME/distrib/ to
/app/<Jakarta-TomCat>/webapps/.
To startup/shutdown Tomcat
•
To startup Tomcat, use startup.sh, which is found in the /app/tomcat/bin
directory.
•
To shutdown Tomcat, use shutdown.sh, which is found in the /app/tomcat/
bin directory.
To view Tomcat log files
View the catalina.out file under /app/tomcat/logs.
To undeploy using Tomcat
To undeploy, you delete the web application directory (e.g., ematrix) found under the
/app/tomcat_install/webapps directory.
1. Stop Tomcat by using shutdown.sh.
2. Delete the web application directory under the /app/tomcat_install/
webapps directory. This is usually called ematrix.
302
ENOVIA Live Collaboration Installation Guide
Starting the ENOVIA Live Collaboration Server
When the Server is configured for RIP, just start the application server and ENOVIA Live
Collaboration is available as needed.
When the RMI daemon (standalone) or gateway is installed, use rmireg.bat on Windows
or rmireg.sh on UNIX to start the server. You can stop the server on UNIX by running
rmireg.sh -stop.
Note that before the ENOVIA Live Collaboration Server is started, you must start the
database, HTTP server, and application server.
Chapter 10: Deploying J2EE
303
304
ENOVIA Live Collaboration Installation Guide
11
Installing the
Documentation
ENOVIA Live Collaboration Documentation
The user’s guides for ENOVIA Live Collaboration are installed in PDF format and
delivered in the ENOVIALiveCollaborationDocumentation-VERSION zip file. The
administrator’s guides are delivered with the ENOVIA Studio Modeling Platform product
in the ENOVIAStudioModelingPlatformDocumentation-VERSION zip file. Both zip files
are delivered as a Windows distribution only and can be installed on a Windows machine
and then copied to a UNIX machine.
Installing the PDF
Files
The following guides are installed with each zip file:
ENOVIA Live Collaboration:
•
ENOVIA Live Collaboration Application Exchange Framework User’s Guide
•
ENOVIA Live Collaboration Business Metrics User’s Guide
•
ENOVIA Live Collaboration Common Components User’s Guide
•
ENOVIA Live Collaboration Matrix Navigator Guide
•
ENOVIA Live Collaboration Team User’s Guide
•
ENOVIA Live Collaboration Installation Guide
•
ENOVIA 3DVIA Viewer User’s Guide
305
ENOVIA Studio Modeling Platform:
•
ENOVIA Live Collaboration Administrator’s Guide
•
ENOVIA Live Collaboration Application Development Guide
•
ENOVIA Live Collaboration Installation Guide
•
ENOVIA Live Collaboration Matrix Navigator Guide
•
ENOVIA Live Collaboration Schema Reference Guide
•
ENOVIA Studio Modeling Platform Business Modeler Guide
•
ENOVIA Studio Modeling Platform MQL Guide
•
ENOVIA Studio Modeling Platform Programming Guide
•
ENOVIA Studio Modeling Platform System Manager Guide
To install the online help files on Windows
1. Log into Windows as a person with Administrator privileges.
2. Copy the .zip files from the CD or the ENOVIA Download page to a temporary
directory.
3. Unzip the first file and run setup.exe.
4. At the Welcome screen, click Next.
5. Enter a Destination Folder for the online help files. You can accept the default folder
or choose a different folder. The default folder for the Studio Modeling Platform
documentation is StudioModelingPlatformHelp. The default folder for the Live
Collaboration documentation is LiveCollaborationHelp. Click Next.
6. Choose a Program Folder. Click Next.
The online help files are installed.
7. Click Finish to exit setup.
8. If required, install the second zip file using the same procedure.
After you install the PDFs, you can choose to make them available online by manually
changing settings in the enovia.ini file for the Studio Modeling Platform. Refer to
Customizing Help for more information.
Uninstalling the
Online Help Files
The PDFs can be entirely removed by using the Add or Remove Programs option from the
Control Panel.
To uninstall online help files
1. From the Control Panel, navigate to the Add or Remove Programs option.
2. Locate the ENOVIA documentation you wish to uninstall and click Remove.
The documentation is uninstalled.
306
ENOVIA Live Collaboration Installation Guide
Customizing Help
Administrators may customize the options available under the Help menu of the thick
client applications by setting several environment variables in the enovia.ini file for the
Studio Modeling Platform (previously matrix.ini). These variables are grouped by their
usage. Application help variables specify what documents are to be available from each
application. Document help variables specify for each document what will appear in the
application’s Help menu, the name of the file to open, and optionally, what viewer
application to use to read the file. Administrators may also add their own help files,
providing pertinent information to users that is specific to their implementation.
Application Help
Variables
The first group of variables stand for the thick client applications: Matrix Navigator,
Business Modeler, System Manager, and MQL. These variables list the document help
variables which are to be included as menu items in the various applications. Document
help variables are also defined in the enovia.ini file.
MX_HELP_MATRIX=MX_HELP_MATRIX_USER
MX_HELP_BUSINESS=MX_HELP_BUSINESS_USER,MX_HELP_MQL_USER
MX_HELP_SYSTEM=MX_HELP_SYSTEM_USER,MX_HELP_INSTALLATION,MX_HELP_MQL_USER
MX_HELP_MQL=MX_HELP_MQL_USER
Document Help
Variables
The variables referenced above are then defined with the text which is to appear in the
Help menu followed by the fully qualified help file name. Windows platforms take
advantage of file associations, so executable information is not necessary. Adobe Acrobat
is required to view PDFs.
MX_HELP_MATRIX_USER=On
Matrix,{DOC_INSTALL_DIR}\PDF\ENOVIALiveCollaborationMatrixNavigatorGuide-{VERSION}.pdf
MX_HELP_BUSINESS_USER=On
Business,{DOC_INSTALL_DIR}\PDF\ENOVIAStudioModelingPlatformBusinessModelerGuide-{VERSION}.
pdf
MX_HELP_SYSTEM_USER=On
System,{DOC_INSTALL_DIR}\PDF\ENOVIAStudioModelingPlatformSystemManagerGuide-{VERSION}.pdf
MX_HELP_MQL_USER= On
MQL,{DOC_INSTALL_DIR}\PDF\ENOVIAStudioModelingPlatformMQLGuide-{VERSION}.pdf
MX_HELP_INSTALLATION=On
Installation,{DOC_INSTALL_DIR}\PDF\ENOVIALiveCollaborationInstallationGuide-{VERSION}.pdf
Note that a comma but no space separates the menu text from the file launching
information. If provided, there must be a space (but no comma) between the executable
and file name. Directories and file names may NOT contain spaces.
If only the Matrix Navigator Help is appearing, the DOC_INSTALL_DIR may be pointing
to the Live Collaboration documentation. Modify the directory to point to the Studio
Modeling Platform documentation.
For example, if you added the following entries to the ini file:
MX_HELP_MATRIX=MX_HELP_MATRIX_USER,MX_HELP_BUSINESS_USER,MX_HELP_SYSTEM_USER,MX_H
ELP_MQL_USER,MX_HELP_INSTALLATION
Chapter 11: Installing the Documentation
307
MX_HELP_MATRIX_USER=On
Matrix,{DOC_INSTALL_DIR}\PDF\ENOVIALiveCollaborationMatrixNavigatorGuide-{VERSION
}.pdf
MX_HELP_BUSINESS_USER=On
Business,{DOC_INSTALL_DIR}\PDF\ENOVIAStudioModelingPlatformBusinessModelerGuide-{
VERSION}.pdf
MX_HELP_SYSTEM_USER=On
System,{DOC_INSTALL_DIR}\PDF\ENOVIAStudioModelingPlatformSystemManagerGuide-{VERS
ION}.pdf
MX_HELP_MQL_USER= On
MQL,{DOC_INSTALL_DIR}\PDF\ENOVIAStudioModelingPlatformMQLGuide-{VERSION}.pdf
MX_HELP_INSTALLATION=On
Installation,{DOC_INSTALL_DIR}\PDF\ENOVIALiveCollaborationInstallationGuide-{VERS
ION}.pdf
You would see this in the Matrix Navigator help menu:
Specifying the Help Viewer Application
If you want to specify the application to use to view the files, the full path and file name of
the executable must be put before the help file path, with a space between the two. There
should be no space before the viewer information, just a comma. For example:
MX_HELP_MATRIX_USER=On Matrix,c:\acrobat\AcroRd32.exe
{DOC_INSTALL_DIR}\pdf\ENOVIALiveCollaborationMatrixNavigatorGuide-V6R2011.pdf
Adding Custom
Help Files
If you want to add custom help files to any of the menus, create new variables and then
reference them in the applicable application’s variable. For example, to add an attribute
description file named attribute.htm to the Business Modeler help menu, use:
MX_HELP_BUSINESS=MX_HELP_BUSINESS_USER,MX_HELP_MQL_USER,MX_HELP_ATTRIBS
MX_HELP_ATTRIBS=On Attributes, {DOC_INSTALL_DIR}\attributes.htm
Of course, the additional file will have to be placed in the directory specified as
DOC_INSTALL_DIR.
308
ENOVIA Live Collaboration Installation Guide
12
Installing Matrix Web Navigator
Web Navigator Installation
Matrix Web Navigator provides access to the ENOVIA Live Collaboration database using
popular Web browsers. Its user interface is nearly identical to that of the ENOVIA Live
Collaboration Matrix Navigator application. Before installing the Java applet, be sure the
ENOVIA Live Collaboration Server is operational.
When installing Web Navigator, the archived class files (.cab and .jar) are first installed on
the Web server. Users may then access the application with the a supported browser.
Before using a new version of Web Navigator, you should remove old versions completely
as described in Removing Web Navigator.
Installing Web
Navigator on UNIX
Use the procedure below to install Web Navigator on a UNIX server. Before installing the
software make sure you know:
•
The path for the Web server document root directory
•
The port number for the server
To install Web Navigator on UNIX
1. Remove any previously-installed versions of Web Navigator. Refer to Removing Web
Navigator for more information.
309
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD in Chapter 7 if necessary.
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup
The following menu is displayed:
Primary Setup Menu for PLATFORM on HOSTNAME as username
1. Setup Web Navigator Software
2. Remove Web Navigator Installation
9. Exit Setup
3. Select Option 1 to perform automatic setup of Web Navigator.
4. Setup prompts for the distribution path:
Enter distribution directory path []?
5. Setup asks for the path where you installed the Live Collaboration server:
J2EE deployment - Enter eMatrixServletRMI installation directory path.
6. Make sure you did not receive any error messages during the install.
Installing Web
Navigator on
Windows
Use the procedure below to install Web Navigator on a Windows Web server. Before
installing the software, make sure you know:
•
The path for the Web server document root directory
•
The port number for the server
Installing Web Navigator on Windows
1. Log into Windows as a person with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome screen, click Next.
5. Next specify the directory where you have installed the ENOVIA Live Collaboration
Server.
6. Now Setup asks you to review the settings you have made and gives you the
opportunity to make any changes by selecting Back and re-entering the information.
Click Next to begin copying files.
310
ENOVIA Live Collaboration Installation Guide
Setting up for Web Navigator Access
After installation of Web Navigator, the following Web pages are available:
•
MatrixAppletXML.jsp page displays a Start Matrix button, which starts the
Java applet for Web Navigator. When users connect for the first time, the supported
version of Sun’s JVM (if needed), as well the ENOVIA applet, are downloaded to the
client machine and saved. The JVM caches the code so, for subsequent connections,
the applet is only downloaded when the jar file is updated (no special plugin is
needed). If a new plugin is required, (either wrong version or none at all), users are
redirected to Sun’s site, which asks the user if they would like to update the Java
plugin. This is required before using Web Navigator.
•
MatrixAppletWizardXML.jsp page uses a parameter that specifies a wizard
name, causing the wizard to launch automatically when the html page is loaded. The
wizard may be optionally embedded within the page, instead of popping the wizard
frames outside of the page. Embedded wizards provide a similar look and feel to a
Web program, and may therefore seem more familiar to users than a wizard that is
spawned from the page. To embed a wizard within a page, add the following
parameters to the Web page that launches the wizard:
•
The Wizard parameter’s value must be set to the name of the wizard to execute.
•
The ShowWindow parameter must be set to false to have the wizard
embedded in the page. Removing the parameter from the html page causes the
wizard to execute in a separate window.
•
Optionally, set the AutoStart parameter is true to set context using the
User and Password parameters. If AutoStart is set to false, the session
context dialog box appears.
If a user gets to the MatrixAppletWizardXML.jsp page after already logging in
using the mxLogin.jsp and the login servlet, the Password parameter need not be
set.
•
The parameters for size must have values large enough to hold the wizard frames.
Width and height values are in pixels. If the size is not sufficient for the wizard,
vertical and/or horizontal scrollbars are be provided.
If you set up your Web server just for Web Navigator, choose one of these pages as the
default (index) page. Otherwise, add links to these pages as needed, from any of the Web
pages currently on your server.
Access these files from:
http:// <hostname>:<portnumber>/<webappname>/WebClient/
For example, to start Web Navigator you might go to:
http://acmeserver:7001/matrix/WebClient/MatrixAppletXML.jsp.
You can customize these pages by adding parameters. For example, you could change the
protocol to https: (secure http) on any of the pages. For a complete list of parameters
that you can add, refer to Configuring Web Navigator, below.
Configuring for
download of Sun
JVM
If Sun’s JVM is not installed, by default your users need internet access and must be able
to download files through any proxy servers that may be in place. If your users will not
Chapter 12: Installing Matrix Web Navigator
311
have access to the internet, you can override the URL for redirection by using any of the
following settings in web.xml:
ematrix.win.plugin
ematrix.sunos.plugin
ematrix.hp-ux.plugin
ematrix.mac.plugin
ematrix.aix.plugin
Refer to Web.xml in Chapter 10 for details.
Also make sure your Sun JVM cache size is large enough to make the downloadable jar
somewhat persistent, otherwise unnecessary reloads may effect performance when
accessing the page.
Installing the
Public Security
Key
A public key is available from CustomerLink that is supported by Web Navigator, as well
as other applets delivered via applications or integrations by ENOVIA. When this in place,
the security certificate warning window will not be displayed. This key needs to be
installed on all client machines or the security window will be displayed. Refer to User
Startup for details.
Configuring Web
Navigator
The pages used to start Web Navigator can be customized as required, by adding
parameters. All parameters that can be passed to the Live Collaboration server are
described below. The provided pages use javascript to generate pages and parameters use
the following syntax:
props.put("PARAMNAME", "VALUE");
If you will use custom applets, your pages may use one of the following formats:
<PARAM name="NAME" value="VALUE">
document.writeln("<param name='NAME' value='VALUE'>");
Complete Parameter List
Parameter Name
Description/Value
ADKTrace
When set to true, Web Navigator will generate a stacktrace that is passed
as a parameter whenever the applet calls into the kernel. This allows the
information to be logged in order to troubleshoot problematic code.
Refer to Studio Customization Toolkit Origin Trace Facility in
Chapter 21 for details.
Autostart
Automatically starts the applet (or wizard) without having to press the
start button (no start button is displayed). The applet autostarts if this
parameter is found on the page—its value (true or false) is ignored. If the
user and password parameters are also included, the applet or wizard
uses them to set context. Otherwise, the set context dialog box is
displayed.
312
ENOVIA Live Collaboration Installation Guide
Parameter Name
Description/Value
CacheFormsOnTypes
When set to true, Web Navigator will more efficiently handle the list of
forms associated with a type and keep it for the duration of the applet
session. The default is false, which means a separate server call is made
EACH time you use the right-mouse button on any object.
You should set CacheMethodsOnTypes to the same value as this.
CacheMethodsOnTypes
When set to true, Web Navigator will more efficiently handle the list of
methods associated with a type and keep it for the duration of the applet
session. The default is false, which means a separate server call is made
EACH time you use the right-mouse button on any object.
You should set CacheFormsOnTypes to the same value as this.
CheckinAppend
A toggle switch for the checkin options, append or replace. The default
is false, which means that existing files are replaced by newly
checked-in files. This setting overrides the setting in the Preferences
dialog.
CheckinUnlock
Tells Web Navigator if objects should be unlocked after files are checked
into it. The default is false. This setting overrides the setting in the
Preferences dialog.
CheckoutLock
Tells Web Navigator if objects should be locked after files are checked
out of it. The default is false. This setting overrides the setting in the
Preferences dialog.
defaultwizardfont
Used to define the font used for wizard widgets that have no font
defined. Refer to Defining Default Fonts on the Web for more
information.
DisableMultipleWizards
Prevents multiple wizards from running concurrently in the same Web
Navigator session. When set to “true,” only one wizard can execute at a
time. If the user attempts to execute a second wizard, the following
message displays:
Multiple concurrent Wizards have been disabled.
If set to “false” or if the parameter is not present, multiple wizards can be
run concurrently.
EnableEnhancedFCS
If set to true, FCS is enabled for Web Navigator. The default is false.
Refer to the System Manager Guide for more information.
ForceFileModes
If set to true, Users will not be able to override the settings of
CheckinAppend, CheckinUnlock, or CheckoutLock in either the
checkin/checkout or preferences dialogs. The default is false.
Host
Value is localhost for Windows or the actual hostname for UNIX
Web servers.
LAF
Sets the look and feel of the applet. Valid values are windows, metal,
or CDE/Motif. If not set, Windows platforms use windows, UNIX
uses CDE/Motif.
Chapter 12: Installing Matrix Web Navigator
313
Parameter Name
Description/Value
Language
Controls which java resource bundle translation is used to display the
menus, windows, and errors of the applet. It is also used to display
schema definitions in another language, if the setting matches a defined
language alias. This setting overrides the language set in the client’s
native locale. For example, when using the following on the Start Matrix
page:
<PARAM name="Language" value="fr">
the applet’s windows are displayed in French, and the fr aliases for
administrative objects will be displayed for all clients.
Valid values are: en (for English), fr (for French), de (for German), it
(for Italian), ja (for Japanese), tw (for traditional Chinese), cn (for
simplified Chinese) and ko (for Korean). These abbreviations must be
lowercase. Translations are provided only for the languages listed above.
The language parameter (and defined alias) must be a valid ISO
Language Code. These codes are the lower-case two-letter codes as
defined by ISO-639. You can find a full list of these codes at a number of
sites, such as:
http://www.ics.uci.edu/pub/ietf/http/related/iso639.txt
If you set the language parameter to an ISO value for which there is
no java resource bundle translation (such as sv for Swedish), Web
Navigator will be displayed in English, but the administrative objects
will be displayed in the language specified, assuming these aliases
exist. To enable a non-ISO alias (such as if you have schema aliases
for manufacturing vs. engineering), set
MX_ALIASNAME_PREFERENCE property on each user that
requires it.
MinTableCellHeight
Sets the maximum height of a table cell in number of lines. The default
value depends on the view mode of the table, as indicated below:
MinTableCellHeight default values of View Modes
View Mode
Default Value
view by name
1 line (always uses 1 line, no matter what value is
set)
view by icon
3 lines (1 each for type name and revision)
view by image
as large as required.
If MinTableCellHeight is set to too small a value, such as if set to 2 and
the view mode is by icon, the default value is used.
MultiFileCheckinEnabled
314
Allows multiple files to be checked in in one operation. The default is
false, which means that multiple file checkin is not allowed. When
enabled, a different File Chooser is launched from the Browse.... button
on the Checkin Dialog. This file chooser allows the selection of multiple
files. However, the alternate file chooser has two minor limitations:
•
file details/icons buttons do not work - you cannot show file
dates.
•
only default file icons are shown, rather than icons associated
with file types.
ENOVIA Live Collaboration Installation Guide
Parameter Name
Description/Value
Password
Password may optionally be provided for login purposes. Used in
conjunction with the User parameter.
Protocol
Set to http or https.
Server
Value defaults to bos. If more than one server is running on a single
server, they may be named, and this parameter should be set accordingly.
ShowWindow
Determines whether the wizard is embedded into the html page (in
which case, value is false) or if a separate window is displayed.
Defaults to true, which displays a separate wizard window. If you want
to change the value back to the default of true, remove the parameter
from the page entirely.
StartLabel
May be set to anything to let the user specify the text for the Start Matrix
button, if a button is displayed.
TableRowChunkSize
Sets the number of Oracle table rows (each row corresponding to one
business object) to be retrieved in each data chunk when expanding in
details mode.After all the chunks have been loaded, Web Navigator
displays the business objects in the indented table. The default is 100.
Increasing the value may improve performance of expands in details
mode.
User
User may be passed for login purposes. If not passed, the Set Context
dialog box displays.
Wizard
Value must be changed to the name of the wizard to be launched.
Additional information on passing parameters via an HTML page is available in the
Programming Guide.
Defining Default
Fonts on the Web
Optionally, fonts may be specified in wizards and cues. When these are displayed on the
Web, by default they are mapped to their closest font “family.” For those wizard
components that are defined with no font specified, an HTML parameter may be added to
a page that lets a default font be defined for all Web clients. The DefaultWizardFont
parameter can be added to the Web page with on of the following values:
•
FONTFAMILY-STYLE-POINTSIZE
•
FONTFAMILY-POINTSIZE
•
FONTFAMILY-STYLE
•
FONTFAMILY
WHERE:
FONTFAMILY is the virtual font name used by Java in the font.properties file to
map to a physical font. Its value may be: dialog, dialoginput, serif,
sanserif,or monospaced.
STYLE may be one of the following:PLAIN, BOLD, BOLDITALIC, or ITALIC. The
default is PLAIN.
POINTSIZE is a decimal representation of the font point size. The default is 12.
For example, the following can be added to the ematrixapplet.jsp page:
<PARAM name="DefaultWizardFont" value="dialog-italic-8">
Chapter 12: Installing Matrix Web Navigator
315
If this parameter is not added to the page, wizard components defined with no font are
displayed using the dialog font family.
font.properties File
Java fonts are defined in one of the font.properties files located in /System32/
lib for Internet Explorer. There may be several versions of the font file (such as
font.properties.ja for Japanese) in support of the various character sets used
across the world. The appropriate file is loaded based on the machine’s locale the first time
Java is launched by the browser.
The font.properties file contains definitions of the five FONTFAMILY variables,
each with five font options specified. A portion of the default font.properties file is
shown below:
dialog.0=Arial,ANSI_CHARSET
dialog.1=Bitstream Cyberbit, DEFAULT_CHARSET
dialog.2=MS Gothic,SHIFTJIS_CHARSET
dialog.3=WingDings,SYMBOL_CHARSET,NEED_CONVERTED
dialog.4=Symbol,SYMBOL_CHARSET,NEED_CONVERTED
dialoginput.0=Courier New,ANSI_CHARSET
dialoginput.1=Bitstream Cyberbit,DEFAULT_CHARSET
dialoginput.2=MS Gothic,SHIFTJIS_CHARSET
dialoginput.3=WingDings,SYMBOL_CHARSET,NEED_CONVERTED
dialoginput.4=Symbol,SYMBOL_CHARSET,NEED_CONVERTED
serif.0=Times New Roman,ANSI_CHARSET
serif.1=Bitstream Cyberbit,DEFAULT_CHARSET
serif.2=MS Gothic,SHIFTJIS_CHARSET
serif.3=WingDings,SYMBOL_CHARSET,NEED_CONVERTED
serif.4=Symbol,SYMBOL_CHARSET,NEED_CONVERTED
sansserif.0=Arial,ANSI_CHARSET
sansserif.1=Bitstream Cyberbit,DEFAULT_CHARSET
sansserif.2=MS Gothic,SHIFTJIS_CHARSET
sansserif.3=WingDings,SYMBOL_CHARSET,NEED_CONVERTED
sansserif.4=Symbol,SYMBOL_CHARSET,NEED_CONVERTED
monospaced.0=Courier New,ANSI_CHARSET
monospaced.1=Bitstream Cyberbit,DEFAULT_CHARSET
monospaced.2=MS Gothic,SHIFTJIS_CHARSET
monospaced.3=WingDings,SYMBOL_CHARSET,NEED_CONVERTED
monospaced.4=Symbol,SYMBOL_CHARSET,NEED_CONVERTED
The browser attempts to use the font specified as option 0 first, and if it is unavailable
proceeds on to option 1, and so on until option 4. The font settings in this file can be
changed, however, changes affect ALL Java programs. For a more complete explanation
of the font.properties files, see http://java.sun.com/j2se/1.4.2/docs/guide/intl/
fontprop.html.
316
ENOVIA Live Collaboration Installation Guide
User Startup
Once the Web server, Live Collaboration server, and Web Navigator are installed, Web
users should be notified of the URL for the page that contains the Start Matrix button. For
example:
http://acmeserver:7001/enovia/WebClient/MatrixAppletXML.jsp.
Clients can then begin working with the database over the Internet.
When users load Web Navigator (that is, click Start Matrix) for the first time, the Web
browser first attempts to download the correct version of Sun’s Java Runtime Environment
if needed. Users are asked to confirm that they wish to install the JRE, and then to accept
the License agreement. When the JRE install finishes, users must restart the browser. On
Internet Explorer you are not prompted for a restart.
Once you restart and return to the URL, before the Start button becomes available a
security warning is displayed. Web browsers only allow special Java “signed” programs to
have read or write access to a user’s hard disk. Selecting Yes allows Web Navigator to be
run. You can avoid this warning by installing the public key that is available from
CustomerLink. This key is supported by Web Navigator, as well as other applets delivered
via applications or integrations by ENOVIA. When this in place, the security certificate
warning window will not be displayed.
To install the public key on Windows
1. Download the MatrixOne.csr file from Customerlink.
2. From the Windows Control Panel, double click Java Plugin.
3. From the Certificates tab, with Signed Applet selected, click Import and browse to
select the MatrixOne.csr file. Click Open.
4. Click Apply.
5. Restart the browser and ENOVIA Applets will no longer display the security warning
window.
Chapter 12: Installing Matrix Web Navigator
317
Removing Web Navigator
Before using a new version of Web Navigator, you should remove old versions completely.
Removing Web Navigator components from Web clients
1. Remove Swing from each client Swing was installed on using one of the methods
below:
•
Deinstall Swing via the Add/Remove Programs option in the Control Panel.
•
From the System icon of Control Panel, use the Environment tab to delete any
reference to swingall.jar in CLASSPATH, if any. If there is a reference, search for
and delete the swingall.jar file.
Version 10.5 does not include Swing classes.
2. Remove previous versions of MQLTCL from each client mqltcl was installed on
using one of the methods below:
•
Deinstall MQLTCL via the Add/Remove Programs option in the Control Panel.
•
Search for wish80.exe. If it exists, and is located in the mqltcl install directory,
remove the entire directory.
•
From the System icon of Control Panel use the Environment tab to delete the
TCL_LIBRARY and TK_LIBRARY environment variables.
MQLTcl is no longer supported or packaged with the LiveCollaborationWebNavigator
tarkit. The “MQLTcl83 Extension for Matrix Web Navigator” link is removed from the
web client.
3. Clear disk and memory caches via the respective browser's cache clearing menu picks
on all clients that used previous versions of Web Navigator.
4. Search all drives for *.jar and *.cab. Delete any cab or jar versions of matrix,
mxplugin, or swing which are in ENOVIA_INSTALL or browser cache directories.
5. Reboot before starting the new install.
If the Studio Customization Toolkit is installed on this machine and you remove Web
Navigator, you will need to re-install the Studio Customization Toolkit.
318
ENOVIA Live Collaboration Installation Guide
The Server’s Directory Structure
When we add Web Navigator to the server, the following structure is created:
Server Install directory
| - - - staging
| - - - ematrix
| - - WebClient
| - - - doc
| - - -user
| - - -pdf
| - - - gif
| - - - java
| - - - classes
J2EE staging directory
Web application name
Client directory
Documentation
Web page images
Java classes for Web Navigator
Archived class files for Web Navigator
Chapter 12: Installing Matrix Web Navigator
319
320
ENOVIA Live Collaboration Installation Guide
13
Integrating with LDAP
and External
Authentication Tools
Internal vs. External Authentication
Internal authentication of users occurs when ENOVIA Live Collaboration authenticates a
user by matching the person’s username and password to a person defined in the database.
For example, if a user attempts to access an ENOVIA product, such as Engineering
Central, and the user has not been authenticated externally, the application presents the
ENOVIA product login page. The surname and password entered by the user must match a
person defined in ENOVIA Live Collaboration. ENOVIA Live Collaboration
authenticates internally by default so if this is the authentication you want to use, it
requires no special setup.
External authentication (also referred to as Single Signon or SSO) occurs when the
application server or some other tool authenticates a user. The requirements for external
authentication differ depending on the tool and configuration used. For example, the
requirement could be a certificate ID entered from a security fob, or a surname and
password stored in a repository or database (such as an LDAP server). To authenticate
externally, the user enters the required information at the login dialog or Web browser
page presented by the authentication tool. ENOVIA Live Collaboration receives the
information that the user has been authenticated.
ENOVIA Live Collaboration supports LDAP (Lightweight Directory Access Protocol)
products that are compliant with the LDAPv3 protocol and is qualified with the following
LDAP servers:
•
openLDAP
321
•
iPlanet Directory Server (IDS)
In addition, ENOVIA Live Collaboration has a standard way to interface with SSO
products that has proven successful with the limited products we have tested. There is no
way to qualify all products or even all capabilities within each product; nor can ENOVIA
restrict you from using your preferred product, since generally the choice of vendor is a
company-wide initiative. Extra “hooks” are provided to allow the flexibility needed to
interoperate with most any SSO product you choose.
Login Behavior
When External
Authentication is
Used
ENOVIA Live Collaboration provides Single Signon when external authentication is used.
This means when a user attempts to access ENOVIA Live Collaboration (by logging into
an ENOVIA product) after having been authenticated externally, ENOVIA Live
Collaboration gives the user access and does not present a separate prompt for login
information. If the user is not already defined as a person in the database, ENOVIA Live
Collaboration automatically creates a person administrative object to represent the user.
ENOVIA Live Collaboration does not attempt to match the surname or password to its
database. For example, the user’s password in ENOVIA Live Collaboration may be
different from the password set up externally. But if authentication is external, the
ENOVIA Live Collaboration password is not used and the password stored with the
external authenticator is used instead.
Persons created automatically in this way are created as Full, Application users and have
all standard person accesses (Read, Modify, Delete, etc.). A restricted password is defined
for them using a random hashed value. But this password is not used for authentication.
Note that the automatic creation of a person administrative object is not sufficient to
successfully access ENOVIA products. These applications require that an
identically-named person business object (type Person) also be created and be in an Active
state. The Person business object must be connected to an Active company business object
with the Employee relationship. Trigger programs can automatically create the necessary
business objects and relationships. For information on the exact requirements for logging
into the ENOVIA products, see the ENOVIA Live Collaboration Administrator’s Guide
and the Administrator’s Guide for the application.
The Application Exchange Framework supports RSA token authentication. When set up,
users must enter a secure ID from a security fob to log in. For information, see the
Application Exchange Framework User’s Guide.
Behaviors to Note
Be aware of the following behaviors when using external authentication.
322
•
If a user starts the Web version of Matrix Navigator after having been authenticated
externally, the user can be re-authenticated internally by using the Set Context option.
•
If a user starts the Web version of Matrix Navigator after having been authenticated
externally, the user can access the Change Password option. The password being
changed is the one in ENOVIA Live Collaboration and not the one used for
authentication, so it has no effect on authentication. In most cases, the user won't
know the ENOVIA Live Collaboration password, which is generated by the system,
and therefore cannot make the change. (When using LDAP with external
authentication, the system does not allow users to change their password through
ENOVIA Live Collaboration client applications.)
ENOVIA Live Collaboration Installation Guide
Enabling External
Authentication
To enable external authentication, the following environment variables are set in enovia.ini
for the Live Collaboration Server (or mxEnv.sh or other startup script on UNIX):
•
MX_PAM_AUTHENTICATE_CLASS— is set to the Java class or JPO to invoke to
perform the authentication. If using a JPO for authentication, the class specification
should use the ${CLASS:XXX} convention for identifying a Java class stored as a
program object.
In order to support FDA approvals in an ENOVIA product, you must use the
authentication JPO. See the procedures below.
The Studio Customization Toolkit contains the following five authentication classes.
When creating a custom authentication method, these classes can be used as a starting
point.
•
matrix.util.SingleSignOnAuthentication
•
matrix.util.BasicAuthentication (Web browser authentication)
•
matrix.util.ServletAuthentication
•
matrix.util.PDUserAuthentication
• matrix.util.JSSOAuthentication
For example, to specify the Java class for basic authentication by the Web browser,
you would use this setting:
MX_PAM_AUTHENTICATE_CLASS=matrix.util.BasicAuthentication
•
MX_PAM_AUTHENTICATE_ARG—An additional parameter to pass to the
authentication function, if required.
MX_PAM_AUTHENTICATE_ARG=ARG
MX_PAM settings should be enabled for SSO logins only. If the MX_PAM settings are
enabled and a user attempts to log in using a non-SSO URL, the login will fail.
When SSO is configured, you should remove the emxLogin.jsp page and use the common/
emxNavigator.jsp page to start ENOVIA products.
In cases where a user is set up for external authentication but not set up in the ENOVIA
Live Collaboration database, a splash page will appear stating that they need to contact
their administrator to establish their ENOVIA Live Collaboration account. This splash
screen is defined by the following parameter in the emxSystem.properties file:
emxFramework.ExternalAuthentication.MatrixUserNotFound.Targe
tJSP = /common/emxSSONoMatrixUser.jsp
If another splash screen is substituted, it must be referenced by the above parameter.
The following is a general procedure for integrating with most tools.
To enable external authentication with a tool
1. Install and configure the external authentication tool you will be using according to
that tool’s documentation.
Chapter 13: Integrating with LDAP and External Authentication Tools
323
2. Update your enovia.ini file for the Live Collaboration Server (previously ematrix.ini)
or startup script, to include the environment variables as listed in the table below.
For integrations with:
Use this(these) setting(s):
Basic authentication by the Web
browser
MX_PAM_AUTHENTICATE_CLASS=matrix.util.BasicAuthentication
Any servlet authentication
MX_PAM_AUTHENTICATE_CLASS=matrix.util.ServletAuthentication
Other tools
MX_PAM_AUTHENTICATE_CLASS=authentication_class
MX_PAM_AUTHENTICATE_ARG=ARG
3. Make sure any jar files used by the external authentication tool are in your
CLASSPATH.
4. If you are using an ENOVIA product, you must by-pass the standard login and logout
pages, emxLogin.jsp and emxLogout.jsp. Use the following property to define the
alternative login/logout page. For more information on using external authentication
with ENOVIA Live Collaboration, see the ENOVIA Live Collaboration
Administrator’s Guide.
ematrix.sso.logout.url=URL_FOR_ALTERNATE_LOGOUT_PAGE
Using the
Authentication
Classes
The authentication classes used with ENOVIA Live Collaboration follow all conventions
of JPO programming. There must be a constructor with the signature “<init>(Context
context, String[] args)” and at least one additional method with the signature
“authenticate(Context context, String[] args)”. The constructor is actually called with an
empty argument list. The authenticate method will be called with 0 or 1 arguments,
depending on whether MX_PAM_AUTHENTICATE_ARG is set or not.
The authenticate method can be used to retrieve the Web client credentials (contained in a
java.util.Map) using the call:
Map map = context.getCredentials();
The credential map contains all the http headers and cookies received from the client/
server connection at the time authentication is requested. The authenticator may proceed
to do its work by either setting context directly with a derived username/password, or by
simply returning a username as a string. When a username is returned, the Live
Collaboration Server assumes the user has been fully authenticated and sets the database
context to the ENOVIA Live Collaboration user of the same name. If the user does not
exist in the ENOVIA Live Collaboration database, a new user is added to the database
(with a randomized initial password setting). Authentication methods can also throw
exceptions, and any exception results in a failed login.
324
ENOVIA Live Collaboration Installation Guide
The following table lists those elements of the map that will always be set by the
Application Exchange Framework:
Map Element
Set in this way by the framework:
HttpServletRequest.remoteUser
If available, string containing the username of the
requesting user. Either defined on the remote host or
defined by the web / application server.
HttpServletRequest.authType
String containing the authentication credentials.
HttpServletRequest.Method
String containing the request method (GET, POST,
…).
HttpServletRequest.URI
String containing the complete URI up to the
Query_String separator “?”.
HttpServletRequest.Protocol
String containing the requested protocol HTTP/1.1
or HTTP/1.0, etc.
HttpServletRequest.pathInfo
String containing the Path_Info, which is extended
path information after a Servlet, JSP, or CGI
program e.g. /Servlet/checkout/abc.doc where /
abc.doc is the Path_Info.
HttpServletRequest.contentLength
String containing the Content-Length of the request.
HttpServletRequest.contentType
String containing the Content-Type of the request.
HttpServletRequest.serverName
Strings contains the name the server has been
configured for.
HttpServletRequest.serverPort
String contains the current port the application
server is listening on.
HttpServletRequest.remoteAddr
If available, this string will contain the IP address of
the requesting remote host.
HttpServletRequest.remoteHost
If available, this string will contain the resolved
canonical name of the requesting remote host.
HttpServletRequest.Scheme
String containing either HTTP or HTTPS.
The following is an example of “basic” authentication (actually the source for
matrix.util.BasicAuthentication):
// BasicAuthentication.java
//
// Copyright (c) 2002 Dassault Systemes Inc.
// All Rights Reserved
// This program contains proprietary and trade secret information of
// Dassault Systemes, Inc. Copyright notice is precautionary only and does
// not evidence any actual or intended publication of such program.
//
// $Log: BasicAuthentication.java,v $
//
//
package matrix.util;
import java.util.Map;
Chapter 13: Integrating with LDAP and External Authentication Tools
325
import matrix.db.Context;
public class BasicAuthentication
{
public BasicAuthentication(Context context, String[] args)
{
}
public void authenticate(Context context, String[] args) throws Exception
{
Map map = context.getCredentials();
if (map == null)
throw new Exception("no credentials");
String header = (String)map.get("Authorization");
if (header == null)
throw new Exception("no authorization header");
String encoded = header.substring(6);
byte[] decoded = Mime64.decode(encoded);
String decodedString = new String(decoded);
int idx = decodedString.indexOf(":");
if (idx <= 0)
throw new Exception("malformed header");
String user = decodedString.substring(0, idx);
String pass = decodedString.substring(idx+1);
context.resetContext(user, pass, "");
}
}
326
ENOVIA Live Collaboration Installation Guide
Using LDAP with ENOVIA Live Collaboration
ENOVIA Live Collaboration integrates with Lightweight Directory Access Protocol
(LDAP) services, so you can use an LDAP server as a repository to store information
about users. The two LDAP servers tested with ENOVIA Live Collaboration are
openLDAP and iPlanet Directory Server (IDS). LDAP is a set of protocols for accessing
information directories. The protocols are based on the X.500 standard, but are simpler
and support TCP/IP. The LDAP standards are open and therefore any kind of server can
host the directories.
ENOVIA Live Collaboration integration uses a toolkit from openldap.org (http://
www.openldap.org/) for the underlying access protocols and is compliant with LDAPv3.
The integration lets you authenticate users based on the users defined in the LDAP
database. The integration also lets you retrieve user information from the LDAP server,
including: address, comment, email address, fax, fullname, groups, password, phone, and
roles.
Limitations
Be aware of the following limitations related to the LDAP integration:
•
External authentication using LDAP integration is not supported for loosely-coupled
databases.
•
LDAP integration is not supported on SGI IRIX or Compaq True 64 operating
systems.
•
The integration works with LDAP version 2 servers, but version 3 features, such as
TLS/SSL, will not work when running on a version 2 server. ENOVIA recommends
using version 3 servers.
•
LDAP usernames and passwords can contain special characters, but do not use the
following: “ , ‘ * (that is, double quote, comma, single quote, asterisk), since they are
used within ENOVIA Live Collaboration as delimiters. The local operating system of
the LDAP directory may have further character restrictions.
Behaviors to Note
•
For people who are defined in LDAP, the system uses the LDAP password for
authentication. The person’s ENOVIA Live Collaboration password might differ and
is not used for authentication. Users who have a DN in LDAP cannot change their
ENOVIA Live Collaboration password through any ENOVIA Live Collaboration
client application user interface or through the Studio Customization Toolkit.
Business Administrators can change ENOVIA Live Collaboration passwords using
Business Modeler or MQL but if the person is defined in LDAP, the person will not be
able to log in using that password because it’s not the password in the LDAP
directory. The person could log in using the LDAP password.
LDAP Integration
Works for both
Types of
Authentication
You can configure ENOVIA Live Collaboration to integrate with your LDAP server
regardless of the type of authentication you are using: either internal or external
authentication. LDAP refers to where and how the user information is stored, not the tool
that performs the authentication.
Chapter 13: Integrating with LDAP and External Authentication Tools
327
LDAP with internal authentication
Person defined in ENOVIA
Live Collaboration?
Person defined
in LDAP?
Person is authenticated?
Yes
Yes
Yes, through LDAP DN
Yes
No
Yes, through ENOVIA Live Collaboration
No
Yes
Configurable using MX_PAM_PERSON_CREATE.
If TRUE, the system automatically creates the person
administration object in ENOVIA Live Collaboration and the
person is authenticated.
If FALSE, authentication fails. For more information, see
Creating person administrator objects.
No
No
No
LDAP with external authentication
Person defined in ENOVIA
Live Collaboration?
Person defined
in LDAP?
Person is authenticated?
Yes
Yes
Yes
Yes
No
No
No
Yes
The system automatically creates the person administrator
object in ENOVIA Live Collaboration and the person is
authenticated. (This happens automatically and is not
dependent on a variable.)
No
No
No
Information
Retrieved from
LDAP
When you configure the integration with LDAP, you specify the information you want to
retrieve from the LDAP server. The information falls into three categories: passwords, user
information (such as email address, comment, address, fax, etc.), and groups and roles.
Each category is handled a little differently, as described below.
User passwords
If your integration with LDAP includes passwords, users must log in using the password
specified in LDAP. This is true for both internal and external authentication and even if the
user is defined in ENOVIA Live Collaboration with a different or no password. When
configuring the integration, you can specify the default cipher used to validate passwords.
User information
If your integration includes standard user information, such as email address or name,
ENOVIA Live Collaboration retrieves the specified user information from LDAP
whenever the information is requested (for example, with a print person MQL
command). If the information isn’t in the LDAP server, ENOVIA Live Collaboration
328
ENOVIA Live Collaboration Installation Guide
retrieves the information from the ENOVIA Live Collaboration database as usual.
ENOVIA Live Collaboration retrieves user information that is not configured to be part of
the integration from the ENOVIA Live Collaboration database.
For example, suppose your integration includes email address only. If a ENOVIA Live
Collaboration application needs to send an email to a person, it gets the email address
from LDAP. If LDAP doesn’t have an email address for the person, the application
retrieves it from ENOVIA Live Collaboration. If the application needs to get the person’s
name, an attribute that’s not part of the integration, it gets it from ENOVIA Live
Collaboration.
Groups and Roles
Mapping roles from LDAP to the ENOVIA Live Collaboration security model lets LDAP
provide the associations between persons, groups, and roles, but maintains the
lifecycle-based access rights in ENOVIA Live Collaboration. If your integration includes
groups and/or roles and ENOVIA Live Collaboration needs to retrieve a user’s group/role
assignments, it looks for the user’s group/role assignments in the LDAP server. If the user
has no assignments in LDAP, ENOVIA Live Collaboration looks for the user’s
assignments in ENOVIA Live Collaboration. ENOVIA Live Collaboration grants the
person the access rights defined for the group/role in ENOVIA Live Collaboration. If the
LDAP server assigns a user to a group/role that does not exist in ENOVIA Live
Collaboration, ENOVIA Live Collaboration discards the assignment.
Using the Group of Names and Group of Unique Names features in LDAP v3, you can
assign groups within groups, or roles within roles, in addition to individual users in groups
or roles. When configured as described in Retrieving group/role assignments, ENOVIA
Live Collaboration recognizes a person as belonging to a higher level group or role if the
person is assigned to a group or role within that higher level group or role.
For example, suppose an LDAP directory is set up with these groups and user:
When configured properly, ENOVIA Live Collaboration will recognize Joe User as
belonging to Group1 and Group2 but not Group3. The groups need to be defined in
ENOVIA Live Collaboration but the hierarchy need only be defined in the LDAP server.
Chapter 13: Integrating with LDAP and External Authentication Tools
329
Overview of LDAP
Connection
Process
The ENOVIA Live Collaboration integration with LDAP includes a number of
configuration options that let you control how users are authenticated. The main steps
performed when a user logs into an ENOVIA Live Collaboration application that is
integrated with LDAP are listed below, along with the configuration options available.
When MX_LDAP_TRACE =TRUE is included in the ini file/startup scripts, all of these
steps are reflected in the trace log. Trace logs for sample configuration are shown in LDAP
Sample Settings. For details on the variables listed in this overview, see Integrating
ENOVIA Live Collaboration with LDAP.
Steps performed when a user logs in or changes context using a password
1. Connect to an LDAP server.
ENOVIA Live Collaboration attempts to open a connection to the first host defined in
MX_LDAP_HOST variable. If the server does not respond, ENOVIA Live
Collaboration attempts to connect to the second host and so on until it successfully
connects. If an attempt to connect fails because the settings are not correct for a
particular server, the entire bind attempt fails.
2. Initial bind to LDAP.
Before the system can search for the user in the LDAP directory, it must make an
initial bind. This initial bind can either be anonymous or as a privileged user and is
configured using MX_LDAP_BIND_DN, MX_LDAP_BIND_PASSWORD, and
MX_LDAP_BIND_USER.
3. Search LDAP for the user’s fully qualified Distinguished Name (DN).
The search (directory, node, and location within the node) is defined using the values
specified for the MX_LDAP_SEARCH_DN and MX_LDAP_SEARCH variables.
The username entered by the user is substituted for the ${USER} macro in the
MX_LDAP_SEARCH variable. There are three types of search results:
•
If the search finds one DN that contains the username, ENOVIA Live
Collaboration stores the DN in the context object for future reference and
proceeds to the next step.
•
If the search finds more than one DN that contains the username (for example,
the system administrator accidentally used the same username for two DNs),
authentication fails. ENOVIA Live Collaboration notifies the user with an error
messages and writes an entry to the error and access logs.
•
If no DN is found in LDAP and the system is set up for internal authentication,
the system looks for the person in ENOVIA Live Collaboration. If the person is
in ENOVIA Live Collaboration, continue to the next step. If the person is not in
ENOVIA Live Collaboration, login fails. When using external authentication,
login fails whenever the person is not defined in LDAP.
4. Unbind.
5. Rebind and authenticate user.
The MX_LDAP_AUTHENTICATOR variable determines how ENOVIA Live
Collaboration performs all subsequent binds (whether the bind is as the named user or
using the same method used for initial bind: privileged or anonymous user) and
determines how the user is authenticated. If the variable is TRUE, ENOVIA Live
Collaboration rebinds using the DN stored in the context object and the password
entered by the user. If the variable is FALSE, ENOVIA Live Collaboration rebinds
using the values in the MX_LDAP_BIND_DN, MX_LDAP_BIND_PASSWORD,
330
ENOVIA Live Collaboration Installation Guide
and MX_LDAP_BIND_USER variables, just as it did for the initial bind. ENOVIA
Live Collaboration authenticates the user by validating the user’s LDAP password
against the password the user entered.
6. Determine if authenticated user is in ENOVIA Live Collaboration and respond as
configured.
If the user has a person administrator object that is not Inactive, authentication is
complete.
If the user does not have a person administrator object in ENOVIA Live Collaboration
and the system is set up for internal authentication, MX_PAM_PERSON_CREATE
determines if ENOVIA Live Collaboration creates a person object. If the variable is
true, ENOVIA Live Collaboration creates a person administrator object with the
entered username. If the variable is false, authentication fails. When using external
authentication, the system always creates a person administrator object.
Types of Binding
As described in Information Retrieved from LDAP, there are two main stages of binding:
an initial binding and rebindings for all subsequent LDAP operations—such as
re-authenticating the user, querying LDAP for more information about the user (for
example, group information), or getting information about a different user (for example,
the user executes a print command for another user). The initial binding can be either as a
privileged user or anonymous user and the rebindings can use the same method as the
initial binding or can use the named user. MX_LDAP_AUTHENTICATOR determines the
rebind method. This table summarizes the methods that can be used for initial binding and
rebinding.
If Initial Bind
Method is:
The Rebind
Method can be:
By defining the initial bind variables
as described in Initial bindings to LDAP
and setting
MX_LDAP_AUTHENTICATOR to:
Anonymous User
Named User
TRUE
Anonymous User
FALSE
Named User
TRUE
Privileged User
FALSE
Privileged User
Each of the bind methods as they apply to rebinding is described below.
•
Named User binding—Named user binding means the system performs all rebinds
with the DN associated with the entered username and with the entered password. Use
this method for rebindings if your LDAP server or security needs require that the user
be authenticated directly against the LDAP directory server.
•
Privileged User binding—Binding as a privileged user means using the DN and
password for a specific user for all bindings. This user is usually an administrator who
has the ability to access all the attributes of the users or a subset of users who are
designated as ENOVIA Live Collaboration users.
Chapter 13: Integrating with LDAP and External Authentication Tools
331
•
Integrating
ENOVIA Live
Collaboration with
LDAP
Anonymous User binding—You might want to configure ENOVIA Live
Collaboration to bind as an anonymous user if users are being authenticated
externally and you do not want to implement a privileged user just for the purpose of
looking up user attributes that are publicly available from the LDAP directory.
iPlanet Directory Server (IDS) requires the bind user to have administrative privileges
and have access to passwords. Since the anonymous user does not have this access,
binding as anonymous user does not work when using IDS.
You integrate ENOVIA Live Collaboration with an LDAP server by setting environment
variables. Use these variables regardless of the type of authentication you are using
(internal or external). On Windows, these variables are set in the enovia.ini file for the
Live Collaboration Server (previously ematrix.ini); on UNIX they are set and exported in
the startup scripts.
Many of the variables accept macros, such as ${USER} and ${DN}. The descriptions in
the following sections list which macros are accepted by each variable and show examples
of how to use macros with the variables. The examples are for Windows. On UNIX, add a
backslash before macro (\${USER}).
If you are using external authentication but you don’t want to integrate with LDAP (you
don’t want to retrieve any user information from LDAP, including groups and roles), do
not add these variables.
This section divides the LDAP variables into these categories:
•
Connecting to an LDAP server
•
Using multiple LDAP servers
•
Initial bindings to LDAP
•
Subsequent bindings to LDAP (rebinding)
•
Creating person administrator objects
•
Searching LDAP
•
Retrieving person information
•
Advanced person variables
•
Retrieving group/role assignments
•
Generating error and message logs
Connecting to an LDAP server
MX_LDAP_HOST—the host or hosts running the LDAP server (slapd, nds). You can
include the port number with the host name by separating them with a colon. When the
port number is included with the host variable, ENOVIA Live Collaboration ignores the
MX_LDAP_PORT variable.
MX_LDAP_HOST=hostname1:789
If ENOVIA Live Collaboration connects to a server with MX_LDAP_HOST defined as
shown above, the resulting trace log would look like:
16:16:22.229 LDAP t@2092 LDAP: init(hostname1,789)
As described below in Using multiple LDAP servers, you can specify multiple hosts. Do
this by separating the host/port pairs with a space. For example:
332
ENOVIA Live Collaboration Installation Guide
MX_LDAP_HOST=hostname1:789 hostname2:389
MX_LDAP_PORT—the port on which the LDAP server is running. If this variable is not
included and no port is specified for MX_LDAP_HOST, the default port of 389 is used.
MX_LDAP_PORT=789
Using multiple LDAP servers
If you have a backup LDAP server available, you can configure ENOVIA Live
Collaboration to use check multiple LDAP servers by specifying the hosts in
MX_LDAP_HOST. When attempting to bind and multiple host servers are specified:
•
The system attempts to bind with the first server specified in MX_LDAP_HOST. If
the server does not respond (for example, its slapd process is down), the system
attempts to bind with the next server and so on until it is able to attempt to
authenticate.
•
If authentication fails for the first server, the system does not attempt to authenticate
through the second server and bind fails.
If you want to configure referrals, refer to Subsequent bindings to LDAP (rebinding).
Initial bindings to LDAP
MX_LDAP_BIND_DN, MX_LDAP_BIND_PASSWORD, and
MX_LDAP_BIND_USER control how the system binds initially to LDAP. These three
variables are also used for binding under these conditions:
•
all subsequent rebinds when MX_LDAP_AUTHENTICATOR=FALSE
•
context changes by a Business Administrator who does not use a password
•
rebinds when MX_LDAP_AUTHENTICATOR=TRUE but the system cannot access
the DN (for example, the user is defined in ENOVIA Live Collaboration only) or
password to rebind with the logged in user’s credentials
When MX_LDAP_AUTHENTICATOR=TRUE, these variables are used only for the
cases listed in the last two bullets above. For all other logins, the system rebinds as the
named user who is logging in (user’s DN and the entered password).
Chapter 13: Integrating with LDAP and External Authentication Tools
333
This table summarizes the methods for binding to LDAP and authenticating.
User Operation
Initial Bind
Password Validation
Rebind
User who is defined in
LDAP logs in or
changes context with
password
Anonymous user or privileged user
based on “bind variables”:
If MX_LDAP_AUTHENT
ICATOR=TRUE, validate
user DN and entered
password against LDAP
directory.
If FALSE, validate entered
password against password
for DN.
If MX_LDAP_AUTHEN
TICATOR=TRUE, rebind
with user DN and entered
password.
If FALSE, same as initial
bind.
Business
Administrator changes
context without
password
Anonymous user or privileged user
based on bind variables.
N/A
No validation takes place.
Same as initial bind.
User who is defined in
ENOVIA Live
Collaboration only
logs in
Anonymous user or privileged user
based on “bind variables”:
Same as initial bind.
Same as initial bind.
MX_LDAP_BIND_DN,
MX_LDAP_BIND_PASSWOR
D, MX_LDAP_BIND_USER
MX_LDAP_BIND_DN,
MX_LDAP_BIND_PASSWOR
D, MX_LDAP_BIND_USER
MX_LDAP_BIND_DN—the Distinguish Name used to bind to the LDAP server.
Supports the ${USER} macro.
If you are using iPlanet Directory Server (IDS), this name must be an administrative user
in IDS. IDS restricts access to the password field on person objects, so ENOVIA Live
Collaboration must authenticate to the LDAP directory as an administrator user to access
passwords. The specified IDS user must also have access to the organization specified for
the search DN.
MX_LDAP_BIND_PASSWORD—the password associated with the name entered for
MX_LDAP_BIND_DN (or for MX_LDAP_BIND_USER if BIND_DN has the ${USER}
macro). The default is null. When a value is specified for this variable, the bind is
privileged user and not anonymous. If you specify a password, encrypt it first. When the
LDAP trace is enabled, the trace log lists the password as XXXX. See Encrypting the Bind
Password.
MX_LDAP_BIND_USER—Used only when MX_LDAP_BIND_DN has the ${USER}
macro. Specify the name that should be substituted for the macro when using a privileged
user binding.
You can configure these three variables so when they are used for binding, the bindings are
either anonymous or as a privileged user.
To bind as an anonymous user
•
Don’t specify a value for MX_LDAP_BIND_PASSWORD:
MX_LDAP_BIND_DN="uid=${USER},ou=People,dc=enovia,dc=net"
MX_LDAP_BIND_PASSWORD=
MX_LDAP_BIND_USER=
When a person attempts to log in, the resulting trace log would look something like
this:
20:59:28.208 LDAP t@1796
bind('uid=anonymous,ou=People,dc=enovia,dc=net','XXXX',128)
334
ENOVIA Live Collaboration Installation Guide
If you will be using anonymous user for the rebind method as well, keep in mind that
the DN defines where in the tree ENOVIA Live Collaboration can search. If you want
ENOVIA Live Collaboration to be able to search at the top of the LDAP hierarchy,
define the DN with a high point, for example:
MX_LDAP_BIND_DN=o=foobar.com
This allows ENOVIA Live Collaboration to search the entire tree. If you want to
constrain the search, specify a DN that is bound further down in the tree, for example:
MX_LDAP_BIND_DN=ou=People,o=foobar.com
IDS does not allow anonymous user binds.
To bind using a privileged user
1. Specify the DN for the user in the MX_LDAP_BIND_DN.
2. Define the user’s password in MX_LDAP_BIND_PASSWORD.
The user needs Read access to the LDAP database but does not require Write access.
This user must be able to access the passwords of those users designated as ENOVIA
Live Collaboration users. A typical configuration would be as follows:
MX_LDAP_BIND_DN="cn=Directory Manager,dc=matrix-one,dc=com"
MX_LDAP_BIND_PASSWORD==usIVNfm2
MX_LDAP_BIND_USER=
When a person attempts to log in, the resulting trace log would look like this:
16:16:22.229 LDAP t@2092 bind('cn=Directory
Manager,dc=matrix-one,dc=com','XXXX',128)
MX_LDAP_BIND_USER is only used to specify a name to substitute for a ${USER}
macro in MX_LDAP_BIND_DN. For example:
MX_LDAP_BIND_DN="cn=${USER},dc=matrix-one,dc=com"
MX_LDAP_BIND_PASSWORD==usIVNfm2
MX_LDAP_BIND_USER=Directory Manager
Subsequent bindings to LDAP (rebinding)
You can configure the integration so the bindings that follow the initial binding are all
named, using the credentials of the logged in user, or are the same as the initial bind
method (privileged user or anonymous user). For details about the different types of
bindings, see Types of Binding.
MX_LDAP_AUTHENTICATOR—determines how ENOVIA Live Collaboration
performs all rebinds (whether the bind is as the named user, the same privileged user used
for the initial bind, or the anonymous user used for the initial bind) and determines how
users are authenticated. If the variable is:
•
TRUE—ENOVIA Live Collaboration rebinds using the DN stored in the context
object and the password entered by the user. In this case, LDAP performs the
authentication. If the bind is successful, meaning the password matches the password
specified for the DN, the user is authenticated and the system proceeds to the next
step. If a person’s DN is not defined (for example, the person is defined in ENOVIA
Live Collaboration but not defined in LDAP) or the password is empty and the person
is a Business Administrator (a password is required to bind successfully for
non-Business Administrators), the three ini variables (MX_LDAP_BIND_DN,
Chapter 13: Integrating with LDAP and External Authentication Tools
335
MX_LDAP_BIND_PASSWORD, and MX_LDAP_BIND_USER) are used to bind.
If the bind is unsuccessful, authentication fails and ENOVIA Live Collaboration
makes no further attempts to authenticate.
•
FALSE—ENOVIA Live Collaboration rebinds using the values in the
MX_LDAP_BIND_DN, MX_LDAP_BIND_PASSWORD, and
MX_LDAP_BIND_USER variables, just as it did for the initial bind. In this case,
ENOVIA Live Collaboration performs the authentication. It searches for the DN
matching the entered username and then gets the attributes for the person. ENOVIA
Live Collaboration validates the user’s LDAP password against the password the user
entered. If the passwords match, the user is authenticated and the system proceeds to
the next step. If the passwords don’t match, authentication fails.
MX_LDAP_REFERRAL — can be enabled to cause ENOVIA Live Collaboration to
make the additional calls that will retrieve the correct LDAP server to complete user
authentication. when the initial server issues a referral. If MX_LDAP_REFERRAL=false
(the default) only users who are defined in one of the servers specified with
MX_LDAP_HOST will be able to bind. If MX_LDAP_REFERRAL=true, all users will
be able to bind, whether they are defined in one of the MX_LDAP_HOST servers, or
whether they are a referral. The default is false, because it is only necessary in the case
where your LDAP hosts are configured to follow referrals, and since it does require
additional calls.
Creating person administrator objects
If the person logging in is authenticated through LDAP but has no matching person admin
object in ENOVIA Live Collaboration, you can configure the system to create a person
object using MX_PAM_PERSON_CREATE. This applies to internal authentication. If
you have external authentication, the person admin objects are created automatically and
this variable is not needed.
MX_PAM_PERSON_CREATE—Determines if ENOVIA Live Collaboration creates a
person admin object for users who are authenticated in LDAP but do not exist in ENOVIA
Live Collaboration. If the variable is:
•
false—Authentication fails and the user is notified with an error message.
•
true—ENOVIA Live Collaboration creates a person admin object with the entered
username and a randomly-generated password. This password is not used for
authentication and the person must log in with the LDAP password. The person
admin object’s email flag is enabled and IconMail is disabled.
The person admin object is only created when the user logs into an ENOVIA Live
Collaboration client application, such as MQL, Matrix Navigator for the Web, or an
ENOVIA Live Collaboration application. The person admin object is not created
when the person logs into Business Modeler or System.
Use password triggers to update the newly created person object or create a new
person business object as needed. See Using Password Triggers with LDAP.
MX_PAM_PERSON_CREATE can be used to have the system automatically create
person admin objects for any internal authentication implementation, not just LDAP. For
example, it could be used in conjunction with password triggers.
Searching LDAP
These variables define the search commands ENOVIA Live Collaboration uses to query
the LDAP directory.
336
ENOVIA Live Collaboration Installation Guide
MX_LDAP_SEARCH_DN—the Distinguished Name used to search the server. Defaults
to the name specified for MX_LDAP_BIND_DN. If you are using IDS, this name should
be the top of the IDS search tree. For OpenLDAP, the default should be used.
MX_LDAP_SEARCH_DN="dc=enovia,dc=net"
MX_LDAP_SEARCH—the LDAP attribute query string. The string can include the
${USER} macro. For example, the following search string takes the username and passes
it in the LDAP ‘uid’ field (Windows):
MX_LDAP_SEARCH="(&(objectclass=person)(uid=${USER}))"
For example, suppose your search variables are defined with the values shown above for
the two variables. When a person with the username “JoeUser” logs in, the resulting
search would look like this (this is how the search is logged in the trace log):
20:59:28.224 LDAP t@1796
search('dc=enovia,dc=net','(&(objectclass=person)(uid=JoeUser))
','*',2)
Retrieving person information
The following settings specify how ENOVIA Live Collaboration should use LDAP data. If
not specified or if the requested person parameter is not populated for a given user in
LDAP, the information for that field is retrieved from the ENOVIA Live Collaboration
database as if LDAP were not in use.
MX_LDAP_COMMENT—attribute or macro for person’s comment.
MX_LDAP_PASSWORD—attribute or macro for person’s password.
MX_LDAP_PASSWORD2—attribute or macro for person’s secondary password.
MX_LDAP_EMAIL—attribute or macro for person’s email.
MX_LDAP_FULLNAME—attribute or macro for person’s fullname.
MX_LDAP_ADDRESS—attribute or macro for person’s address.
MX_LDAP_PHONE—attribute or macro for person’s phone number.
MX_LDAP_FAX—attribute or macro for person’s fax number.
Advanced person variables
MX_LDAP_ATTRIBUTES—list of LDAP attributes to retrieve for macro expansion.
Person attributes, such as “FULLNAME,” are either specified as a single LDAP attribute
name or as a macro made up of multiple LDAP attributes. Use the
MX_LDAP_ATTRIBUTES variable to specify which LDAP attributes can be used in
macro substitution. The default value is “*”, which makes all LDAP variables available for
substitution. In standard LDAP schemas, there's no reason to change this. In a custom
LDAP schema, MX_LDAP_ATTRIBUTE can be used to limit the amount of information
retrieved from LDAP.
MX_LDAP_CIPHER—sets the default cipher used to decrypt/validate the data stream
coming from LDAP. To secure passwords, you must setup secure protocol for LDAP
which means setting up LDAP to use TLS/SSL. Support for TLS/SSL is described below.
The supported ciphers are CRYPT, MD5, SHA, SMD5,and SSHA. If this variable is not set,
the data stream, including passwords, coming from LDAP are assumed to be clear-text.
This setting may be overridden by a prefix stored with passwords in an LDAP directory
Chapter 13: Integrating with LDAP and External Authentication Tools
337
that denotes which cipher should be used for that specific entry. For example, a password
entry of “{MD5}vbsaaskaer” means that the encoded password ‘vbsaaskaer’ is to be
validated using the MD5 algorithm.
Retrieving group/role assignments
Groups and roles specified in LDAP must exist (with the same names) in ENOVIA Live
Collaboration. If they do not, ENOVIA Live Collaboration cannot use the assignments to
control accesses. However, you can maintain the list of persons assigned to the groups and
roles only in LDAP, if desired.
If a person is assigned to a group in IDS, that person receives all accesses assigned to the
group in ENOVIA Live Collaboration. However, if you print or view the group from MQL
or Business Modeler, the person will not be listed as belonging to the group. If you print or
view the person, the group is listed as one of the person’s assignments.
IDS recognizes groups, but not roles.
MX_LDAP_GROUP_SEARCH—the query string to use to search for assigned groups.
To substitute the person’s LDAP DN when searching for assigned groups, include the
${DN} macro. To substitute the persons username (uid), use the ${USER} macro. For
example:
MX_LDAP_GROUP_SEARCH="(&(objectclass=groupofuniquenames)(unique
member=${DN}))"
MX_LDAP_GROUP_SEARCH="(&(objectclass=groupofuniquenames)(unique
member=uid=${USER},ou=People,dc=enovia,dc=net))"
If your LDAP system has group hierarchies, with groups assigned to other groups, and you
want ENOVIA Live Collaboration to search all higher level groups when checking group
assignments for a person, use the ${DN} macro in MX_LDAP_GROUP_SEARCH. If the
${USER} macro is used instead, ENOVIA Live Collaboration searches only the specified
group and does not consider higher-level groups unless the group hierarchy is modeled in
ENOVIA Live Collaboration.
For example, suppose an LDAP directory has a Group1, which contains Group2. Joe User
is assigned to Group2. When MX_LDAP_GROUP_SEARCH is defined using the ${DN}
macro, like the first example above, and a user executes this MQL command:
print person “Joe User” select isassigned[Group1]
The resulting output is TRUE. If a user requests Joe User’s group assignments, only
Group2, and not Group1, is listed.
Using the same scenario but with MX_LDAP_GROUP_SEARCH defined using the
${USER} macro instead of ${DN}, the resulting output for the isassigned command
would be FALSE (unless the group hierarchy is also modeled in ENOVIA Live
Collaboration).
MX_LDAP_GROUP—group name attribute.
MX_LDAP_ROLE_SEARCH—the query string to use to search for assigned roles. Like
the group search, role search supports the ${DN} and ${USER} macros.
MX_LDAP_ROLE—role name attribute.
338
ENOVIA Live Collaboration Installation Guide
Generating error and message logs
When first integrating with LDAP, it may be helpful to set the following variable to make
debugging information available:
MX_LDAP_TRACE can be set to TRUE when debugging LDAP integration so trace
output is routed to the console.
MX_ACCESS_LOG can be set to TRUE to log errors to the Event Viewer in Windows
and the system.log in UNIX.
Support for TLS/
SSL
The ENOVIA Live Collaboration integration with LDAP services supports the Transport
Layer Security (TLS) and Secure Sockets Layer (SSL) LDAP v3 protocols. These
protocols will not work when running an LDAP v2 server.
To use the TLS/SSL protocols, add this environment variable to your ini file or startup
script:
MX_LDAP_SSL = TRUE
ldaps:// syntax and connectivity is not supported.
Encrypting the
Bind Password
For security, encrypt the password stored for MX_LDAP_BIND_PASSWORD as
described below. ENOVIA Live Collaboration uses the same algorithm used for
encrypting the bootstrap file password. The system unencrypts the password before
passing it to LDAP.
To encrypt the LDAP bind password
1. Log into MQL as a user who has System Admin access.
2. Enter the command:
encrypt password PASSWORD_STRING
For example, to encrypt the password “secret”, enter:
encrypt password secret
MQL outputs the encrypted string.
3. Copy the encrypted string to the ini file or startup script.
Using Password
Triggers with
LDAP
If you want to use password triggers with LDAP, you'll need to:
•
write a custom JPO for the trigger.
•
add MX_PASSWORD_TRIGGERS=TRUE to enable the password trigger.
•
add MX_PAM_PERSON_CREATE=true, if you will be authenticating users not
currently in the ENOVIA Live Collaboration database.
•
configure the password trigger to launch the JPO as appropriate (see the list of
program object names below)
•
set the classpath to the appropriate classes used in the JPO (use CLASSPATH variable
on UNIX, MX_CLASSPATH on Windows).
Chapter 13: Integrating with LDAP and External Authentication Tools
339
When MX_PASSWORD_TRIGGERS is set to true, triggers configured to fire on set
context and/or change password events are enabled. Once enabled, ENOVIA Live
Collaboration executes program objects with the following names when a set context
event occurs:
•
ValidatePasswordCheck
•
ValidatePasswordOverride
•
ValidatePasswordAction
When a change password event occurs with password triggers enabled, ENOVIA Live
Collaboration executes programs named:
•
SetPasswordCheck
•
SetPasswordOverride
•
SetPasswordAction
To use password triggers, create one or more of these programs as appropriate.
Retrieving LDAP
Data Using Selects
You can retrieve LDAP data using MQL select statements. The select command uses the
ldap keyword and the LDAP attribute name. For example, with these environment
variables defined:
MX_LDAP_EMAIL=mail
MX_LDAP_FULLNAME=${sn},${givenName}
MX_LDAP_ADDRESS=postalAddress
MX_LDAP_PHONE=telephoneNumber
MX_LDAP_FAX=facsimileTelephoneNumber
MX_LDAP_GROUP=cn
The following select statements could be used:
MQL<3>print person Peter select ldap[mail];
person
Peter
ldap[mail] = Peter@3ds.com
MQL<4>print person Peter select ldap[telephoneNumber];
person
Peter
ldap[telephoneNumber] = 978-320-4500
MQL<5>print person Peter select ldap[cn];
person
Peter
ldap[cn] = Peter Mason
LDAP Sample
Settings
This section contains samples of LDAP variables set up for various configurations. Except
for the backslash needed for UNIX when specifying macros, the settings are the same for
both UNIX and Windows.
Single Server with initial bind using ${USER} macro and
340
ENOVIA Live Collaboration Installation Guide
anonymous user, rebinds are as named user
This sample includes only the variables that control the connection, binding,
authentication, and search. Variables for retrieving user information are not included.
Because the bind password is not defined, the initial bind is as anonymous user.
Subsequent binds are as the named user because the AUTHENTICATOR variable is
TRUE.
MX_PAM_PERSON_CREATE=true
MX_LDAP_AUTHENTICATOR=TRUE
MX_LDAP_TRACE=TRUE
MX_LDAP_HOST=qechnt2
MX_LDAP_PORT=389
MX_LDAP_BIND_DN="uid=${USER},ou=People,dc=enovia,dc=net"
MX_LDAP_BIND_USER=
MX_LDAP_BIND_PASSWORD=
MX_LDAP_SEARCH_DN="dc=enovia,dc=net"
MX_LDAP_SEARCH="(&(objectclass=person)(uid=${USER}))"
.
.
.
This is how the trace log might look for a system configured with the variables listed
above and when a person with username Test Everything and password Test logs in. The
steps listed on the left side correspond to the steps described in Information Retrieved
from LDAP.
MQL<1>set context user “Test Everything” password Test;
1. Connection to LDAP server
2. Initial bind as anonymous
3. Search for user’s DN; DN
found and stored in Context
object
4. Unbind
5. Rebind as named user and
authenticate
21:12:58.505 LDAP t@1796 LDAP: init(qechnt2,389)
21:12:58.505 LDAP t@1796
bind('uid=anonymous,ou=People,dc=enovia,dc=net','XXXX',128)
21:12:58.521 LDAP t@1796
search('dc=enovia,dc=net','(&(objectclass=person)(uid=Test
Everything))','*',2)
21:12:58.521 LDAP t@1796 dn: ='uid=Test
Everything,cn=QE,ou=Groups, dc=enovia,dc=net'
21:12:58.521 LDAP t@1796 unbind()
21:12:58.536 LDAP t@1796 LDAP: init(qechnt2,389)
21:12:58.536 LDAP t@1796 bind('uid=Test
Everything,cn=QE,ou=Groups, dc=enovia,dc=net','Test',128)
Multiple Server with initial bind and rebind using privileged
user
This set of variables configures a system with two LDAP servers. The initial bind has a
password and specific user so it will be as a privileged user. Because the
AUTHENTICATOR variable is FALSE, the subsequent binds are as the privileged user
also. This sample does not include variables for retrieving user information.
Chapter 13: Integrating with LDAP and External Authentication Tools
341
MX_LDAP_AUTHENTICATOR=FALSE
MX_PAM_PERSON_CREATE=true
MX_LDAP_HOST=HOSTNAME1:789 HOSTNAME2:389
MX_LDAP_PORT=
MX_LDAP_BIND_DN="cn=Directory
Manager,ou=People,dc=enovia,dc=net"
MX_LDAP_BIND_PASSWORD==y8ssla
MX_LDAP_PASSWORD=userPassword
MX_LDAP_SEARCH_DN=”dc=enovia, dc=net”
MX_LDAP_SEARCH=(&(objectClass=person)(uid=${USER}))
.
.
.
This is how the trace log might look for a system configured with the variables listed
above and when a person with username Test Everything attempts to log in. In this case,
the uNser logs in with password Test but the user’s password stored in LDAP is Secret, so
authentication fails. Notice that because the system is rebinding as the privileged user, the
user’s password is not authenticated until the system retrieves the user’s information, after
rebinding. In the previous example, in which the system rebinds as the named user,
authentication takes place as part of the rebind. The steps listed on the left side correspond
to the steps described in Information Retrieved from LDAP.
342
ENOVIA Live Collaboration Installation Guide
MQL<1>set context user "Test Everything" password Test;
1. Connection to LDAP servers
21:12:58.505 LDAP t@1796 LDAP: init(HOSTNAME1:789
HOSTNAME2:389,389)
2. Initial bind as privileged user
21:12:58.505 LDAP t@1796 bind('cn=Directory
Manager,ou=people,dc=enovia,dc=net','XXXX',128)
3. Search for user’s DN; DN
found and stored in Context
object
21:12:58.521 LDAP t@1796
search('dc=enovia,dc=net','(&(objectclass=person)(uid=Test
Everything))','*',2)
21:12:58.521 LDAP t@1796 dn: ='uid=Test
Everything,cn=QE,ou=Groups, dc=enovia,dc=net'
4. Unbind
21:12:58.521 LDAP t@1796
unbind()
21:12:58.536 LDAP t@1796 LDAP: init(HOSTNAME1:789
HOSTNAME2:389,389)
5. Rebind as privileged user
21:12:58.536 LDAP t@1796 bind('cn=Directory
Manager,ou=people,dc=enovia,dc=net','XXXX',128)
16:16:22.338 LDAP t@2092
search('dc=enovia,dc=com','(&(objectclass=person)(uid=Test
Everything))','*',2)
16:16:22.338 LDAP t@2092 result: mail='test@matrix-one.com'
16:16:22.338 LDAP t@2092 result: uid='Test Everything'
Retrieve user’s password
and compare to entered
password
16:16:22.338 LDAP t@2092 result: userPassword='Secret'
16:16:22.338 LDAP t@2092 result: objectClass='top'
16:16:22.338 LDAP t@2092 result: objectClass='person'
16:16:22.338 LDAP t@2092 result:
objectClass='organizationalPerson'
16:16:22.338 LDAP t@2092 result: objectClass='inetOrgPerson'
16:16:22.338 LDAP t@2092 result: sn='Test Everything'
16:16:22.338 LDAP t@2092 result: cn='Test Everything'
Authentication fails due to
password mismatch
16:16:22.338 LDAP t@2092
password
unbind()Error: #1500037: Invalid
Sample for IDS LDAP server
The following is a sample of the ini variables needed to establish an integration with
ENOVIA Live Collaboration and an LDAP server. The sample includes some IDS specific
notes. For most variables, there is no difference between how you define them in IDS
versus OpenLDAP.
# information for connecting to LDAP server running on the
# machine “qeserver5”.
# initial bind using admin account 'admin' created during
installation of IDS;
# this account has access to the domain “matrix-one.com”
# note: On IDS, an administrator account is required to retrieve
# the userpassword attribute
# subsequent binds using named user
Chapter 13: Integrating with LDAP and External Authentication Tools
343
MX_LDAP_AUTHENTICATOR=TRUE
MX_PAM_PERSON_CREATE=true
MX_LDAP_HOST=qeserver5
MX_LDAP_PORT=
MX_LDAP_BIND_DN=’uid=admin,ou=Administrators,ou=TopologyManagem
ent,o=NetscapeRoot’
MX_LDAP_BIND_PASSWORD==Y7d8ss
### Person information
# person to pull from LDAP: password, comment, fullname, and
email
# USER in search string will be populated with ENOVIA
# Collaboration Platform person name. For
# Windows, remove the backslash (\) before the $
# note use of macros in MX_LDAP_FULLNAME
# setting MX_LDAP_ATTRIBUTES to * makes all LDAP attributes
# available for macro substitution
# any field can be populated from multiple LDAP values
# IDS returns cipher type in encoded password string; no need to
specify it here
MX_LDAP_SEARCH_DN=’o=matrix-one.com’
MX_LDAP_SEARCH=”(uid=\${USER})”
MX_LDAP_CIPHER=
MX_LDAP_ATTRIBUTES=*
MX_LDAP_PASSWORD=userpassword
MX_LDAP_COMMENT=comment
MX_LDAP_FULLNAME=${sn}, ${givenname}
MX_LDAP_EMAIL=mail
### Group/role assignment variables
# assignments to be pulled from LDAP. USER in search string will
# be filled with ENOVIA Collaboration Platform Person name; for
# Windows, remove the backslash
# note there is no macro substitution applied to the
# MX_LDAP_GROUP attribute
# also note that IDS has no concept of “roles”
MX_LDAP_GROUP_SEARCH=”(&(objectclass=groupofuniquenames)(unique
member=uid=\${USER},ou=People,o=matrix-one.com))”
MX_LDAP_GROUP=cn
### Error Log
MX_LDAP_TRACE=true
One-to-One mappings to attributes
When configuring LDAP attribute settings, you can provide a one-to-one mapping from
LDAP attributes to ENOVIA Live Collaboration user attributes or you can use macro
syntax. The following example shows a sample configuration for OpenLDAP that contains
only one-to-one mappings for attributes.
MX_LDAP_AUTHENTICATOR=TRUE
MX_PAM_PERSON_CREATE=true
MX_LDAP_HOST=hplight
MX_LDAP_PORT=
MX_LDAP_BIND_DN="uid=${USER},ou=People,dc=enovia,dc=net"
MX_LDAP_BIND_PASSWORD=
MX_LDAP_SEARCH=(uid=\${USER})
MX_LDAP_CIPHER=CRYPT
MX_LDAP_PASSWORD=userPassword
344
ENOVIA Live Collaboration Installation Guide
MX_LDAP_COMMENT=comment
MX_LDAP_EMAIL=mail
MX_LDAP_FULLNAME=cn
MX_LDAP_TRACE=true
In the above sample, the LDAP server is running on the host ‘hplight’ on the default port.
ENOVIA Live Collaboration will bind initially to the server as an anonymous user
because no BIND_PASSWORD is defined. Then the system binds as the named user. The
search string is formed by taking the username and passing it in the LDAP ‘uid’ field.
Passwords are assumed to be stored in UNIX crypt() format. Password, comment, email,
and fullname are being read from LDAP; all other person parameters will be read from
ENOVIA Live Collaboration.
Macros for attributes
To use macros for LDAP attribute settings, set the variable MX_LDAP_ATTRIBUTES to
the list of all LDAP attributes that can be retrieved for a user. You can then specify the
individual ENOVIA Live Collaboration attribute settings, such as
MX_LDAP_ADDRESS, using macro syntax, ${name}. The advantage of this option is
that multiple LDAP attributes can be mapped into a single ENOVIA Live Collaboration
user attribute. This is common for such things as “address”, where city, state, and ZipCode
may each be separate LDAP fields. Here is an example of the same setup as shown in the
previous example except it uses macros for attributes:
MX_LDAP_AUTHENTICATOR=TRUE
MX_PAM_PERSON_CREATE=true
MX_LDAP_HOST=hplight
MX_LDAP_PORT=
MX_LDAP_BIND_DN="uid=${USER},ou=People,dc=enovia,dc=net"
MX_LDAP_SEARCH=(uid=${USER})
MX_LDAP_CIPHER=CRYPT
MX_LDAP_ATTRIBUTES=userpassword,comment,mail,cn,city,state,zip
MX_LDAP_PASSWORD=${userpassword}
MX_LDAP_COMMENT=${comment}
MX_LDAP_EMAIL=${mail}
MX_LDAP_FULLNAME=${cn}
MX_LDAP_ADDRESS=${city}, ${state} ${zip}
MX_LDAP_TRACE=true
Chapter 13: Integrating with LDAP and External Authentication Tools
345
Tomcat LDAP Authentication
Every context change, including push-pop, results in a request to the repository for
authentication. This section describes setup procedures that allow Tomcat to authenticate users against an LDAP/Active-Directory repository as a means of reducing the
total traffic between the DS ENOVIA kernel and the LDAP repository.
Changes to
server.xml
Enter the following Realm template in the Engine container. The connectionName is
the DN of the BIND user, which is the same as MX_LDAP_BIND_DN. The connectionPassword is the same as MX_LDAP_BIND_PASSWORD.
<Realm className=”org.apache.catalina.real.CombinedRealm” >
<Realm
className=”org.apache.catalina.realm.UserDatabaseRealm”
resourceName=”UserDatabase”/>
<Realm className=”org.apache.cataline.realm.JNDIRealm”
debug=”99”
connectionName=”kdyer@matrixone”
connectionPassword=”........”
connectionURL=”ldap://matrixone.net:3268”
alternateURL=”ldap://matrixone.net:3268
referrals=”follow”
userBase=”DC=matrixone,DC=net”
userSearch=”(sAMAccountName={0})”
userSubtree=”true”
userRoleName=”memberOf”/>
<Realm/>
This configuration uses the CombinedRealm of Tomcat 6.0, which allows you to store the
test userNames in the tomcat-users.xml file. You can centralize this file per machine by
properly setting the pathName. This configuration also assumes that the default Global
Naming Resource is in place in the server.xml file. The passwords in this file may be
stored encrypted (digested). Please refer to the tomcat-6.0-documentation for
realm-howto.
Changes to
web.xml
Add the following changes to the end of the web.xml file. These security constraints
configure the web application to use the new LDAP login JSP and protect the Servlets, JSPs, Workspace, and Services resources.
<welcome-file-list>
<welcome-file>/common/emxNavigator.jsp</welcome-file>
</welcome-file-list>
<!-- Insert the following after welcome-file-list container -->
<security-constraint>
<web-resource-collection>
<web-resource-name>SecurePages</web-resource-name>
<description>Security constraint for resources in the
secure directory</description>
<url-pattern>*.jsp</url-pattern>
<url-pattern>/servlet/*</url-pattern>
346
ENOVIA Live Collaboration Installation Guide
<url-pattern>/workspace/*</url-pattern>
<url-pattern./services/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<description>General Access</description>
<role-name>*</role-name>
</auth-constraint>
<user-data-constraint>
<description>SSL not required</description>
<transport-guarantee>NONE</transport-guarantee>
</user-data-constraint>
</security-constraint>
<login-config>
<auth-method>FORM</auth-method>
<form-login-config>
<form-login-page>/emxLogin_LDAP.jsp</form-login-page>
<form-error-page>/emxLogin_LDAP.jsp</form-error-page>
</form-login-config>
</login-config>
<security-role>
<description>General Access</description>
<role-name>*</role-name>
</security-role>
Additions to
enovia.ini
Add the following line to the C:\WINDOWS\enovia.ini file (previously ematrix.ini):
MX_PAM_AUTHENTICATE_CLASS=${CLASS:mxCommonRUAuthentication}
In addition, you must also import the two Java programs and compile them into the database as Java program objects.
Changes to
WEB-INF\classes
The zip archive includes a new emxLogin.properties file (in ematrix/properties/),
which contains several new entries for the LDAP login page. Back up the existing
emxLogin.properties file, and then replace it with this one.
Chapter 13: Integrating with LDAP and External Authentication Tools
347
348
ENOVIA Live Collaboration Installation Guide
14
Installing Business
Process Services™
Overview
ENOVIA Live Collaboration Business Process Services includes these components:
•
Application Exchange Framework™ (AEF)—Contains the underlying schema and
user interface for ENOVIA products.
•
Common Components—Contains features used by multiple ENOVIA applications,
such as Discussions and Subscriptions.
•
ENOVIA Team Central—Provides a secure, structured, virtual workplace that enables
ad-hoc collaboration for cross-functional and geographically dispersed teams.
•
ENOVIA Business Metrics Module—Generates metric reports based on your
business processes.
Before installing any of these products, you must install the BPS version that supports the
version of the application you are installing.
The BPS installation installs the user interface components and then allows you to launch
a separate installation program to add only the schema required for the applications you
will use. You can later use the schema installer by itself to add more ENOVIA or custom
application schema.
Refer to the Program Directory for the given version of Business Process Services for
installation instructions and requirements specific to that version.
349
For more information on Business Process Services, refer to the ENOVIA Live
Collaboration Administrator’s Guide.
Important
Installation
Considerations
ENOVIA products are not simple executables that can be installed and then uninstalled
like PC software productivity tools. Instead, these applications require regimented backup
and testing procedures like any other enterprise system. It is important to understand that
database schema and business object instance data is installed with all ENOVIA products,
including BPS. Because of this, it is important to back up the system to which they are
being installed. This backup should include the file system, as well as the database itself.
It is STRONGLY recommended that a System Test environment is in place that is an exact
duplicate of the Production environment where the software will ultimately be operated.
This System Test environment is where the software should first be loaded and tested. The
purpose of testing is to make sure the application can be installed without errors and that,
once installed, it functions as expected.
Often, customers and/or ENOVIA Professional Services modify an application in order to
satisfy specific needs of the user community. To facilitate this, the schema installer looks
at a custom directory for your modification XML files and merges the files accordingly.
Refer to Adding Custom Schema for more information.
If you are doing upgrades or installing a new application, you can expect to take 4 to 12
hours to test and validate the installation scripts for the schema and document any changes
you had to make (or what changes the installation scripts made). The amount of time
decreases as you install to the next environment (Development, Test, Production) and
depends on the amount of customizations made to the schema and JSPs. You’ll need to
allow for additional time to perform standard system regression tests. The amount of time
for system regression tests depends on the amount of changes made to JSPs and custom
triggers.
Don’t assume that because everything is fine in one environment, it will be fine in the next
environment. In some cases, an environment may have gone through one or two upgrades
before promoting it to the next environment. This is why an exact copy of Production
environment (and backups!) are so important.
Preparing to Install
to a Production
Environment
The following procedure describes the main steps needed before an ENOVIA product is
installed to a Production environment. Note that some sites may have an additional
Development environment that is installed to prior to the Test environment.
To install ENOVIA products in a Production environment
1. Install an application (including BPS) into an empty, play database. The purpose of
this step is to get familiar with the functionality and perform a gap analysis for what
needs to be configured.
2. Save off the application staging area that contains the database scripts that install the
application and its schema. This staging area can usually be found below the
SERVER_INSTALL directory, in the Apps\APP_NAME\<version>\
subdirectory. This subdirectory contains an installAPP_NAMEAPP_VERSION.tcl
file. This file can be run from within MQL to install the application schema.
3. Make the System Test environment a copy of the Production environment.
350
ENOVIA Live Collaboration Installation Guide
4. Install the BPS and/or application to the Test environment, review the changes the
installation makes, and customize the XML files as needed. For more information
about how to review the installation changes and what to look for, see Reviewing
Changes that an Installation Makes. Refer to Adding Custom Schema for customizing
information.
5. After making changes to the installation, restore the Test environment so it is again an
exact copy of the Production environment. Apply the new installation (with your
changes) to the Test environment. Test the installation and make additional changes to
the install scripts as needed.
Repeat the above process until you are satisfied the installation has not adversely
affected your system and all of the errors have been fixed in the customized schema.
6. Perform the necessary testing in the System Test environment until there is an
acceptable level of reliability and performance.
7. Now that the scripts are solid and you know what to expect when they are run against
the Production environment, you can plan the upgrade to the Production system.
Always back up a Production system before making any schema changes. The installations
for both BPS and ENOVIA products make schema changes.
Reviewing
Changes that an
Installation Makes
When performing an installation, you need some way of determining the changes the
installation is making to the schema, business object data, and JSPs. One way of tracking
the schema changes is to create an XML export file prior to running the installation. After
installing, you can use the XML compare utility from MQL to review the changes to the
schema. You can also use the log file created for each installation in
SERVER_INSTALL\Apps\APP_NAME\<version>\ to track changes to schema and
business objects. For more information on the log file, see Installation Log File.
When reviewing the changes that have been made, look for changes that may conflict or
that are not needed because of customizations that you have made. Some changes to watch
for are listed below. Keep in mind, however, that the install scripts make changes to
support the business processes within each application. You need to decide if these
changes are consistent with your business process and if they are needed based on the
existing customizations you have made.
For example, suppose the installation for ENOVIA Engineering Central adds an extra
notification or signature to the ECR Standard policy. This change is made because the
Product Engineer needs to approve the ECR before it goes to a full Change Board review.
Your business process, however, requires approval from a Project Engineer instead of the
Product Engineer. You have triggers that already handle this, thus making the newly-added
Engineering Central notification unnecessary (or unwanted). Alternatively, if you are
using out-of-the-box Engineering Central, this notification is crucial and if removed,
ECRs will get hung up at a particular state because no one was notified to do anything
with it.
Installation changes that you may need to review
•
Event triggers—If you are NOT using emxTriggerManager and are NOT using the
naming conventions recommended by BPS documentation, then there is a good
chance that your trigger will be overwritten.
Chapter 14: Installing Business Process Services™
351
If you do not have a trigger on a given event, there is a chance one might be added. If
you do not want a particular trigger to run, you can deactivate the trigger by demoting
the corresponding eService Trigger Program Parameters object to the Inactive state.
Note that business objects are not captured in an XML compare. This is currently a
manual process. It might be a good idea to create a backup of all eService Trigger
Program Parameters objects.
Before Installing
352
•
Access privileges—BPS or application installation may add or remove some access
privileges.
•
Properties files—New installations typically add new properties that let you configure
features and that contain string resources for onscreen text display and
internationalization. All properties files are stored in ematrix/properties. When BPS
or any application is installed, the installation copies all files in ematrix/properties to
ematrix/properties.sav and then overwrites files in ematrix/properties. The
properties.sav directory is overwritten with each new install so make sure you make a
backup of this directory if you want to save it.
Properties files are intended to be configured so any changes that you make need to be
merged back into the newly installed properties files using any file comparison tool.
The comparison should be between the newly installed properties file (located in
ematrix/properties) and the “old” properties file (located in ematrix/properties.sav).
•
New administrative objects—If you use the Studio Modeling Platform, you may
want/need to “hide” types that are not used so the type chooser is not cluttered. Take
care not to hide types that are used by any ENOVIA products that you are using. You
may want to consider subtyping as an alternative.
•
You may see new attributes added to a type or relationship.
•
Administrative (schema) properties—Most installations add schema properties.
•
Any customized UI component.
Make sure you perform the following steps before installing an ENOVIA product for
either platform:
•
Back up all application directories and the database. Before installing to a system
that has an ENOVIA application installed, make backup copies of the
MX_BOS_ROOT/Apps/framework directory. Also back up the database instance. If
you have customized properties files, you must back up the files before you upgrade
the software to prevent them from being overwritten. Each product has properties files
for configuring settings and for onscreen text. For example, BPS has
emxSystem.properties, emxLogin.properties, and
emxFrameworkStringResource*.properties. All properties files are located in
ematrix/properties.
•
Have a staging area. A staging area must exist in order for the backup to work. Make
sure there is a STAGING directory under the Live Collaboration server installation
directory. If not, then extract enovia.war into MX_BOS_ROOT/STAGING.
•
Have a valid bootstrap file. The installation program requires there be a valid
bootstrap file that points to the database you are using. For UNIX, the bootstrap file
must be called MATRIX-R (all caps). For Windows, the bootstrap can have any
name. Both the UNIX and Windows setup programs ask for the location of the
bootstrap file during installation.
ENOVIA Live Collaboration Installation Guide
•
Turn off system-wide password settings. Make sure all system-wide password
restrictions are turned off (unchecked), such as the setting that requires passwords to
be a minimum number of characters. To access system-wide password settings,
choose Settings>Password from Business Modeler. You can turn the settings back on
after you install the applications.
•
Be sure that MQL is not in escape mode. Run the following MQL command to
determine if escaping is enabled (you must log in as a business administrator to do
so):
MQL<> print escape;
If the system indicates that escape mode is on, turn it off before running the install
with:
MQL<> set escape off;
Refer to “Working with Workspace Objects” in the MQL Guide for details.
•
Oracle tuning may be required. Be aware that the database tuning required for BPS
installation may be different than the tuning required for a normal production
operation.
•
Refer to the installation instructions for your platform: Installing Business Process
Services on UNIX or Installing Business Process Services on Windows.
Chapter 14: Installing Business Process Services™
353
Installing ENOVIA Live Collaboration Business
Process Services
Installing
Business Process
Services on UNIX
Before installing BPS on UNIX you must:
•
Log in as a user who has the privileges to install BPS (install on the database, run
MQL, etc.).
•
If installing from a CD, mount the CD so the operating system software can access
the files contained on the disk. Refer to To mount the CD-ROM in Chapter 7 for
examples of mount commands for each platform.
•
Make sure you know the path where mql is located.
•
Make sure you know the username and password for the super user (user that has
Business and System Administrator privileges, such as creator).
To install Business Process Services on UNIX
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD in Chapter 7 if necessary. Use the -i option of the
tar command to avoid errors caused by long path names in the distribution that some
versions of tar can't handle properly.
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup.BusinessProcessServices
3. Choose the directories for the installation to use.
Choose Scripts Directories
-----------------------------------------------------------Enter install directory path for ENOVIA Studio Modeling
Platform []?
Enter install directory path for ENOVIA Live Collaboration
Server []?
Enter directory path for ENOVIA Studio Modeling Platform
scripts [/usr/bin]?
The ENOVIA Studio Modeling Platform installation directory is the path that
contains the ENOVIA Studio Modeling Platform installation.
The ENOVIA Live Collaboration Server installation directory is the path that
contains the ENOVIA Live Collaboration Server installation.
The ENOVIA Studio Modeling Platform scripts directory is the path where the
scripts that build the application in the database are placed. If you specify a directory
that does not exist, the setup program will create the directory.
4. Tell the setup program the user name and password for a user that has Business and
System Administrator privileges, such as creator. If the user has no password, accept
the default.
Specify Administration Parameters
-----------------------------------------------------------Enter Administrator user for ENOVIA Studio Modeling
Platform? [creator]?
354
ENOVIA Live Collaboration Installation Guide
Enter Administrator password for ENOVIA Studio Modeling
Platform? [NONE]?
5. Tell the setup program where the Schema Customization directory is located.
Enter custom schema directory path [ ]?
6. At the next prompts, enter the names of the Data and Index table spaces for the
eService Production vault. For non-Oracle databases, the values must be the same.
Specify database storage details for eService Production vault’s
table data and indexes
----------------------------------------------Enter Data Table Space? [NONE]?
Enter Index Table Space? [NONE]?
The eService Production vault is the vault that will be used for production data.
Consult your Database Administrator for information about the table space names
used.
If you do not specify a table space name, the tables and indexes for the product vault
will be created in the database’s default tablespace, which may not be sized
appropriately for production data storage.
For Oracle, if you specify only an Index Table Space, the Data Table Space will
default.
7. You are then asked what schema to install:
Schema to support the Business Process Services product will be
installed automatically.
Schema to support ENOVIA products may be selected below.
-----------------------------------------------------------Do you wish to install All Applications <Required for ENOVIA
products> Schema [No]?
All Applications option includes schema for all ENOVIA products. The schema for
BPS is automatically installed whether or not you install the application schema.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
8. You are then asked to confirm your schema choices:
Installing following schema
Business Process Services
All Applications
Do you want to continue [yOrN]?
9. The schema installer then creates the selected schema. If errors are encountered and
you chose to undo transactions in case of errors, the setup will undo all changes.
Check the files named installSchemaInstallerVERSION.log and
SchemaChangesMQLVERSION.log, as well as installFrameworkVERSION.log and
installFrameworkVERSION.err in your installation script directory to get details
about errors and to see exactly what items were added and/or modified. If there are no
errors, you may still want to review the log files to see if any items were renamed due
to name collisions.
10. After the schema installer has created the schema, Business Process Services are
installed.
11. Setup then indicates that BPS installed successfully.
Chapter 14: Installing Business Process Services™
355
12. If you have backups of customized properties files, you’ll need to compare your
customized files with the new files from the updated version. Either update the new
files with your customizations or update your customized files with any new settings.
13. Continue with next step in General Installation for ENOVIA Live Collaboration
Server.
Installing
Business Process
Services on
Windows
To install Business Process Services on Windows
1. Log into Windows as a person with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome frame, click Next.
5. At the Super User/Password frame, enter the User and Password that has Business
and System Administrator privileges, such as creator. If the user has no password,
leave the Password box blank. Click Next.
6. The schema installer then requests the directory where custom schema files exist. If
needed, specify the directory. Click Next.
7. At the next frame, specify database storage details for eService Production vault's
table data and indexes. For non-Oracle databases, the values must be the same.
The eService Production vault is the vault that will be used for production data.
Consult your Database Administrator for information about the table space names
used. If you do not specify table space names, the tables and indexes for the product
vault will be created in the database's default storage area.
Click Next.
8. Specify the Schema to install by checking the boxes of the options you want.
All Applications option includes schema for all ENOVIA products. The schema for
BPS is automatically installed whether or not you install the application schema.
Click Next.
9. You are asked to review your choices. Click Yes to install or No to Cancel.
If you clicked Yes, the Setup program:
356
•
Copies install scripts to the selected directory. While the files are copied, a
progress meter displays the current files being copied and the percent completed.
Files named installSchemaInstallerVERSION.log and
SchemaChangesMQLVERSION.log are created in the SchemaInstall
directory.VERSION is the software version number, such as 10-0-0-0. (If you
used the Advanced install option and chose not to run the install scripts, the setup
performs this step only and the remaining steps are not performed.)
•
Launches MQL in the background and adds the schema.
•
Displays a progress meter, which shows the current files being run and the
percent completed.
ENOVIA Live Collaboration Installation Guide
It may take several minutes to run the SchemaInstaller. If you have an extensive database
in place, it could take much longer.
10. A Business Process Services setup is complete message displays. Click OK.
11. When complete, you receive a message telling you either the setup encountered errors
or the setup is complete.
If errors were encountered, the setup will have undone all changes (unless you used
the Advanced install and chose not to undo the transactions). Using a text editor such
as WordPad, check the log and error file names of all the products installed.
a ) Start with the installFrameworkVERSION.log and
installFrameworkVERSION.err in your installation script directory to get details
about errors and to see exactly what items were added and/or modified.
b ) Go through the remaining log and error files in the order the products were
installed.
c ) Check also the SchemaChangesMQLVERSION.log file.
If there are no errors, you may still want to review the log files to see if any items
were renamed due to name collisions.
12. If you have backups of customized properties files, you’ll need to compare your
customized files with the new files from the updated version. Either update the new
files with your customizations or update your customized files with any new settings.
13. Continue with next step in General Installation for ENOVIA Live Collaboration
Server.
Refer to the application administrator’s guides for any application specific setup issues.
Refer to the ENOVIA Live Collaboration and ENOVIA Studio Modeling Platform
documentation sets for FCS setup, deployment settings, and server setup and diagnostics.
Adding Sample
Users
A program named emxCommonAddSampleUsers.tcl script adds sample users for each
role that exists in the database. The program can be run as many times as necessary.
To add sample users
1. From MQL, set context to a Business Administrator user that is allowed to create all
kinds of users.
2. Run the program as follows:
exec program emxCommonAddSampleUsers.tcl USERS_PER_ROLE;
Where USERS_PER_ROLE defaults to 3 and indicates the number of times the
program will loop through the commands.
The program creates as many users as specified for each role in the database. This not only
includes the administrative person objects, but also the business object person objects and
connections that the applications require.
Chapter 14: Installing Business Process Services™
357
Schema Installer
You can add schema after installing the framework using the schema installer. There may
be two schemaInstaller directories as follows:
•
If you chose not to install any schema at the time you installed the framework, the
schemaInstaller setup program is in Apps/framework/<version>/
SchemaInstaller. This is the only SchemaInstaller directory you will see until
this setup program is run either manually or via the framework install routine.
•
Once you have installed some schema with the schema installer, you can install out of
the box schema not previously installed, or custom schema that is defined in xml files
as described in Adding Custom Schema.
After successful installation of selected schema, it is registered in the database.
SchemaInstaller adds the property appSchema<SCHEMA_NAME> to the
eServiceSystemInformation.tcl program. The value of this property indicates the version
of schema. In addition, the eServiceSystemInformation.tcl program’s code, which is
basically an install log, is appended with the same information. This includes custom
schema as well. For example, if Engineering Central schema is installed with
SchemaInstaller 10-6, the system information program has the
appSchemaEngineeringCentral property with a value of 10-6, as well as the following
entry appended to the program code:
SchemaEngieneringCentral 10-6 04-30-2005 11:37 AM SCHEMA
Schema XML Files
Once the SchemaInstaller setup program has been run (either from within the BPS
installation program or manually from
SERVER_INSTALL\Apps\Framework\SchemaInstaller\), the following
directory structure is in place:
SERVER_INSTALL\Apps\Framework\<version>\SchemaInstaller\
| Common\
(common routines used at time of install
and uninstall)
| Conversions\
(includes conversion manifest files and
conversion programs)
| InstallUtility\
(JPOs used to install schema)
| SchemaDefinition\ (includes SDF XML files defining each
administration object)
| SchemaManifest\
(includes SchemaManifest files and
Schema-Mapping file)
| Uninstall\
| CustomSchema\
(staging area for customizing schema or
adding custom apps)
| SchemaDefinition\
| SchemaManifest\
Schema installer is driven by four kinds of xml files, placed within this directory structure
as follows:
1. Schema Definition Files (SDF)
358
ENOVIA Live Collaboration Installation Guide
These files are found in the SchemaDefinition directory. There is one schema
definition file (SDF) in XML format for every administrative object. The name of the
XML file is the symbolic name of the administrative object. For example, the SDF for
policy “RTS Cancelled” is named policy_RTSCancelled.xml. Each file includes
everything needed to create or update the definition in the ENOVIA product to the
newest version.
Since some administrative objects rely on other administrative objects (such as types
requiring attributes, etc.), all MQL commands are parsed to be sure that prerequisites
exist. If a required object is missing, the schema installer will not attempt to add it to
a definition.
2. Schema Manifest Files (SMF)
These files are found in the SchemaManifest directory. There is one manifest file in
XML format per application schema. Each manifest file lists symbolic names of the
administrative objects required by its respective application.
3. Schema Mapping File
This is a single file called SchemaMapping.xml found in the SchemaManifest
directory. This file keeps information about all the available application schemas,
their order, and prerequisite details. There is a section for each schema category that
includes the application name, SMF file name, display details (show/hide and order),
Conversion Manifest File (CMF) file, if any, and prerequisite schema.
4. Conversion Manifest Files (CMF)
These files are found in the Conversions directory. Conversions directory will also
have all the conversion programs that need to be run. Generally there is no need to
work with these files.
These four kinds of files are overwritten intentionally whenever a new version is installed.
This is the out of the box xml file area. You should use the customschema directory for any
changes you want to implement.
Adding Custom
Schema
To install custom schema, you should first create a staging area by running the Schema
installer, choosing the advanced setup option, and then choosing to Install to Staging area
only. This way you will get with all the necessary files and directories for customizing in
the CustomSchema directory which has two subdirectories:
•
SchemaDefinition to hold custom SDFs.
•
SchemaManifest to hold custom SMFs and SchemaMapping.xml file.
During installation, the schema installer parses all the files in these directories looking for
any customization.
Custom Schema Manifest Files
Custom SMF files should only contain changes from the out-of-the-box SMF file; that is,
they should not include all the administrative objects again. Use the Add or Exclude
sub-nodes for each administrative type. For example:
- <SchemaManifest>
<ApplicationName>Custom Application</ApplicationName>
- <attribute>
<Add>
attribute_PartType
attribute_PartNature
Chapter 14: Installing Business Process Services™
359
</Add>
<Exclude>
attribute_PartClass
attribute_PartSubclass
</Exclude>
</attribute>
...
In the above example, two attributes are added to the Custom Application, and two
attributes (which already existed or were to be added by a different XML manifest file) are
excluded (will not be installed).
For each add item you need a Schema Definition File. Items that are excluded are
prevented from being installed. However if they already exist in the database, they are not
removed.
The <ApplicationName> node value from the Schema Manifest file must have a matching
<Name> entry in the SchemaMapping.xml file.
Custom Schema Manifest File
-<SchemaManifest>
<ApplicationName>Custom Application</ApplicationName>
.
.
.
Custom Schema Mapping File
-<SchemaMapping>
-<SchemaManifest>
<Name>Custom Application</Name>
.
.
.
Custom SchemaMapping File
If you want to add custom schema or change the order or prerequisites of the schema, you
need a custom SchemaMapping file (named SchemaMapping.xml and located in the
CustomSchema/SchemaManifest directory). This file will have a SchemaManifest node
for each application that has a corresponding Custom SMF file, or a node for each
out-of-the-box SMF file that you want to customize. The custom SchemaMapping.xml file
must follow the same syntax as the out-of-the-box SchemaMapping.xml file.
For example, this SchemaManifest node is for a new Custom Application to be installed:
<SchemaManifest>
<Name>Custom Application</Name>
<FileName>SchemaManifest_CustomApplication.xml</FileName>
<Order>2</Order>
<Display>Yes</Display>
<Conversions />
<PreRequisiteSchema />
</SchemaManifest>
In this node
360
•
the Custom Application must be defined in the SchemaManifest file named
SchemaManifest_CustomApplication.xml, which must be in the /CustomSchema/
SchemaManifest directory
•
Custom Application will be the second schema choice listed in the schema chooser.
•
no conversions need to be run to support the schema.
ENOVIA Live Collaboration Installation Guide
•
the schema does not have an prerequisites.
The next node example modifies Application Common schema, so that it is now a choice
to be installed. This schema is normally automatically installed when BPS schema is
installed without being a choice in the schema list.
<SchemaManifest>
<Name>Application Common</Name>
<FileName>SchemaManifest_AppsCommon.xml</FileName>
<Order>3</Order>
<Display>Yes</Display>
<Conversions />
<PreRequisiteSchema>Business Process Services</
PreRequisiteSchema>
</SchemaManifest>
In this node
•
the SchemaManifest_AppsCommon.xml file is in the /SchemaManifest directory (not
the CustomSchema/SchemaManifest directory).
•
Applications Common will be the third schema choice in the schema installer.
•
no conversions need to be run to support the schema.
•
Business Process Serivces schema selected for installation (if not, the Applications
Common schema will not display in the schema list).
The last node is an example of removing out-of-the-box schema. The flag Remove =
“Yes” indicates that the specified schema needs to be removed from the install list:
<SchemaManifest Remove=”Yes”>
<Name>All Applications</Name>
<FileName>SchemaManifest_BusProcApps.xml</FileName>
<Order>4</Order>
<Display>Yes</Display>
<Conversions>BusProcAppsConversion.xml</Conversions>
<PreRequisiteSchema>Business Process Services</
PreRequisiteSchema>
</SchemaManifest>
You may want to remove a schema manifest to make sure it will not be installed. In the
above example, the “All Applications” prompt (UNIX install) or checkbox (Windows
install) will not display, so the person installing the software cannot accidentally install it.
When the SchemaInstaller is run, it merges the schema listed in the out-of-the-box
SchemaMapping.xml file (in the SchemaInstaller/SchemaManifest directory) with those
listed in the custom SchemaMapping.xml file (in the CustomSchema/SchemaManifest
directory) to build the list of schema choices for installation.
Using the above example nodes as the custom schema manifest, the SchemaInstaller
shows this list of schemas:
•
Business Process Services
•
Custom Application
•
Application Common
Business Process Serivces is defined in the out-of-the-box SchemaMapping file, “All
Applications” was removed by the custom mapping file, Custom Application was added
by the custom mapping file, and Application Common, which is normally installed but not
displayed in the list, is displayed based on the custom mapping file.
Note that the <Order> node must be unique. If more than one node has the same order
number only one of the options will be presented during installation.
Chapter 14: Installing Business Process Services™
361
Custom Schema Definition Files
For new schema to be added, the custom SDF files use the exact same format as the
out-of-the-box files. However, if you want to modify existing schema you only need to
include the changes. For example:
<SchemaDefinition>
<AdminType>type</AdminType>
<OriginalName>Part</OriginalName>
<SymbolicName>type_Part</SymbolicName>
<VersionHistory Version=”9-2-0-0” Skip=”Yes”>
<CommandInfo>
<Command Type=”MQL”>
<![CDATA[
modify type “<SYM>type_Part</SYM>
add trigger changeowner action
emxTriggerManager input “TypePartChangeOwnerAction”
]]
</Command>
</CommandInfo>
</VersionHistory>
</SchemaDefinition>
When custom SDF files are in place, the schema installer merges the changes with the out
of the box definition giving the custom file first priority:
•
If custom SDF has a skip flag set the whole version install is skipped.
•
If both SDF files have VersionHistory nodes for same version, the section from the
custom SDF file is used.
•
If custom SDF file has additional VersionHistory it is processed.
When the installer builds the list of SDF files to install, it uses the out-of-the-box and the
custom schema manifest and schema mapping files to determine which SDFs will be in
the list.
For example, the installer builds a list of what to install based on the SchemaMapping.xml
and SchemaManifest files in the SchemaManifest directory. Then, the installer looks at the
custom SchemaMapping.xml file, which includes this node:
<SchemaManifest>
<Name>Custom Application</Name>
<Filename>SchemaManifest_CustomApplication.xml</Filename>
.
.
.
</SchemaManifest>
The installer then looks in the SchemaManifest_CustomApplication.xml file (in the
CustomSchema/SchemaManifest directory). That manifest file must have the
<ApplicationName> node defined as “Custom Application”.
The custom schema manifest file contains these attribute nodes:
- <SchemaManifest>
<ApplicationName>Custom Application</ApplicationName>
- <attribute>
<Add>
attribute_PartType
attribute_PartNature
</Add>
<Exclude>
attribute_PartClass
362
ENOVIA Live Collaboration Installation Guide
attribute_PartSubclass
</Exclude>
</attribute>
...
The installer then adds the schema definition files for the Part Type and Part Nature
attributes (custom attributes to be added must have SDF files in the CustomSchema/
SchemaDefinition directory). The installer then removes the Part Class and Part Subclass
attributes from the list, which were in the list as defined by another schema manifest file.
Installing Schema
with the Schema
Installer
To install schema with stand-alone schema installer on UNIX
1. Change to the directory named “install” under the distribution directory you used
when you first installed the framework. Run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup.SchemaInstaller
2. Choose the Installation Type from the following menu:
-----------------------------------------------------------Choose Installation Type
-----------------------------------------------------------1. Standard (Recommended)
2. Advanced
Select option (1-2) [1]?
Choose option 1 for the recommended Standard installation.
Choose option 2 to change the default settings for the prompts in step 6.
3. Choose the directories for the installation to use.
Choose Directories
-----------------------------------------------------------Enter distribution directory path []?
Enter build script directory path []?
Enter eMatrixServlet(RMI) installation directory path []?
The distribution directory defaults to the directory above the current directory and
you should be able to accept the default by typing enter (or type in a new path as
required).
The build script directory is the path where the scripts that build the application in
the database are placed. If you specify a directory that does not exist, the setup
program will create the directory.
The RMI installation directory is the path that contains the ENOVIA collaboration
server installation.
4. Tell the setup program where the Schema Customization directory is located.
Enter custom schema directory path [/Apps/SchemaInstaller/
CustomSchema]?
5. Tell the setup program where MQL is (application scripts) and the user name and
password for a user that has Business and System Administrator privileges, such as
creator. If the user has no password, accept the default.
Specify Matrix Administration Parameters
------------------------------------------------------------
Chapter 14: Installing Business Process Services™
363
Enter
bin]?
Enter
Enter
directory path for Matrix application scripts [/usr/
/app/mx10
Administrator user for Matrix Business ? [creator]?
Administrator password ? [NONE]?
6. If you selected the Advanced option in step 2, you are prompted for the following.
The Standard option accepts the defaults:
Advanced Install
-----------------------------------------------------------Do you wish to install to staging area only & Don't update
database ? [no]?
Do you wish to undo the whole Framework transaction in case
of failure [yes]?
Install to staging area only. Don’t update database—The default is no, which
means after you complete the installation, the installation copies all files to the staging
area and runs the installation scripts to update the database. If you want to copy files
to the build script directory only and run the installation scripts later, enter yes. When
you’re ready to run the installation scripts, use MQL to run the
installFrameworkVERSION.tcl file, located in the framework directory. To create log
and error files, use the -stderr and -stdout MQL options.
Undo whole transaction in failures—The default is yes. Undoing all transactions
makes it easier for you to correct problems with the new installation without
introducing problems into your existing setup. The log file for the framework lists all
transactions even if they are undone.
You should only change this option, allowing transactions to proceed even when there
are errors, if you know how to correct the error or if you are just installing for testing
purposes.
7. At the next prompts, enter the names of the Data and Index table spaces for the
eService Production vault. For non-Oracle databases, the values must be the same.
Specify Table Space for eService Production vault
----------------------------------------------Enter Data Table Space? [NONE]?
Enter Index Table Space? [NONE]?
The eService Production vault is the vault that will be used for production data.
Consult your Database Administrator for information about the table space names
used.
If you do not specify a table space name, the tables and indexes for the product vault
will be created in the database’s default tablespace, which may not be sized
appropriately for production data storage.
For Oracle, if you specify only an Index Table Space, the Data Table Space will
default.
8. You are asked to confirm your choices and click 1 to continue, 2 to Cancel.
If you continue with the installation, the system creates installation directories, copies
files to the directories, and builds the script files. A file named
installSchemaInstallerVERSION.tcl is created in the directory you specified for the
build scripts. VERSION is the software version number, such as V6R2011x.
Then the setup program runs the installation scripts (unless you chose not to update
the database in the Advanced setup).
364
ENOVIA Live Collaboration Installation Guide
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
9. You are then asked what schema to install:
Schema Install
-----------------------------------------------------------Do you wish to install All Application schema [yes]?
All Applications option includes schema for all ENOVIA products. The schema for
BPS is automatically installed whether or not you install the application schema.
The list may also include applications defined in a custom SchemaManifest.xml file,
and may have removed one or more of the default schema (not recommended).
If you are upgrading a database from previous releases, you must choose to install all
application schema.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
10. If errors were encountered and you chose to undo transactions in case of errors, the
setup will have undone all changes. Check the files named
installSchemaInstallerVERSION.log and SchemaChangesMQLVERSION.log in
your installation script directory to get details about errors and to see exactly what
items were added and/or modified. If there are no errors, you may still want to review
the log files to see if any items were renamed due to name collisions.
11. If you have backups of customized properties files, you’ll need to compare your
customized files with the new files from the updated version. Either update the new
files with your customizations or update your customized files with any new settings.
To install the with stand-alone schema installer on Windows
1. Run setup.exe from apps\Framework\VERSION\SchemaInstaller.
2. At the Welcome frame, click Next.
3. At the Installation Type prompt, check the type of install you want to perform:
Standard (Recommended)—Use this option for all standard installations. When you
choose this option, the installation will undo all transactions if it encounters problems.
You can still use the log files to find out what transactions were attempted and to
diagnose the errors. The standard installation also automatically runs the installation
scripts after copying files to the staging area.
Advanced—Choose this option only if you want to allow the installation to proceed
even if errors occur or if you only want to copy files to the staging area now and run
the installation scripts later. If you choose this option, an Advanced Options prompt
displays at the end of the installation wizard, allowing you to change these options
from their default. (See step 9)
Click Next.
4. The Script Path frame asks where to put the scripts that build the application in the
database. The default is MATRIXHOME\framework, where MATRIXHOME is the
directory where ENOVIA Live Collaboration Server is installed. You can select a
different location using the Browse button. The MATRIXHOME directory contains the
connection file that points to your database. After specifying the directory, click Next.
Chapter 14: Installing Business Process Services™
365
5. Enter the directory (or use Browse button) where any custom schema exists. Click
Next.
6. At the Super User/Password frame, enter the User and Password that has Business
and System Administrator privileges, such as creator. If the user has no password,
leave the Password box blank. Click Next.
7. Enter the name of the bootstrap file that points to the database in which you want to
install the schema. This bootstrap file must already exist in the ENOVIAHOME
directory. When you are done, click Next.
8. At the next frame, enter the names of the Data and Index table spaces for the eService
Production vault. For non-Oracle databases, the values must be the same.
The eService Production vault is the vault that will be used for production data.
Consult your Database Administrator for information about the table space names
used. If you do not specify table space names, the tables and indexes for the product
vault will be created in the Oracle user’s default tablespace, which may not be sized
appropriately for production data storage.
Click Next.
9. If you chose the Advanced option in step 4, the Advanced Options prompt opens.
Choose the options you want based on the descriptions below.
Install to staging area only. Don’t update database—This option is unchecked by
default, which means after you complete the installation wizard, the installation
copies all files to the staging area and runs the installation scripts to update the
database. If you want to copy files to the staging area only and run the installation
scripts later, check this option. When you’re ready to run the installation scripts, run
the installFrameworkVERSION.tcl file, located in the framework directory. To create
log and error files, use the -stderr and -stdout MQL options.
Undo whole transaction in failures—This option is checked by default. Undoing all
transactions makes it easier for you to correct problems with the new installation
without introducing errors into your existing setup. The log file for the framework
lists all transactions even if they are undone. If the transactions are undone, you can
use the log file to identify the error.
You should only uncheck this option, allowing transactions to proceed even when
there are errors, if you know how to correct the error or if you are just installing for
testing purposes.
10. Enter the location of the Java Development Kit (JDK) directory. You can click Browse
to select the directory, then click Next.
11. Specify the Schema to install by checking the boxes of the options you want.
All Applications option includes schema for all ENOVIA products. The schema for
BPS is automatically installed whether or not you install the application schema.
The list may also include applications defined in a custom SchemaManifest.xml file,
and may have removed one or more of the default schema (not recommended).
If you are upgrading a database from previous releases, you must choose to install all
application schema.
Click Next.
12. You are asked to confirm your choices. Click Yes to continue, No to cancel.
If you clicked Yes to install the schema, the Setup program:
366
ENOVIA Live Collaboration Installation Guide
•
Copies install scripts to the selected directory. While the files are copied, a
progress meter displays the current files being copied and the percent completed.
Files named installSchemaInstallerVERSION.log and
SchemaChangesMQLVERSION.log are created in the SchemaInstall
directory.VERSION is the software version number, such as 10-6. (If you used
the Advanced install option and chose not to run the install scripts, the setup
performs this step only and the remaining steps are not performed.)
•
Launches MQL in the background and runs the install scripts.
•
Displays a progress meter, which shows you the files being run and the percent
completed. If you do not see the progress meter, the installation is not working
correctly. Cancel the installation and re-run it, making sure you specify a valid
bootstrap file name.
If you clicked No, the Setup program displays a message. See step 13.It may take
several minutes to run all the scripts. If you have an extensive database in place, it
could take much longer.
13. When complete, you receive a message telling you either the setup encountered errors
or the setup is complete. If errors were encountered, the setup will have undone all
changes (unless you used the Advanced install and chose not to undo the
transactions). Using a text editor such as WordPad, check the files named
installSchemaInstallerVERSION.log and SchemaChangesMQLVERSION.log, as
well as installFrameworkVERSION.log and installFrameworkVERSION.err in your
installation script directory to get details about errors and to see exactly what items
were added and/or modified. If there are no errors, you may still want to review the
log files to see if any items were renamed due to name collisions.
14. If you have backups of customized properties files, you’ll need to compare your
customized files with the new files from the updated version. Either update the new
files with your customizations or update your customized files with any new settings.
Refer to the application administrator’s guides for any application specific setup issues.
Refer to the Studio Modeling Platform documentation set for FCS setup, deployment
settings, and server setup and diagnostics.
Chapter 14: Installing Business Process Services™
367
Installing to Large Databases
The BPS installation routines are capable of upgrading from any previous BPS version to
the current version being installed. During this install process, transaction boundaries are
placed around each version upgrade so that if any problems are encountered during the
upgrade, the database is left in a consistent and known state (i.e. at some predefined
version). During some of the version upgrades, the transactions can become very large and
take a long time to complete. In addition, these large transaction boundaries consume
resources when attributes are added to existing types that already have a large number of
instantiated objects. These and other related database operations are capable of consuming
so many system resources that the BPS installation routines fail to complete or, at a
minimum, take an unacceptably long time to complete.
To solve this issue, you can run a preprocessing script that enables the more resource
intensive operations to be performed individually and outside of large database
transactions. This script is included with the BPS installation, in the framework/Common
directory. You should run the script before updating the database so use the Advanced
install option and choose to install to the staging area only. Then after running the script,
update the database by running the install script manually.
The number of instantiated objects that is considered large is tens of millions. However,
any type or relationship with over 100,000 instantiations will benefit significantly from
running this preprocessing script.
This section contains the following topics. Make sure you review all sections before
running the script:
About the Script
Before Running the Script
Running the Script
Database Considerations
About the Script
These are the database operations that can consume large amounts of system resources and
that are run in the preprocessing script:
•
Mod Type Add Attr: Adding an attribute to a type that has a large number of
instantiated objects.
•
Mod Type Remove Attr: Removing an attribute from a type that has a large number
of instantiated objects.
•
Mod Rel Add Attr: Adding an attribute to a relationship that has a large number of
instantiated objects.
•
Mod Rel Remove Attr: Removing an attribute from a relationship that has a large
number of instantiated objects.
By default, the preprocessing script addresses all of these items with modification
statements. You can comment out specific statements that you do not want to run or you
can run them in batches.
The script contains all the modify type and relationship MQL commands that adds
attributes to them from 8-0-0-0 to the latest version to be installed.
368
ENOVIA Live Collaboration Installation Guide
1. For each MQL command in the script:
a ) If attribute to be added doesn't exists then
i.
Add attribute
ii.
Register Attribute with admin property name
iii. Stamp attribute version to the version of
Framework at which Attribute is added
iv.
Stamp application property to FrameworkFuture
b ) End if
c ) Modify Type Or Relationship with Attribute.
d ) End if
2. End For
Before Running
the Script
The LargeDBSchemaUpdate.tcl script performs the lengthy database operations outside
the normal installation transactions. You can run this script prior to installing BPS in
whole or in part depending on your system availability restrictions. The script is written in
such a way that you can run upgrade commands for specific versions and commands.
Prerequisite steps to perform before running the script
1. As always before upgrading, make sure your database is backed up and you have a
good recovery. To keep the user base off during the upgrade, change the “MATRIX”
schema password to something new, create a new bootstrap with the new password,
and then do the upgrade from there.
2. Make sure you have upgraded to the Matrix10 or higher Platform according to the
instructions in the Program Directory.
3. To get the script, run the BPS installation in the Advanced mode and choose to copy
to the staging area only. The script installs to
SERVER_INSTALL\Apps\Framework\<version>\Common\.
4. In consultation with your Oracle Database Administrator and/or ENOVIA Customer
Support, make temporary changes to database settings to accommodate the large
transactions. Some areas that you may want to change are listed below. For more
details and examples, see Database Considerations.
•
Disable redo logs at the tablespace level or create more and much larger logs
because they will fill up quickly.
•
Disable LOG_CHECKPOINT_INTERVAL and
LOG_CHECKPOINT_TIMEOUT.
•
Disable ARCHIVE LOG operations.
•
To avoid sorting to disk, increase Sort_Area_Size substantially and increase the
TEMP tablespace accordingly.
•
Set DB_BLOCK_BUFFERS (Oracle 8i), DB_CACHE_SIZE (Oracle 9i), and
SHARED_POOL_SIZE (8i and 9i) high depending on system RAM and size of
database.
Chapter 14: Installing Business Process Services™
369
•
In Oracle 8i, set OFFLINE all production rollback segments and create a unique,
large rollback segment tablespace with very large extent sizes (200m). Within
that new tablespace, create at least 2 very large rollback segments with
initial=next=200MB, min=5.
•
Make sure this large rollback segment tablespace has several large data files.
•
In Oracle 9i, use the undo tablespace and auto undo segments as an alternative to
the rollback segment concept. Set undo_retention=10800 and increase the
initialization file.
If you do not want to run all commands for all versions at once
•
Open LargeDBSchemaUpdate.tcl in a text editor and use the following guidelines to
comment out or remove the commands you do not want to execute during this run of
the install script. BPS installs this script in
SERVER_INSTALL\Apps\Framework\<version>\Common\. The only reason not to run the entire script at once is if you have limited time to run them and want
to run them incrementally. At some point, the commands for all versions must be run.
•
To run upgrade commands for specific BPS versions only, comment out the line
that executes the command for the versions you do not want to execute for this
run of the script. Comment out a line by adding a # to the beginning of the line.
The lines for each version are at the end of the Tcl file and begin with “set
mqlret”. For example, if you do not want to run the commands for version
8-0-0-1, comment out the set mqlret line for that version line as follows:
# executing modify commands for 8-0-0-1
# set mqlret [emxExecCommands ${lCmd8-0-0-1}]
Note that you don’t need to comment out upgrade commands for versions that
have already been run. For example, if you are installing v10.0.1.0 over a 9-5-5-0
version, the routines will detect that upgrade commands for versions prior to
9-5-5-0 have been run and they will not run again, even if they are not
commented out.
•
If you do not want to run a specific modify command for a specific type or
relationship, make a backup copy of the script. Then in the original version of the
script, delete that type or relationship from the build list for that version. For
example, suppose you don’t want to run the version 10-0-0-0 modify command
for the Person type. Delete the line highlighted in blue below:
# building list of modify commands for 10-0-0-0
set lCmd10-0-0-0 [list \
$type_ProjectSpace1 \
$type_ProjectConcept1 \
$type_ProjectTemplate1 \
$type_Person1 \
Running the Script
Do not run the script until you complete the steps in Before Running the Script.
You can run LargeDBSchemaUpdate.tcl through MQL or through the command line on
Unix or Windows. When using MQL, log messages appear in the MQL window. When
using the log file, log messages can be saved to a log file. Both procedures are listed
below, where:
•
370
SUPER_USER = User who has all access.
ENOVIA Live Collaboration Installation Guide
•
SUPER_USER_PASSWORD = Password of super user.
•
MQL_PATH = Path where MQL exists.
•
LOG_FILE = Name of log file including full path.
•
ERROR_FILE = Name of error file including full path.
To run the script using MQL
1. Start MQL.
2. Set the context to a Super User. For example:
Set context user <SUPER_USER> password
<SUPER_USER_PASSWORD>;
3. Execute the script using the command:
run <SCRIPT_PATH>/ LargeDBSchemaUpdate.tcl;
All log messages display in the MQL window.
As the V6 installers use the MQL executable delivered in the Live Collaboration Server
(server) directory to perform their needed installation steps, they no longer require a
Studio Modeling Platform (studio) installation to be present, and therefore do not update
the studio environment. If the studio installation is to be used to perform operations that
depend on server-delivered jars, those jars must be copied from the server directories to
the corresponding studio directories.
To run the script using the command line and store log messages in a log
file
•
If using Windows, start the Command Prompt and enter:
<MQL_PATH>\mql -c "set context user <SUPER_USER> password
<SUPER_USER_PASSWORD>; run <SCRIPT_PATH>\
LargeDBSchemaUpdate.tcl" -stdout:<LOG_FILE>
-stderr:<ERROR_FILE>
•
If using Unix, start the Command Tool and enter:
<MQL_PATH>/mql -c "set context user <SUPER_USER> password
<SUPER_USER_PASSWORD>; run <SCRIPT_PATH>/
LargeDBSchemaUpdate.tcl" 1><LOG_FILE> 2><ERROR_FILE>
After running the script
1. If you did not run the entire script, uncomment or add back the commands that you
did not run. Re-run the script until all commands for all versions are run. There is no
harm in leaving in a command that has already been run. The script will skip a
command if the modification has already been made.
2. When you are finished running the script, reset any changed database settings back to
production values.
3. After you have run all the commands, install new version of BPS. Installing after
running this script might generate Skipping/Syncing warning messages in the log for
attributes added in the script.
Database
Considerations
This section contains specific examples of database settings you may want change before
running the LargeDBSchemaUpdate.tcl script. The appropriate settings depends on your
database size and configuration and system resources so consult with ENOVIA Customer
Support and your Database Administrator for the changes appropriate for your system.
Chapter 14: Installing Business Process Services™
371
These changes are temporary and needed only when running commands with large scale
transaction boundaries. They should be changed back after running the script.
Redo Logs
Disable logging at the tablespace level and then turn them back on after running the script.
Alternatively, create more and larger logs because they will fill up quickly. Should an
existing database have four 10m redo logs, you could drop them one by one, replacing
each one with a 200m redo log. Then create two additional logs.
More on Redo Log Activity
Increase the log_buffer size, but always keep the log_buffer size to be no more than 5% in
size of the sum of the redo logs. So for 5 * 200m redo logs, set log_buffer = 50m.
Disable LOG_CHECKPOINT_INTERVAL and LOG_CHECKPOINT_TIMEOUT. For
example, set them to a very high number such as 18000000 or 10000000 respectively.
Disable ARCHIVE LOG operations.
Sort_Area_Size and the TEMP tablespace
The goal is to avoid sorting to disk.
An installation with a sort_area_size set to 2097152 or 2m might change it to 200m,
depending on how much RAM is available on the box.
For the TEMP tablespace, the extent sizing calculation is usually:
N*sort_area_size + db_block_size
For a 2048k (2097152) sort_area_size and an 8k db_block_size, the extent setting would
be 2056k. So before running the tcl script, the TEMP extent should be changed to
200m+8k or 204808k.
Buffer, Cache, and Pool Size
Oracle 8i: DB_BLOCK_BUFFERS
Oracle 9i: DB_CACHE_SIZE
Oracle 8i and 9i: SHARED_POOL_SIZE
Set both values high. For a single Oracle instance on a database server, then assign up to
50% physical memory. If database server has more than one instance or other applications,
assign largest amount of physical memory without causing system to go to swap. Settings
of 1GB and higher for Oracle 32bit software and higher for Oracle 64 bit software have
been noted at large installations for such large operations. This is entirely dependent on
system RAM and size of the database.
372
ENOVIA Live Collaboration Installation Guide
The Installation Process
This section describes the installation process for Business Process Services and other
ENOVIA products. It includes a high level description of the files used during installation;
the procedures that are called during installation, including how the system handles name
collisions and updates to existing objects; file naming conventions; and the directory
structure for installed files. This information is especially important to know if you plan on
configuring the installation process. For information on the prerequisites for installing the
system and for instructions on how to install the various components, see the Program
Directory for the given version of your ENOVIA product.
Installing to a
Populated
Database
(Released
Versions Only)
Business Process Services must be installed before installing other ENOVIA products.
BPS adds most of the administrative objects used in the applications, including all types,
attributes, policies, relationships, roles, groups, persons, vaults, and stores. The
installation process also manages issues that may occur when installing over a populated
database, such as:
•
Identifying previous versions of administrative objects that need to be updated.
•
Identifying previous versions of administrative objects that should not be updated
because they have been modified (updating might override modifications).
The above check for whether objects have been modified is not available for this release.
•
Preventing naming conflicts by renaming objects in the framework that have the same
name as an existing object (not the same symbolic name though). The installation
renames the framework object using the format eService[version number]~[original
name].
•
Identifying existing administration objects with the same symbolic name as an
installing object. If the installation is attempting to add the object, it skips the add
command.
•
Backing up program, administration, business object, and UI components
•
Schema Changes.mql.
Only RELEASED versions of the framework support the upgrade process listed above.
Customers who receive PRE-RELEASED software as part of a Beta and/or Customer
Sponsorship program are given the pre-released software for evaluation purposes only.
The installation program will not automatically upgrade databases from a Beta version to
a released version. Installing pre-released versions of the framework requires that the
database be empty.
MatrixIniDefaults
Program
The MatrixIniDefaults program contains Matrix ini settings that apply to the entire
system. The BPS installs this program to implement settings that it requires. If you install
the framework and the database already contains a MatrixIniDefaults program (from a
previous framework version or because the administrator created one to implement system
settings), the installation copies the existing program to a program called
MatrixIniDefaults_VERSION, for example MatrixIniDefaults_10-0-0-0, before it installs
Chapter 14: Installing Business Process Services™
373
its own copy of the program. You should compare the copy with the new version and copy
over any settings that you had in the existing program.
If you make changes to the date/time settings, make sure they are in sync with the
corresponding framework properties as described in “Data/Time Format Properties” in
the ENOVIA Live Collaboration Administrator’s Guide.
Business Process
Services Version
Must Be Correct
for Applications
It is critical that ENOVIA products use the correct Business Process Services and schema
version, as specified in the Program Directory for the given release. Having the correct
installation is key to getting the applications to work correctly and for future upgrades to
work right.
Preventing
Custom Pages
from Being
Overwritten
During Upgrades
The ENOVIA Live Collaboration Server contains a filter class that allows requests from
ENOVIA products to check for a prefixed file name so that you can store custom resources
(JSP, HTML, and image files) with alternate filenames to prevent them from being
overwritten on subsequent application installs. In version 10.6.1, the ability to have
multiple prefixes defined was added. This allows you to keep various customization,
accelerator, or integration files easy to identify.
You can also implement a custom directory to store custom files; however, when using
custom directories, there are certain jsp directives that will result in run-time (vs. compile
time) errors if the relative pathing isn't correct. Therefore, it is recommended that custom
prefixes are used instead of a custom directory. In Version 10.7, use of a custom directory
is not supported by default — web.xml configuration is required.
The naming convention prefix(es) are contained in the web.xml file for the application
server. If the custom JSP filter is enabled, the filter first looks for a page having a name
that is the concatenation of any of the defined prefixes and the name of the file requested.
If no prefix is set or the page is not found, it looks for the originally requested page.
For example, the filter first looks for an Engineering Central file with all specified prefixes
under /engineeringcentral/.If not found it looks for the originally requested file
name in /engineeringcentral/.
Implementing the custom JSP filter involves simple changes to the web.xml file for your
application server’s WAR file.
To enable the custom JSP filter
Open the web.xml file, and in the custom filter section, remove the two multiline
comments and make them single line comments. You can do this by deleting the two lines
having only --> and pasting the --> at the end of the comment’s first line.
The custom filter section should look similar to the following, with the modified single
line comment lines shown in boldface. The following shows defined prefixes which are
not defined in the web.xml as installed:
<!--
Custom filter -->
<!-- Custom filter class -->
<filter>
<filter-name>CustomFilter</filter-name>
<filter-class>com.matrixone.servlet.CustomFilter</
filter-class>
374
ENOVIA Live Collaboration Installation Guide
</filter>
<!-- Custom filter definitions -->
<filter>
<filter-name>CustomFilter1</filter-name>
<filter-class>com.matrixone.servlet.CustomFilter</
filter-class>
<init-param>
<param-name>ematrix.customFilePrefix</param-name>
<param-value>emxLib_</param-value>
</init-param>
</filter>
<filter>
<filter-name>CustomFilter2</filter-name>
<filter-class>com.matrixone.servlet.CustomFilter</
filter-class>
<init-param>
<param-name>ematrix.customFilePrefix</param-name>
<param-value>emxFDA_</param-value>
</init-param>
</filter>
<filter>
<filter-name>CustomFilter3</filter-name>
<filter-class>com.matrixone.servlet.CustomFilter</
filter-class>
<init-param>
<param-name>ematrix.customFilePrefix</param-name>
<param-value>emxUCCnet_</param-value>
</init-param>
</filter>
<!-- Custom filter mappings -->
<filter-mapping>
<filter-name>CustomFilter1</filter-name>
<url-pattern>/common/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>CustomFilter2</filter-name>
<url-pattern>/common/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>CustomFilter2</filter-name>
<url-pattern>/engineeringcentral/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>CustomFilter3</filter-name>
<url-pattern>/common/*</url-pattern>
</filter-mapping>
<filter-mapping>
<filter-name>CustomFilter3</filter-name>
<url-pattern>/teamcentral/*</url-pattern>
</filter-mapping>
Chapter 14: Installing Business Process Services™
375
The above web.xml defines 3 filters (CustomFilter1, CustomFilter2, and CustomFilter3).
Each of these filters has its own prefix and mappings defined. All three filters will
potentially intercept requests for pages with /common/… in the URL. The request will
first be processed for CustomFilter1 and if no alternate page exists, CustomFilter2 is used,
and so on until all have been checked. If no alternate page exists for any of the defined
customFilePrefixes, the originally requested resource is supplied. If an alternate page is
found with any of the prefixes, that resource is supplied and the checking is stopped.
Therefore, the order the prefixes are defined dictates the precedence of the filters. That is,
in the example above, CustomFilter1 (emxLib_ ) is first, CustomFilter2 (emxFDA_) is
second, CustomFilter3 (emxUCCnet_) is third and the originally requested resource is
fourth for any resource requested in the /common directory.
To use a custom directory for custom JSP pages
It is recommended that if you will be creating your own custom JSP pages, that you use
the custom prefix approach described above. However, if you need to use a custom
directory for backward compatibility, you can add the following bolded lines into the
custom filter section of the Web.xml file:
<filter>
<filter-name>CustomFilter</filter-name>
<filter-class>com.matrixone.servlet.CustomFilter</
filter-class>
<init-param>
<param-name>ematrix.customDirName</param-name>
<param-value>/custom</param-value>
</init-param>
</filter>
When using custom dirs, there are certain jsp directives that will result in run-time (vs.
compile time) errors if the relative pathing isn't correct. Therefore, it is recommended that
custom prefixes are used instead of a custom directory.
How the
Installation
Manages Previous
Versions
The framework installation handles versions named with any string, including version
names with more than 4 digits (for example, 9.4.1.1.0.1) and names with letters (for
example, 9.4.acmecorp). It also handles patches that are inserted into the version sequence
after subsequent versions have been released.
Each framework version installs a file called AppInfo.rul, which is located in
SERVER_INSTALL\Apps\Framework\<version>\Schema\. The
VERSION_LIST section of this file contains a list of all the framework versions in
sequence. The last version is the latest version of the framework. All install files and
routines refer to this file to get the latest version and version list. When each framework
and application version is installed, the install routines record the application name,
version, and installation date in a Version Log. This log is stored in the code section of
eServiceSystemInformation.tcl. For more information on this program, see “Programs” in
the ENOVIA Live Collaboration Administrator’s Guide.
The installation routines that handle version comparison and tracking work as follows:
1. Get versions in sequence from the VERSION_LIST section of AppInfo.rul file.
2. Check if framework is installed.
376
ENOVIA Live Collaboration Installation Guide
3. If framework is not installed, start installing from first version of framework in the
VERSION_LIST section of AppInfo.rul. After successful completion of each version,
make an entry in the Version Log (eServiceSystemInformation.tcl). For example, the
log for a new installation might look like this:
Framework 8-0-1-0 05-01-2002 09:41 AM
Framework 8-0-2-0 05-01-2002 09:42 AM
Framework 9-0-0-0 05-01-2002 09:43 AM
Framework 9-0-0-1 05-01-2002 09:43 AM
Framework 9-0-1-0 05-01-2002 09:44 AM
.
.
.
Framework 9-5-1-2 05-01-2002 09:50 AM
PartStructure 9-5-0-0 05-01-2002 10:15 AM
PartDefinition 9-5-0-0 05-01-2002 10:16 AM
ProfileManagement 9-5-0-0 05-01-2002 10:16 AM
EngineeringChange 9-5-0-0 05-01-2002 10:44 AM
4. If a previous version of the framework is installed, then:
a ) Get the version of the installed framework and list it in the Version Log. For the
date, enter UNKNOWN (because the new version has no way of knowing when
the installed version was installed). For example:
Framework 9-0-0-0
Framework 9-0-1-2
Framework 9-0-2-0
Framework 9-0-2-1
EngineeringChange
EngineeringChange
UNKNOWN
04-29-2002 11:23 AM
04-29-2002 11:24 AM
04-29-2002 11:24 AM
9-0-3-0 UNKNOWN
9-1-0-0 05-29-2002 11:24 AM
b ) Check if the installed version of the framework is in the VERSION_LIST section
of AppInfo.rul for the version being installed. This is a check to see if the version
being installed knows about the installed version. For example, the version being
installed might not know about a patch for a previous version that was released
after the installing version was released. Suppose a patch for version 9.5.1.2,
called 9.5.1.2.0.1, is released after version 9.5.1.4 is released. Versions 9.5.1.3
and 9.5.1.4 will not know about the patch.
If the installed version is in the installing version’s VERSION_LIST (the
installing version does know about the installed version), start installing the
framework from the very next version. After successful completion of each
version, make an entry in the Version Log.
If the installed version is not in the installing version’s VERSION_LIST (the
installing version does not know about the installed version), get the latest
version from the Version Log that is in the installing version’s VERSION_LIST
(get the latest version that the installing version does know about). Start installing
from the very next version. Using the example versions described above, suppose
you are installing 9.5.1.4 over the 9.5.1.2.0.1 patch, which the 9.5.1.4 version
doesn’t know about. The installing version checks the VersionLog and finds that
the latest version that is in its VERSION_LIST is 9.5.1.2. So it will begin
installing with version 9.5.1.3, leaving all the changes made by the patch intact.
Chapter 14: Installing Business Process Services™
377
How the
Installation
Handles Schema
Similarities
At the highest level, there are two ways an existing administration object might be similar
to an object being installed:
•
the administration object names are the same but their symbolic names are not; see
Name Collisions
•
the administration object symbolic names are the same; see Symbolic Name Matches
Name Collisions
A simple name collision is when a framework administration object has the same name as
a custom administration object in the database (an object that was never installed as part of
the framework). In this case, the symbolic names of the objects are not the same: either the
existing object has no symbolic name or its symbolic name is different from the
framework object’s. When the framework install program finds a name collision, it
renames the administration object it is installing using the format “eService[version
number]~[original name]”.
For example, suppose your database contains a Widget type and you are installing version
9.0.0.0 of the framework, which also contains a Widget type. When the framework
installs, it renames its Widget type to “eService9000~Widget”. It does not change the
type’s symbolic name.
After installing the framework, you can find any name collisions by looking at the
installation log file (see Installation Log File). For recommendations on resolving
collisions, see “Resolving Schema Similarities Between the Framework and Custom
Schema” in the ENOVIA Live Collaboration Administrator’s Guide.
Symbolic Name Matches
When the framework installation encounters an existing object that has the same symbolic
name as an object it is adding or modifying, it checks to see if the MQL command for the
object is an add or modify command. If it’s an add command, the installation skips the
command and logs the skip action in the log file.
If the MQL command is a modify command, the installation checks the existing object’s
Application property to determine if it’s a FrameworkFuture object. How the installation
proceeds depends on the value for this property and how the version number compares to
the version of the object being installed. There are two types of values for the Application
property:
•
378
Framework or anything other than FrameworkFuture—The object was installed by
the framework or is a custom object.
•
If the Version property on the existing object is less than the version for the object
to be installed (existing object is older than installing object), the installation
modifies the object.
•
If the Version property on the existing object is equal to or greater than the
version to be installed (existing object is same as or newer than installing object),
the installation skips the modify command.
•
If a new manifest file has been selected, the installation may modify the object.
ENOVIA Live Collaboration Installation Guide
•
FrameworkFuture—This is a special case in which the schema was flagged as a future
part of the framework. This only occurs when a customer works closely with
ENOVIA Engineering to add new schema. When schema is flagged as
FrameworkFuture, the Version property is also updated with the framework version
number the new or modified schema will appear in.
•
If the Version property on the existing object is less than the version for the
installing object (existing object older than the installing object), the installation
executes the modify command.
•
If the Version property on the existing object is the same as the installing object’s
version, the installation skips the modify command and changes the Application
property from FrameworkFuture to Framework to identify it as a framework
object. It then logs a message to the log file to indicate that the object has been
synced and the modify command skipped.
•
If the Version property on the existing object is higher than the installing object’s
version (existing object is newer than installing), the installation skips the modify
command and indicates the skipped command in the log file.
•
If a new manifest file has been selected, the installation may modify the object.
This table summarizes how the system handles symbolic name matches.
MQL
command
Application property on
existing object is:
Existing object’s
Version property is
less, equal, or greater
than installing
version?
Framework installation:
add
ANY
ANY
skips the add command because the
object already exists
log a message about the command being
skipped
may add if new manifest file has been
selected.
Chapter 14: Installing Business Process Services™
379
MQL
command
Application property on
existing object is:
Existing object’s
Version property is
less, equal, or greater
than installing
version?
Framework installation:
modify
Framework or any value other
than FrameworkFuture
(indicating a custom object)
less (existing object is older)
executes the modify command
equal
skips the command
may modify if new manifest file has
been selected.
greater (existing object is
newer)
skips the command
may modify if new manifest file has
been selected.
less (existing object is older)
executes the modify command
equal
skips the modify command, changes the
Application property to Framework, and
logs the object syncing and command
skip in the log file
may modify if new manifest file has
been selected.
greater (existing object is
newer)
skips the command and enters the skip in
the log file
may modify if new manifest file has
been selected.
FrameworkFuture
Installation Log
File
After installing the framework and schema, you can review these log files:
•
install[Framework or application][version number].log
•
installSchemaInstaller[version number].log
•
SchemaChangessMQL[version number].log
Framework\Application Installation Log File
A log file is created every time the installation file is run for the framework or for a
application. The file is called install[Framework or application name][version number].log
and is installed by default in SERVER_INSTALL\Apps\Framework\. For example,
the log file for the V6R2011x framework is called installFrameworkV6R2011x.log.
The file lists all the administrative objects added or modified during installation, objects
renamed due to name collisions, MQL commands skipped due to symbolic name
collisions, and error conditions. The log file shows messages generated for each
installation script that runs during installation. You can determine which program
generated the message by looking above the message until you find the line that lists the
program that was running.
380
ENOVIA Live Collaboration Installation Guide
This table describes the messages that can appear in the file.
Log Message
Condition
Action Performed by Installation
Currently Installed Applications
>None Installed
No application is installed in the
database.
Install application for first time.
Currently Installed Applications
>Application : A1 V1
>Application : A1 V2
Applications A1 of version V1 and A2 of
version V2 are already installed.
If application to be installed is same as A1
or A2 then update installed application
objects for latest version, else add new
application.
Now Installing
>Application : A1 V1
—
Start installing application A1 of version
V1.
Adding : program P1 V1
Program P1 is not present in the database.
Add program to database.
Modifying : program P1 V1
Program P1 with earlier version already
exists.
Modify program in the database to update
it to new version.
Exists : program P1
Program P1 with same or newer version
is already present in the database.
Do nothing.
Adding : adminType A1 V1
Administration object A1 is not present in
the database.
Add administration object to the database.
Renaming : adminType A1
Administration object with same name as
A1 is already present in the database.
Object is created by customer and not
installed by installation scripts.
Don’t change the administration object
present in the database. Instead install
object with the name formed by prefixing
previous name by string eService +
version_name.
Same Version: adminType A1 V1
Administration object A1 with same
version is present in the database.
Do nothing.
Modifying : adminType A1 V1
Administration object A1 is installed by
earlier version.
Update existing administration object to
make it compatible with new version.
Adding : itemDesc V1
Administration bus object not present in
the database.
Add administration object to the database.
Modifying : itemDesc V1
Administration bus object is already
installed by earlier installation script.
Update administration object by
modifying it for latest version.
Adding : Method T1 M1
Method M1 not present on type T1.
Add a new method.
Exists : Method T1 M1
Method M1 already exists on type T1.
Do nothing.
Removing : Method T1 M1
Method M1 is defined on type T1.
Remove method .
Adding : user U1
Sample user U1 not present in the
database.
Add a person.
Exists : user U1
Sample user U1 already present in the
database.
Do nothing.
Adding : itemDesc
Sample bus object not present in the
database.
Add sample object to the database.
Adding : workspace R1
—
Sets workspace for role R1.
Adding : workspace itemDesc V1
Toolset is not defined in current operating
workspace.
Add toolset in the operating workspace
for version V1.
Chapter 14: Installing Business Process Services™
381
Log Message
Condition
Action Performed by Installation
Modifying : workspace itemDesc
V1
Toolset is defined in current operating
workspace.
Modify toolset in the operating workspace
for version V1.
Cannot create type xxx not unique
type
This message should not appear
after version 9550.
There is an existing, custom
administration object with the same
symbolic name as an object being
installed.
Condition causes the installation to roll
back and creates many additional errors.
You need to unregister the existing
administration object.
Only for pre-9550 installations.
Cannot rename xxx as object
already exists with new name
There is an existing, custom
administration object with the same name
as the new name we are trying to use.
Condition causes the installation to roll
back and creates many additional errors.
You need to unregister the existing
administration object.
Skipping mql command for type T
version 9-0-0-0
Following command is skipped
mql add type T
There is an existing framework
administration object with the same
symbolic name as the object being
installed.
Add command is skipped.
type T already exists.
Following mql command skipped
mql add type T
There is an existing custom
administration object with the same
symbolic name as the object being added.
Add command is skipped.
Skipping mql command for type T
version 9-0-0-0
Following command is skipped
mql modify type T
There is an existing framework object
whose version is equal or greater to the
installing object’s.
Modify command is skipped
Syncing type T at version 9-0-0-0
There is an administration object with the
same symbolic name, Application
property of FrameworkFuture, and the
same Version property as installing
object.
Application property is changed to
Framework and modify or add command
is not executed
Schema Installation Log File
A log file is created every time the schema installer is run. The file is called
installSchemaInstaller[version number].log and is installed by default in the
SERVER_INSTALL\Apps\<version>\SchemaInstaller\ directory.
The file contains a section for each version of each schema installed (AEF, Team Central,
all other ENOVIA products, and any custom schema).
You may see Modifying messages for a version earlier than your currently installed
version. For example, your installed version is 9.5.5.1, but you see a modifying message
for version 9.5.0.0. This situation may occur if a prior conversion executed, but for some
reason did not update the version number for the object. The message here indicates that
the version has been modified, not that the conversion was run again.
382
ENOVIA Live Collaboration Installation Guide
This table describes the messages that can appear in the file. .
Log Message
Description
Currently Installed Applications
Lists the applictions that have already been
installed
Now Installing
>Application : SchemaInstaller
Running SchemaInstallerPrograms.tcl
The Schema Installer is running.
Adding : program P1 V1
Schema for the program/verion added.
Running
SchemaInstallerCustomPrograms.tcl
The schema for custom programs (defined
by the custom SDF, SMF, and mapping
files) is being installed
>Upgrading [version] [application]
Section for each application/version
containing the schema changes
> Adding : adminType P1 V1
Adding administrative objections for the
program/version P1/V1
>Modifying : admingType P1/V1
Modifying administrative objections for the
program/version P1/V1
>Modifying : workspace itemDesc V1
Toolset is defined in current operating
workspace.
MQL Schema Changes Log File
A schema changes log file is created every time the schema installer is run. The file is
called SchemaChangesMQL[version number].log and is installed by default in the
SERVER_INSTALL\Apps\<version>\SchemaInstaller\ directory.
The file contains the MQL code corresponding to the entries listed in the Schema Installer
log file.
Directory
Structure
Build scripts
The BPS installation program adds the following directories to the location specified as
the directory for placing the build scripts, usually the installation directory for ENOVIA
Live Collaboration.
SERVER_INSTALL\Apps\Framework\<version>\
| Common\
(All trigger programs common to all
applications; includes their utility programs)
| Common UI\ (Program and image files needed for the user
interface. Applet jar files are also located
there.)
| Doc\
(User’s guides and online help for the
Application Exchange Framework and the
applications. Online help for each application
is located in a subdirectory with the name of
the application. The user’s guide for the apps
and the framework are located in the pdf
directory. The common directory contains VCP
help. The javadoc directory contains javadoc
from the framework classes.
| Pixmaps\
(Graphics, .gif, files for icons and other
Chapter 14: Installing Business Process Services™
383
images)
(Tcl file that add administrative objects owned
by each application; also includes programs
used by the framework, such as the trigger
manager, atuomatic object creation program,
and the scheman variable mapping program)
| Store\
(Test store directory used for checking in
files; empty upon installation)
| UserInterface\
| Uninstall\
| UI\
| Backup\
\ ematrix\ (Any modified files are copied here using
the same directory structure as exists
under the staging directory.)
| Schema\
The installation program for each ENOVIA product adds a subdirectory under the
framework directory. Each application subdirectory contains the program files needed to
build the application. For example, the directory structure would look like this if the
Engineering Central application is installed.
SERVER_INSTALL\Apps\EngineeringCentral\<version>\
| AppsCommon\ (Program files for the Common Components
application)
| Common\
| Doc\
| EngineeringCentral\ (Program files for the Engineering
Central application)
| Uninstall\
| UI\
| Backup\
| ematrix\ (Any modified files are copied here using
the same directory structure as exists
under the staging directory.)
Application Server directories
When Web Interface is chosen during the framework installation, the installation program
creates a directory called “ematrix” under the staging directory of the Collaboration server
installation directory. The installation installs some files to this directory and creates
subdirectories for other files. When you install an ENOVIA product, the installation
program creates a directory under the ematrix directory using the name of the application.
All application-specific files for the application are copied to the directory. Directories for
the online help and user guide are also created. The following lists the directory structure
under the ematrix\ directory.
SERVER_INSTALL\STAGING\
| ematrix\
(JSP, JavaScript, and style sheet files related
to the Login, Logout, and Home pages. All other
component files are in the common
subdirectory.)
| classes\ (.jar files needed for the applications)
| common\ (All JSP files that belong to AEF and the
dynamic user interface components used for the
applications. Only BPS installs to the common
384
ENOVIA Live Collaboration Installation Guide
|
|
|
|
|
J2EE
Implementation
directory and its subdirectories. Individual
applications use files from the directory but
don’t install to it.)
| scripts\ (All .js files that belong to BPS; used for
the applications)
| styles\ (All style sheet (.css) files that belong to
BPS; used for the applications)
| images\ (All image, .gif, files that belong to BPS;
used for the applications. All the icon
files for the object types are in this
directory. For example, it contains images
for object type Part and administration
types like role and person.)
components\ (Program and image files for common
components; installed as part of Business
Process Services)
doc\
(Contains a subdirectory for each installed
application’s help systems, and a pdf
directory for user’s guides. Within each
application’s help subdirectory, there is a
subdirectory for each language, named using
the standard abbreviation for the
language, i.e., en for English, fr for
French, etc.. The javadoc directory
contains javadoc from the framework
classes.)
properties\ (All property files, including the String
Resource files and system property files
that let you configure features.
APPS_DIR\
(Each application, such as Engineering
Central and Supplier Central, has its own
directory. The application subdirectories
have the same name as the application,
with no spaces, such as EngineeringCentral
and SupplierCentral. The following types,
which belong to the applications, are in
this directory:
- JSP, .jsp, files
- JavaScript, .js, files
- style sheet, .css, files
- all component files)
| images\
(All image, .gif, files that belong to the
corresponding applications)
Web-Inf\
(Contains the emxUtil.tld and
framework.tld files, which are custom tag
libraries)
When installing ENOVIA products, all files are installed to the staging directory of the
Collaboration server installation directory. After installing all applications, you must run
the war utility to create archive files in the distrib directory. Then deploy the EAR file
using your J2EE application server. For more information on supported application
servers, the directory structures, and instructions for running the war utility and deploying
the archive file, see Deploying J2EE in Chapter 10.
Chapter 14: Installing Business Process Services™
385
Keep these important points in mind when making changes to framework and application
files, including changes to emxSystem.properties, emxLogin.properties, any
StringResource file, and any changes or additions to the JSPs:
File Naming
Conventions
•
Always make changes to the files within the staging directory and not to the
corresponding file in the archive files. If you make changes within the archive file
itself, you risk overwriting these changes the next time you run the war utility.
•
Remember to rerun the war utility and redeploy the archive file every time you make
changes to files in the staging directory. Restart the application server after deploying
the archive file.
The naming conventions for the files installed with Business Process Services and
applications ensure that all ENOVIA programs correctly refer to each other and are
distinguished from custom programs. The naming conventions also make it easy to
identify the purpose of the file and the application it belongs to. The below table shows the
conventions used for directories and files in the framework and for some applications.
Do not change the name of ENOVIA product programs and do not create new programs
that use any of the prefixes listed below. Doing either may cause programs to fail.
Directory Name
File Prefix
Example File Name
(various directories with Tcl and JSP files)
eService
emx
eServiceInstallAdmin.tcl
emxTeamAddBusinessUnit.jsp
Common\
common
emxcommon
eServicecommon
commonCheckRelativeState.tcl
eServicecommonCompleteTask.tcl
emxcommonPushPopShadowAgent.java
SERVER_INSTALL\intel_a\pixmaps\app\
—
The files in the pixmaps directory
are GIF image files. Since they
aren’t added to the database, there
is no naming convention for these
files.
SERVER_INSTALL\Apps\Framework\<version>\
Schema\
—
The files in the Schema directory
are for installation and are not
added to the database so there is no
naming convention used for them.
SERVER_INSTALL\intel_a\ematrix\ directory
and application subdirectories
emx[ABBREVIATION
FOR APPLICATION]
emxTeamAddBusinessUnit.jsp
emxbomCopyEBOMdialog.jsp
Other prefixes that are used include:
386
•
banner
•
bar
•
button
•
datapopulate
•
logo
ENOVIA Live Collaboration Installation Guide
•
menu
•
populate
•
softmgmt
•
splash
•
UserInterface
•
util
Naming conventions for image files
Category of
Image
Description
File name format
Example File Names
Object types like
Part, ECR etc
Small image / Icon
iconSmall<Object Name>.gif
iconSmallPart.gif
iconSmallECR.gif
Large Image / Icon
iconLarge< Object Name>.gif
iconLargePart.gif
iconLargeECR.gif
Small image / Icon
iconSmall<Admin Type Name>.gif
iconSmallPerson.gif
iconSmallRole.gif
Large image / Icon
iconLarge<Admin Type Name>.gif
iconLargePerson.gif
iconLargeRole.gif
Generic action
based images
Used in forms and Menus
button<Action Name>.gif
buttonDone.gif
buttonCancel.gif
buttonLogout.gif
buttonHelpAbout.gif
buttonInboxTask.gif
All Feature
specific images,
buttons, and icons
Icons
icon<FeatureKey><Name>.gif
iconSearchPerson.gif
iconProfilePerson.gif
iconBOMView.gif
Buttons
button<FeatureKey><Name>.gif
buttonBOMCopy.gif
buttonBOMView.gif
Utility and other Images
util<FeatureKey><Name>.gif
utilLoginBackground.gif
utilEngineeringTop.gif
utilPlus.gif
utilNavArrow.gif
utilSpacer.gif
Logos
logo<Name>.gif
logoEngineeringCentral.gif
logoSupplierCentral.gif
Administration
types like Role,
Person etc
Logo images for
products /
companies
Chapter 14: Installing Business Process Services™
387
388
ENOVIA Live Collaboration Installation Guide
15
Installing the 3DVIA
Viewer
Overview
The 3DVIA Viewer is a webtop visualization component used to view 3D and 2D images
(CGM, CGR or 3DXML files) associated with parts and CAD models.
The 3DVIA Viewer also allows you to view TIFF files (files with an extension of .tif or
.tiff) in 3DLive quality, a higher precision than is generally available with the viewer
integrated into Windows. The 3DVIA Viewer is launched initially in File mode, which
means that you cannot do any markup, redlining, or taking of measurements. Document
objects should conform to the CDM (Common Document Model) for storing TIFF files.
You can invoke the 3DVIA Viewer by:
•
Clicking the 3DVIA Viewer button in the BOM PowerView page for parts in
Engineering Central.
•
Clicking the 3DVIA Viewer button in the Navigator page for MCAD models in
Designer Central.
•
Viewing 3D or 2D images in the Image Manager page for objects in Common
Components. The Image Manager must be configured for the object. For details, see
“Configuring Images for Objects” in the ENOVIA Live Collaboration Administrator’s
Guide.
The first time you invoke the 3DVIA Viewer from your machine, you are asked if you
would like to install it. If you choose to install it, the 3DVIA Viewer is downloaded from
389
the Live Collaboration Server and installed on your machine. The next time you invoke it,
the 3DVIA Viewer already installed on your machine is used.
The 3DVIA Viewer is supported on both Windows 32- and 64-bit clients. You can invoke
the viewer from Internet Explorer on both 32- and 64-bit clients, and from Firefox on
32-bit clients.
390
ENOVIA Live Collaboration Installation Guide
3DVIA Viewer Live Collaboration Server
Installation
The 3DVIA Viewer is not required to be installed on the Live Collaboration Server.
Instead the Live Collaboration Server acts as a storage place for the 3DVIA Viewer
installation files. The 3DVIA Viewer is installed one time on a user's machine based on
need (i.e. if it's not already installed or if the existing version is older than the version
stored on the Live Collaboration Server). Users initiate the installation process by
invoking the 3DVIA Viewer from the locations listed above.
Even though the 3DVIA Viewer is only supported on Windows 32 and 64-bit clients, the
installation files need to be stored on all Live Collaboration Server installations (Windows,
UNIX, etc.). There are two separate tarkits that must be stored:
•
One for Windows 32-bit (3DVIAViewer.Windows_package)
•
One for Windows 64-bit (3DVIAViewer.Windows64_package)
Both tarkits must be stored so the 3DVIA Viewer can be installed on both Windows 32 and
64-bit clients.
Prerequisites for
Installing the
3DVIA Viewer on
the Live
Collaboration
Server
Before you launch the 3DVIA Viewer installation, the following are prerequisites:
•
The Live Collaboration Server and at least Business Process Services must be
installed. ENOVIA applications can be installed before or after installing the 3DVIA
Viewer tarkits.
•
The MSXML Parser must be in the STAGING directory. Both the 32 and 64-bit
versions must be installed. To download the MSXML Parser, an Administrator must
download both the msxml6_x86.msi and msxml6_x64.msi files from the Microsoft
website:
http://www.microsoft.com/downloads/
details.aspx?FamilyID=d21c292c-368b-4ce1-9dab-3e9827b70604&DisplayLang=en
Both files must be placed in the STAGING directory. For example, msxml6_x86.msi
should be copied in ENOVIAHOME/server/STAGING/components/x86/
msi/ and msxml6_x64.msi should be copied in ENOVIAHOME/server/
STAGING/components/x64/msi/. After all the ENOVIA applications you are
using are installed, run the war utility. For details, see Building the J2EE Archive File.
•
The web services required for the 3DVIA Viewer must be published. To publish these
web services, do the following:
a ) Set the following variables in the enovia.ini file for the Studio Modeling Platform
and the enovia.ini file for the Live Collaboration Server:
MX_SERVICE_PATH = <server path>\
distrib\enovia\WEB-INF\classes
This variable should be set to the directory where the service stubs and
deployment files will be written when service JPOs are compiled in the ENOVIA
Live Collaboration.
MX_SERVICE_ADMIN = <application server url>
This variable should specify the administration URL of the Axis Web
application.
Chapter 15: Installing the 3DVIA Viewer
391
b ) Force compile all the JPOs by running the following commands in MQL. The
application server above should be running when you compile:
set context user creator;
compile program * force;
c ) Restart the Live Collaboration Server.
d ) Access the following URL to verify the web services are published: <application
server url>/services
Installing the
3DVIA Viewer on
Windows
To install the 3DVIA Viewer on Windows Live Collaboration Servers
1. Log into Windows as a person with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
3. Unzip the zip file and run ENOVIUSetup.bat. The command prompt window opens.
4. Enter the path to your Live Collaboration Server installation, for example,
C:\enoviaV6R2011x\server. Click Enter.
The setup then copies the entire contents of the .tar file to
SERVER_INSTALL\STAGING\ematrix\components\x86\ (for the 32-bit
version).
5. Repeat the steps above for the tarkit for the 64-bit version.
6. Run the war utility (war_setup.bat) after installing all applications. See Building the
J2EE Archive File.
7. Deploy the generated web application using the J2EE application server. See
Deploying the J2EE Archive File.
8. Restart the application server.
Installing the
3DVIA Viewer on
UNIX
To install the 3DVIA Viewer on UNIX Live Collaboration Servers
1. Log in as a user who has the privileges to install the 3DVIA Viewer (copy files to the
Web server root directory, install on the database, run MQL.exe, etc.).
2. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD in Chapter 7 if necessary.
3. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./ENOVIUSetup
4. Enter the path to your Live Collaboration Server installation, for example:
/home/enovia/V6R2011x/server
The setup then copies the entire contents of the .tar file to SERVERHOME/
STAGING/enovia/components/x86/ (for the 32-bit version).
5. Repeat the steps above for the tarkit for the 64-bit version.
6. Run the war utility setup file after installing all applications. See Building the J2EE
Archive File.
392
ENOVIA Live Collaboration Installation Guide
7. Deploy the generated web application using the J2EE application server. See
Deploying the J2EE Archive File.
8. Restart the application server.
Upgrading the
3DVIA Viewer
To upgrade the version of the 3DVIA Viewer installation files stored on the Live
Collaboration Server, follow the installation instructions above for your platform.
Chapter 15: Installing the 3DVIA Viewer
393
394
ENOVIA Live Collaboration Installation Guide
16
Installing ENOVIA Products
Overview
All ENOVIA products require that you first install all components of ENOVIA Live
Collaboration as outlined in What Needs to be Installed? Then follow the installation
procedure appropriate for your platform:
Before Installing
the applications
•
Installing an Application on UNIX
•
Installing an Application on Windows
If installing many ENOVIA products on the same system, the default setting for open files
may be too small in a RIP environment (single process). In this case, ENOVIA Live
Collaboration requires about 1k for open files. For example, on Solaris use the following
setting in the /etc/system file:
set rlim_fd_cur=1024 ; soft limit (per process)
If your application server is configured for use with other applications besides ENOVIA’s,
you should refer to your application server’s tuning recommendations. For WebLogic on
Solaris, the recommendation is 8192 as shown in their documentation at:
http://e-docs.bea.com/wls/docs70/perform/HWTuning.html.
395
Installing a
Service Pack
Service pack installations (VERSION.SPX.Partial) are available for selected ENOVIA
product versions. A service pack can be installed only over the version of the same name.
For example, EngineeringCentral.10.5.SP2.Partial can be installed over Engineering
Central version 10.5 or 10.5.SP1. A full upgrade (VERSION.SPX.Full) can be installed
over any previous release.
Service pack installation follows the same procedure as the full release installation, but
includes only modified files. It is recommended for sites that have customized pages.
Installing an
Application on
UNIX
Before installing an application on UNIX you must:
•
Log in as a user who has the privileges to install the application (copy files to the Web
server root directory, install on the database, run MQL.exe, etc.).
•
If installing from a CD, mount the CD so the operating system software can access
the files contained on the disk. Refer to Mounting the CD in Chapter 7 for examples
of mount commands for each platform.
•
Make sure you know the path where mql.exe is located.
To install ENOVIA products on UNIX
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD in Chapter 7 if necessary. Use the -i option of the
tar command to avoid errors caused by long path names in the distribution that some
versions of tar can’t handle properly.
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup.APPNAME (for example, ./setup.ProgramCentral)
3. First you must choose the Installation Type from the following menu:
Installing APPLICATION_NAME
-----------------------------------------------------------Choose Installation Type
-----------------------------------------------------------1. Standard (Recommended)
2. Advanced
Select option (1-2) [1]? 1
Choose option 1 for the recommended Standard installation.
Choose option 2 to change the default settings for the prompts shown in Step 6.
4. Next, you must choose the directories for the installation to use.
Choose Directories
-----------------------------------------------------------Enter distribution directory path []?
Enter build script directory path []?
Enter Collaboration Platform Server installation directory
path []?
The distribution directory defaults to the directory above the current directory and
you should be able to accept the default by typing enter (or type in a new path as
required).
396
ENOVIA Live Collaboration Installation Guide
The build script directory is the path where the scripts that build the application in
the database are placed. If you specify a directory that does not exist, the setup
program will create the directory.
The Collaboration Platform Server installation directory is the path that contains
the ENOVIA Live Collaboration Server installation.
5. Next you must tell the setup program where MQL is (Matrix application scripts)
and the user name and password for a user that has Business and System
Administrator privileges, such as creator. If the user has no password, accept the
default.
Specify Administration Parameters
-----------------------------------------------------------Enter directory path for Modeling Studio scripts [/usr/bin]?
/app/mx10
Enter Administrator user for Modeling Studio ? [creator]?
Enter Administrator password ? [NONE]?
6. If you selected the Advanced option in Step 3, you are prompted for the following.
The Standard option accepts the defaults:
Advanced Install
-----------------------------------------------------------Do you wish to install to staging area only & Don’t update
database ? [no]?
Do you wish to undo the whole Framework transaction in case
of failure [yes]?
Install to staging area only. Don’t update database—The default is no, which
means after you complete the installation, the installation copies all files to the staging
area and runs the installation scripts to update the database. If you want to copy files
to the build script directory only and run the installation scripts later, check this
option. When you’re ready to run the installation scripts, use MQL to run the
installFrameworkVERSION.tcl file, located in the framework directory. To create log
and error files, use the -stderr and -stdout MQL options.
Undo whole transaction in failures—The default is yes. Undoing all transactions
makes it easier for you to correct problems with the new installation without
introducing problems into your existing setup. The log file for the framework lists all
transactions even if they are undone. If the transactions are undone, you can use the
log file to identify the error and then re-run setup after correcting the problem. You
should only change this option, allowing transactions to proceed even when there are
errors, if you know how to correct the error or if you are just installing for testing
purposes.
7. The system checks to see if there is a version of the application already installed. You
will receive one of the following messages.
•
If there is no previous installation:
No version of APPLICATION is installed. All application/
common files (JSPs, JPOs, Tcl Program Objects and JAR Files)
and schema (types, attributes, menus, commands, application
business objects, etc.) will be installed. Do you want to
continue [y n]
•
If there is an older version installed:
An older version of APPLICATION is installed. All older
application/common files (JSPs, JPOs, Tcl Program Objects
and JAR Files) and schema (types, attributes, menus,
Chapter 16: Installing ENOVIA Products
397
commands, application business objects, etc.) will be
updated. Do you want to continue [y n]
•
If the same version is installed:
The same version of APPLICATION is installed. All older
application/common files (JSPs, JPOs, Tcl Program Objects
and JAR Files) will be updated.
Do you want to continue [y n]
•
If a newer version is installed:
A newer version of APPLICATION is installed. You cannot
replace it with an older version.
<Press return to continue>
8. When you decide to continue, the system creates installation directories, copies files
to the directories, and builds the script files. A file named
installAPPNAME_VERSION.tcl is created in Apps/APP_NAME/VERSION.
VERSION is the software version number, such as 10-5.
Then the setup program runs the installation scripts.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, check the files named installAPPNAME_VERSION.log and
installAPPNAME_VERSION.err in your installation script directory to verify that the
setup is complete, to get details about errors, to see exactly what items were added
and/or modified, and to see if any items were renamed due to name collisions. If
errors were encountered and you chose to undo transactions in case of errors, the
setup will have undone all changes.
9. If you have backups of customized properties files, you’ll need to compare your
customized files with the new files from the updated version. Either update the new
files with your customizations or update your customized files with any new settings.
10. Continue with the next step in General Installation for ENOVIA Live Collaboration
Server.
Installing an
Application on
Windows
To install an ENOVIA product on Windows
1. Log into Windows as a person with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome frame, click Next.
5. At the Installation Type prompt, check the type of install you want to perform:
398
ENOVIA Live Collaboration Installation Guide
Standard (Recommended)—Use this option for all standard installations. When you
choose this option, the installation will undo all transactions if it encounters problems.
You can still use the log files to find out what transactions were attempted and to
diagnose the errors. The standard installation also automatically runs the installation
scripts after copying files to the staging area, but does not install sample data.
Advanced—Choose this option only if you want to allow the installation to proceed
even if errors occur or if you only want to copy files to the staging area now and run
the installation scripts later. If you choose this option, an Advanced Options prompt
displays at the end of the installation wizard, allowing you to change these options
from their default. (See Step 10.)
Click Next.
6. The Script Path frame asks where to put the scripts that build the application in the
database. The default is SERVER_INSTALL\Apps\APP_NAME\<version>\,
where SERVER_INSTALL is the directory where ENOVIA Live Collaboration is
installed. You can select a different location, if desired, using the Browse button. The
SERVER_INSTALL directory should contain the bootstrap file that points to your
database. After specifying the directory, click Next.
7. At the Super User/Password frame, enter the User and Password that has Business
and System Administrator privileges, such as creator. If the user has no password,
leave the Password box blank. Click Next.
8. Enter the name of the bootstrap file that points to the database in which you want to
install the schema. This bootstrap file must already exist in the ENOVIA_INSTALL
directory. When you are done, click Next.
9. At the next frame, enter the names of the Data and Index table spaces for the eService
Production vault.
The eService Production vault is the vault that will be used for production data.
Consult your Database Administrator for information about the table space names
used. If you do not specify table space names, the tables and indexes for the product
vault will be created in the Oracle user’s default tablespace, which may not be sized
appropriately for production data storage.
Click Next.
10. If you chose the Advanced install option, the Advanced Options prompt opens.
Choose the options you want based on the descriptions below. If you chose a Standard
install, skip to Step 16.
Install to staging area only. Don’t update database—This option is unchecked by
default, which means after you complete the installation wizard, the installation
copies all files to the staging area and runs the installation scripts to update the
database. If you want to copy files to the staging area only and run the installation
scripts later, check this option. When you’re ready to run the installation scripts, run
the installFrameworkVERSION.tcl file, located in the framework directory. To create
log and error files, use the -stderr and -stdout MQL options.
Undo whole transaction in failures—This option is checked by default. Undoing all
transactions makes it easier for you to correct problems with the new installation
without introducing errors into your existing setup. The log file for the framework
lists all transactions even if they are undone. If the transactions are undone, you can
use the log file to identify the error and then re-run setup after correcting the problem.
You should only uncheck this option, allowing transactions to proceed even when
there are errors, if you know how to correct the error or if you are just installing for
testing purposes.
Chapter 16: Installing ENOVIA Products
399
11. The system checks to see if there is a version of the application already installed. If
not, the program asks if you want to continue installing the application. To continue
installing, click Yes. Choosing No will exit setup and you’ll have to run setup again to
install.
If the install program detects an existing version of the application, you will receive
one of the following messages based on whether the existing version is older or newer
than the installing version.
If the existing
application
version is:
This message displays:
Available Actions:
older than the
installing version
An older version of
APPLICATION is installed. All
older application/common
files (JSPs, JPOs, Tcl Program
Objects and JAR Files) and
schema (types, attributes,
menus, commands, application
business objects, etc.) will
be updated.
To not install any schema or programs, click No.
To install updated schema and programs, click Yes.
Common component schema is installed only if it is
newer than the existing common components. Common
component programs are installed only if they are the
same version or newer than the existing common
components. (The existing common component version
might be different than the existing application version.)
the same as the
installing version
The same version of
APPLICATION is installed. All
older application/common
files (JSPs, JPOs, Tcl Program
Objects and JAR Files) will be
updated.
To not install any schema or programs, click No.
To install updated schema and programs, click Yes.
Common component schema is installed only if it is
newer than the existing common components. Common
component programs are installed only if they are the
same version or newer than the existing common
components. (The existing common component version
might be different than the existing application version.)
newer than the
installing version
A newer version of APPLICATION
is installed. You cannot
replace it with an older
version.
Click OK. No schema or programs are installed.
If you clicked Yes to install the application, the Setup program:
•
Copies installation scripts to the selected directory. While the files are copied, a
progress meter displays the current files being copied and the percent completed.
When the copy is complete, a file named installAPPNAME_VERSION.tcl is
created in the application’s directory. VERSION is the software version number
for the application, such as 10-6.
•
Launches MQL in the background and runs the install scripts.
•
Displays a progress meter, which shows you the files being run and the percent
completed. If you don’t see the progress meter, the installation isn’t working
correctly. Cancel the installation and rerun it, making sure you specify a valid
bootstrap file name.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
400
ENOVIA Live Collaboration Installation Guide
When complete, using a text editor such as WordPad, check the files named
installAPPNAME_VERSION.log and installAPPNAME_VERSION.err in your
installation directory to verify that the setup is complete, to get details about errors,
and to see exactly what items were added and/or modified. If errors were encountered,
the setup will have undone all changes (unless you chose not to undo the
transactions).
12. If you have backups of customized properties files, you’ll need to compare your
customized files with the new files from the updated version. Either update the new
files with your customizations or update your customized files with any new settings.
13. Continue with the next step in General Installation for ENOVIA Live Collaboration
Server.
Chapter 16: Installing ENOVIA Products
401
Upgrading ENOVIA Products
The installation programs for ENOVIA products recognize previously-installed versions
and make the necessary updates to upgrade the application to the new version. Refer to the
Program Directory for the given release for additional information on upgrading.
To install a new version of BPS or application over a previous version
1. Back up all files and the database.
a ) Back up the SERVER_INSTALL\STAGING\ematrix\ directory. It is
especially important to back up properties files to which you have made changes.
b ) Back up the SERVER_INSTALL\Apps\Framework\ directory.
c ) Back up the database instance.
2. If you want to install sample data for BPS, and have sample data installed from a
previous version of BPS, be aware that the installation scripts for sample data will not
overwrite business objects of the same name. This means that older version sample
data will not be updated, if changes were made in the newer revision.
3. Follow the instructions for Installing Business Process Services™ and Overview. See
the Program Directory for the specific version that you are installing for additional
instructions.
4. If you customized properties files, you’ll need to compare the backup copies of your
customized files with the new files from the updated version. Either update the new
files with your customizations or update your customized files with any new settings.
5. Continue with the next step in General Installation for ENOVIA Live Collaboration
Server.
402
ENOVIA Live Collaboration Installation Guide
Installation Troubleshooting
Symptom
Possible Remedy
Errors during application login from the
emxLogin page such as.
java.lang.ClassNotFoundException:
java.lang.Exception: Message:Compile error:
/usr/tmp/851aa48/
emxPropertyUtil_mxJPOHXUH8QAAAAEA
AAAB.java:21: cannot access java.lang.Object
bad class file: /usr/jdk1.5.0_02/jre/lib/
rt.jar(java/lang/Object.class)
class file has wrong version 49.0, should be
48.0
This exception usually this means that the JPO's were compiled on a higher
version of the JDK and the class files are attempting to be used by a lower
version of jdk.
All JPOs and JSPs should be compiled with the same version of the JDK as
the Application server will use. If you use the BPS Admin tool to run the
MQL compile command, this will ensure that the same JDK is used.
Also make sure that the MX_CLASSPATH and PATH information in
mxEnv.sh file are pointing to the correct JDK, and verify that the
Application server is indeed picking up this JDK when running in RIP
mode. Also check the JAVA_HOME in your environment.
Problems accessing the login or home page
Make sure web.xml has the correct login and home page properties, which
by default are as follows:
ematrix.login.page=/ematrix/emxLogin.jsp
ematrix.home.page=/ematrix/emxHome.jsp
On the application pages, you see tags for
strings instead of appropriate onscreen text
Make sure all StringResource.properties files are in STAGING/ematrix/
properties and that the classpath statements are correct for the Web server
(see the next remedy below).
Install error:
#0 System Error #1900014 Cannot open file
'c:matrixVERCoreAppsFrameworkCommonC
ommonCompatibilityCheck.tcl'
Be sure that MQL is not in “escape” mode. Run the following MQL
command to determine if escaping is enabled (you must log in as a
business administrator to do so):
MQL<> print escape;
If the system indicates that escape mode is on, turn it off before running the
install with:
MQL<> set escape off;
Refer to “Working with Workspace Objects” in the MQL Guide.
Chapter 16: Installing ENOVIA Products
403
Symptom
Possible Remedy
Install errors that indicate an administration
object couldn't be installed because it was not
unique or an administration object couldn't be
renamed because an object already exists with
that name.
A custom administration object may have been registered with the same
symbolic name as an object being installed/renamed. For example, you
may have registered administrative objects that you expect to be included
in the framework or you may have registered an object that coincidentally
has the same properties as a framework object.
To correct the problem so the installation proceeds correctly, you need to
unregister the added schema that is causing the collisions. To unregister
schema, use the eService Change Administration Property wizard, as
described in the Application Exchange Framework User’s Guide. Note that
there is no need to unregister added schema if it is not causing a collision
with installing schema.
After installing the framework, you can either use the framework’s object
or your custom object. Either way, you’ll probably have to make changes
to the one you use to include code and other characteristics from the one
you don't use. For considerations on which object to use and instructions,
see the “When There are Similarities Between the Framework and Your
Database” section of the Application Exchange Framework User’s Guide.
Do not register schema that you anticipate to be in an upcoming
release of the framework without explicit permission from ENOVIA
Framework Engineering. They must provide you with the registration
information.
Web server errors regarding problems finding
classes
404
The application server startup scripts that need matrix .jar files don’t refer
to .jar files directly. Instead they call ComputedClassPath. This only
requires that you have a valid bootstrap in place and that all the directories
that contain the .jar files you need are listed in MX_CLASSPATH. You
should only need to configure this if you have custom apps or custom JPOs
with non-Matrix dependencies. For more information, see
MX_CLASSPATH in Optional Variables in Chapter 9.
ENOVIA Live Collaboration Installation Guide
User Access to ENOVIA products
Refer to “Prerequisites” in the Program Directory for the given release for client-side
requirements.
Compile JSPs and
JPOs
When an application page (JSP) is first accessed it is compiled by the JVM in the
application server. In order to improve performance for the first user you should
pre-compile all the pages, as well as all the JPOs in the database. Use the table below to
determine how to precompile the JSPs with your application server.
Application Server
Precompile Command Information
Websphere
http://publib.boulder.ibm.com/infocenter/wasinfo/
index.jsp?topic=/com.ibm.websphere.nd.doc/info/ae/ae/
rweb_jspbchtl.html
Weblogic
http://e-docs.bea.com/wls/docs70/jsp/reference.html#57794
tomcat
http://jakarta.apache.org/tomcat/tomcat-4.1-doc/
jasper-howto.html#Web%20Application%20Compilation
Sun
http://docs.sun.com/source/817-2172/dwjsp.html#49427
All JPOs and JSPs should be compiled with the same version of the JDK as the
Application server will use. If you use the BPS Admin tool to run the MQL compile
command, this will ensure that the same JDK is used. To compile JPOs use the following
MQL command:
<mql> compile prog * force update;
File Text Searches
Some ENOVIA products allow you to search on text of a checked in file. To enable the full
text search functionality, you must select the Advanced Search option when installing
ENOVIA Live Collaboration.
Time/Date Format
For more information about configuring date/time formats for the framework and
ENOVIA products, refer to the “Setting Date Management Properties” section of the
ENOVIA Live Collaboration Administrator’s Guide.
Configuring File
Download for
Multi-Byte
Filenames on IE
To configure Internet Explorer to save files with filenames that have characters from any
language, you set the option that sends URLs as UTF-8.
To enable Internet Explorer to send URLs as UTF-8
1. In Internet Explorer, choose Tools > Internet Options.
Chapter 16: Installing ENOVIA Products
405
2. Select the Advanced tab.
3. Under the Browsing section, check Always send URLs as UTF-8.
4. Click OK.
5. Restart the browser.
Browser Screen
Resolution and
DPI settings
It is recommended that your browser machine uses a minimum resolution of 1024 x 768
with Small (or Normal) Font on the display settings. This ensures the display of large
calendar and table views.
In addition, most Windows/Linux systems are shipped with the display DPI set to 96.
Certain machines set to 120 have reported issues where some information is being cut-off
from their display. If you experience truncation (partial menus, etc.) in the Matrix UI and
have the resolution set to 120 DPI, it needs to be reset back to 96.
Accessing
ENOVIA products
To access ENOVIA products
1. Start the Application server.
If using WebLogic, start it from a console at the server, not from Telnet or other
remote service.
2. Start your Web browser.
3. Go to the http://HOSTNAME:[PORTNUMBER]/enovia/emxLogin.jsp.
The port number is only needed if you are using WebLogic.
4. At the login page, enter a User Name, such as the sample user, “Test Everything”,
and click Login.
For instructions on using the ENOVIA product, click the help button on any page.
406
ENOVIA Live Collaboration Installation Guide
Installing the ENOVIA Semiconductor
Accelerators
There are 4 ENOVIA Semiconductor Accelerators designed for the semiconductor
industry:
•
ENOVIA Synchronicity DesignSync Central- is an bundle that includes DesignSync
Data Manager and the Team Collaboration overlay. This application requires only
ENOVIA Live Collaboration (including Business Process Services) and ENOVIA
Synchronicity DesignSync Data manager.
•
ENOVIA Semiconductor Accelerator for Design to Manufacture - is an “overlay”
component that requires ENOVIA Engineering Central and ENOVIA Variant
Configuration Central.
•
ENOVIA Semiconductor Accelerator for Enterprise Project Management - is a
“bridge” component between ENOVIA Program Central and ENOVIA Synchronicity
DesignSync Data Manager and as such requires both DesignSync and Program
Central.
•
ENOVIA Semiconductor Accelerator for IP Management - is an “overlay” component
and requires ENOVIA Library Central. An optional integration to Synchronicity
DesignSync is included, but you can use the IP classification piece without
DesignSync. In addition, a Library Central taxonomy based on the VSIA standard is
also available. This is the same classification taxonomy implemented in
Synchronicity IP Gear; it is created by a script that must be run manually, as described
in the ENOVIA Library Central Administrator's Guide. A toolkit that provides partial
automation to enable migration of data/metadata from Synchronicity IP Gear is also
provided.
All of the accelerators can be enabled to interface with ENOVIA Synchronicity
DesignSync Data Manager and publish DesignSync files/folders as IP.
If you want to use HTTPS to communicate between DesignSync and the ENOVIA Live
Collaboration server, you must configure SSL on your DesignSync server and install the
digital certificate onto the ENOVIA Live Collaboration server. For more information, see
"DesignSync File Access" in the Application Development Guide.
Refer to the Program Directory for the given release for additional requirements.
Installing
DesignSync
Central
Installation involves the following steps
1. Installing Prerequisites in the correct order.
2. Installing the Team Collaboration Accelerator on UNIX or Installing the Team
Collaboration Accelerator on Windows.
3. Enabling source control access if you use Using ENOVIA Synchronicity DesignSync
Data Manager with ENOVIA Live Collaboration.
The war utility only needs to be run one time after the last Accelerator you plan to use is
installed. It does not need to be run after each Accelerator is installed.
Chapter 16: Installing ENOVIA Products
407
Prerequisites
You should install the SAME VERSION (such as V6R2011x) of the prerequisites in the
following order:
1. Live Collaboration, with its requirements of a supported application server and a
supported database. Be sure to include the schema for the application(s) you are using
when installing the Business Process Services component of the platform.
2. DesignSync on a different host machine than ENOVIA Live Collaboration.
Installing the Team Collaboration Accelerator on UNIX
The Team Collaboration Accelerator is supported for both UNIX and Windows platforms.
To install the Accelerator on Windows platforms, see Installing the Team Collaboration
Accelerator on Windows.
To install the Accelerator on UNIX
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD if necessary. Use the -i option of the tar
command to avoid errors caused by long path names in the distribution that some
versions of tar can’t handle properly.
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup.TeamCollaboration
3. First you must choose the Installation Type from the following menu
Installing Team Collaboration
-----------------------------------------------------------Choose Installation Type
-----------------------------------------------------------1. Standard (Recommended)
2. Advanced
Select option (1-2) [1]? 1
Choose option 1 for the recommended Standard installation.
Choose option 2 to change the default settings for the prompts shown.
4. Next, choose the directories for the installation to use.
Choose Scripts Directories
-----------------------------------------------------------Enter build script directory path [<current_dir>]?
Enter Collaboration Platform Server installation directory
path?
The build script directory is the path where the scripts that build the application in
the database are placed. If you specify a directory that does not exist, the setup
program will create the directory. The default value is the current working directory.
The installation directory is the path that contains the ENOVIA Live Collaboration
Server installation. The default value is the current working directory.
408
ENOVIA Live Collaboration Installation Guide
5. Next you must tell the setup program where the ENOVIA Studio Modeling Platform
and where the Schema Installer are, as well as the user name and password for a user
that has Business and System Administrator privileges, such as creator. If the user has
no password, accept the default.
Specify Administration Parameters
-----------------------------------------------------------Enter directory path for Modeling Studio scripts [/usr/bin]?
Schema Installer Path
-----------------------------------------------------------Enter where schema installer exists [SERVERHOME/Apps/
Framework/<version>/SchemaInstaller]?
Enter Administrator user for Modeling Studio? [creator]?
Enter Administrator password ? [NONE]?
6. If you selected the Advanced install option, you are prompted for the following. The
Standard option accepts the defaults:
Advanced Install
-----------------------------------------------------------Do you wish to install to staging area only & Don’t update
database ? [no]?
Do you wish to undo the whole TeamCollaboration transaction
in case of failure [yes]?
Refer to Step 6. in the Installing ENOVIA products procedure for details on the
options.
7. The system checks to see if there is a previous version of the Team Collaboration
accelerator already installed. You will receive a message asking you to confirm that
you want to proceed. If you say yes, the system creates installation directories, copies
files to the directories, and builds the script files. A file named
installDesigntoSyncCentral_<VERSION>.tcl is created in Apps/TeamCollaboration/
<VERSION>. <VERSION> is the software version number, such as V6R2009x.
Then the setup program runs the installation scripts.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered and you chose to undo transactions in
case of errors, the setup will have undone all changes. Check the files named
installTeamCollaboration_VERSION.log and
installTeamCollaboration_VERSION.err in your installation script directory to get
details about errors and to see exactly which items were added and/or modified. If
there are no errors, you may still want to review the log file to see if any items were
renamed to avoid name collisions.
8. The schema installer then creates the selected schema. If errors are encountered and
you chose to undo transactions in case of errors, the setup will undo all changes.
Check the files named installSchemaInstallerVERSION.log and
SchemaChangesMQLVERSION.log, as well as installFrameworkVERSION.log and
installFrameworkVERSION.err in your installation script directory to get details
Chapter 16: Installing ENOVIA Products
409
about errors and to see exactly what items were added and/or modified. If there are no
errors, you may still want to review the log files to see if any items were renamed to
avoid name collisions.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
9. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
10. Run the war utility and deploy the application. For information on deploying an
application, see Deploying the J2EE Archive File.
Installing the Team Collaboration Accelerator on Windows
The Accelerator is supported for both UNIX and Windows platforms. To install the
Accelerator on UNIX platforms, see Installing the Team Collaboration Accelerator on
UNIX.
To install the Accelerator on Windows
1. Log into Windows as a user with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome frame, click Next.
5. At the Installation Type prompt, check the type of install you want to perform:
Standard (Recommended)—Use this option for all standard installations. When you
choose this option, the installation will undo all transactions if it encounters problems.
You can still use the log files to find out what transactions were attempted and to
diagnose the errors. The standard installation also automatically runs the installation
scripts after copying files to the staging area, but does not install sample data.
Advanced—Choose this option only if you want to allow the installation to proceed
even if errors occur or if you only want to copy files to the staging area now and run
the installation scripts later. If you choose this option, an Advanced Options prompt
displays at the end of the installation wizard, allowing you to change these options
from their default. (See Step 11.)
Click Next.
6. The Script Path frame asks where to put the scripts that build the application in the
database. The default is the SERVER_INSTALL\Apps\TeamCollaboration\<version>\ directory.
You can select a different location, if desired, using the Browse button. After
specifying the directory, click Next.
7. On the JDK directory frame, enter the path to the JDK. Click Next.
410
ENOVIA Live Collaboration Installation Guide
8. On the Schema installer frame, enter the path to the schema installer.
9. At the Super User/Password frame, enter the User and Password for a user who has
Business and System Administrator privileges, such as creator. If the user has no
password, leave the Password box blank. Click Next.
10. Enter the name of the bootstrap file that points to the database in which you want to
install the schema. This bootstrap file must already exist in installation directory
where Supplier Central suite is installed. When you are done, click Next.
11. If you chose the Advanced install option, the Advanced Options prompt opens.
Choose the options you want based on the descriptions below.
Install to staging area only. Don’t update database—This option is unchecked by
default, which means after you complete the installation wizard, the installation
copies all files to the staging area and runs the installation scripts to update the
database. If you want to copy files to the staging area only and run the installation
scripts later, check this option. When you’re ready to run the installation scripts, run
the installFrameworkVERSION.tcl file, located in the framework directory. To create
log and error files, use the -stderr and -stdout MQL options.
Undo whole transaction in failures—This option is checked by default. Undoing all
transactions makes it easier for you to correct problems with the new installation
without introducing errors into your existing setup. The log file for the framework
lists all transactions even if they are undone. If the transactions are undone, you can
use the log file to identify the error and then re-run setup after correcting the problem.
You should only uncheck this option, allowing transactions to proceed even when
there are errors, if you know how to correct the error or if you are just installing for
testing purposes.
12. DesignSync Central is installed. When the schema portion of the install is reached,
you are asked if you want to continue. You must install the schema in order for the
accelerator to work. Click Yes to continue, No to cancel.
13. Next you are asked where custom schema files exist. Enter the path to your custom
schema directory.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered, the setup will have undone all
changes (unless you chose not to undo the transactions). Using a text editor such as
WordPad, check the files named installTeamCollaboration_VERSION.log and
installTeamCollaboration_VERSION.err in your installation directory to get details
about errors and to see exactly what items were added and/or modified.
14. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
15. Run the war utility and deploy the application. For information on deploying an
application, see Deploying the J2EE Archive File.
Chapter 16: Installing ENOVIA Products
411
Using ENOVIA Synchronicity DesignSync Data Manager with
ENOVIA Live Collaboration
When you install DesignSync Central, you should enable DesignSync file access (DSFA).
This entails the following:
Installing the
Design to
Manufacture
Accelerator
•
Obtaining and installing a DSFA license key for each ENOVIA Live Collaboration
user that will use the DesignSync store. Refer to the DesignSync document,
INSTALL_LICENSE.txt for details.
•
Creating a DesignSync store. Refer to the ENOVIA Live Collaboration
Administrator’s Guide for details.
Installation involves the following steps
1. Installing Prerequisites in the correct order.
2. Installing the Design to Manufacture Accelerator on UNIX or Installing the Design to
Manufacture Accelerator on Windows.
3. Enabling source control access if you use Using ENOVIA Synchronicity DesignSync
Data Manager with ENOVIA Live Collaboration.
The war utility only needs to be run one time after the last Accelerator you plan to use is
installed. It does not need to be run after each Accelerator is installed.
Prerequisites
You should install the SAME VERSION (such as V6R2011x) of the prerequisites in the
following order:
1. ENOVIA Live Collaboration, with its requirements of a supported application server
and a supported database. Be sure to include the schema for the application(s) you are
using when installing the Business Process Services component of the platform.
2. Engineering Central.
3. Variant Configuration Central.
See Before Installing the applications for information on installing ENOVIA products.
You may install Engineering Central and Variant Configuration Central in either order,
but you must install Live Collaboration first, and all three applications must be installed
before installing the Accelerator.
Installing the Design to Manufacture Accelerator on UNIX
The Accelerator is supported for both UNIX and Windows platforms. To install the
Accelerator on Windows platforms, see Installing the Design to Manufacture Accelerator
on Windows.
412
ENOVIA Live Collaboration Installation Guide
To install the Accelerator on UNIX
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD if necessary. Use the -i option of the tar
command to avoid errors caused by long path names in the distribution that some
versions of tar can’t handle properly.
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup.DesigntoManufacture
3. First you must choose the Installation Type from the following menu
Installing Design to Manufacture
-----------------------------------------------------------Choose Installation Type
-----------------------------------------------------------1. Standard (Recommended)
2. Advanced
Select option (1-2) [1]? 1
Choose option 1 for the recommended Standard installation.
Choose option 2 to change the default settings for the prompts.
4. Next, choose the directories for the installation to use.
Choose Scripts Directories
-----------------------------------------------------------Enter build script directory path [<current_dir>]?
Enter Collaboration Platform Server installation directory
path [<current_dir>]?
The build script directory is the path where the scripts that build the application in
the database are placed. If you specify a directory that does not exist, the setup
program will create the directory. The default value is the current working directory.
The installation directory is the path that contains the ENOVIA Live Collaboration
Server installation. The default value is the current working directory.
5. Next you must tell the setup program where the ENOVIA Studio Modeling Platform
and where the Schema Installer are, as well as the user name and password for a user
that has Business and System Administrator privileges, such as creator. If the user has
no password, accept the default.
Specify Administration Parameters
-----------------------------------------------------------Enter directory path for Modeling Studio scripts [/usr/bin]?
Schema Installer Path
-----------------------------------------------------------Enter where schema installer exists [SERVERHOME/Apps/
Framework/<version>/SchemaInstaller]?
Enter Administrator user for Modeling Studio? [creator]?
Enter Administrator password ? [NONE]?
6. If you selected the Advanced install option, you are prompted for the following. The
Standard option accepts the defaults:
Advanced Install
Chapter 16: Installing ENOVIA Products
413
-----------------------------------------------------------Do you wish to install to staging area only & Don’t update
database ? [no]?
Do you wish to undo the whole Semiconductor Accelerator for
Design to Manufacture transaction in case of failure [yes]?
Refer to Step 6. in the Installing ENOVIA products procedure for details on the
options.
7. The system checks to see if there is a version of the accelerator already installed. You
will receive a message asking you to confirm that you want to proceed. If you say yes,
the system creates installation directories, copies files to the directories, and builds the
script files. A file named installDesigntoManfacture_<VERSION>.tcl is created in
Apps/DesigntoManufacture/<VERSION>. <VERSION> is the software version
number, such as V6R2009x.
Then the setup program runs the installation scripts.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered and you chose to undo transactions in
case of errors, the setup will have undone all changes. Check the files named
installDesigntoManufacture_VERSION.log and
installDesigntoManufacture_VERSION.err in your installation script directory to get
details about errors and to see exactly which items were added and/or modified. If
there are no errors, you may still want to review the log file to see if any items were
renamed to avoid name collisions.
8. The schema installer then creates the selected schema. If errors are encountered and
you chose to undo transactions in case of errors, the setup will undo all changes.
Check the files named installSchemaInstallerVERSION.log and
SchemaChangesMQLVERSION.log, as well as installFrameworkVERSION.log and
installFrameworkVERSION.err in your installation script directory to get details
about errors and to see exactly what items were added and/or modified. If there are no
errors, you may still want to review the log files to see if any items were renamed to
avoid name collisions.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
9. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
10. Run the war utility and deploy the application. For information on deploying an
application, see Deploying the J2EE Archive File.
Installing the Design to Manufacture Accelerator on Windows
The Accelerator is supported for both UNIX and Windows platforms. To install the
Accelerator on UNIX platforms, see Installing the Design to Manufacture Accelerator on
UNIX.
414
ENOVIA Live Collaboration Installation Guide
To install the Accelerator on Windows
1. Log into Windows as a user with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome frame, click Next.
5. At the Installation Type prompt, check the type of install you want to perform:
Standard (Recommended)—Use this option for all standard installations. When you
choose this option, the installation will undo all transactions if it encounters problems.
You can still use the log files to find out what transactions were attempted and to
diagnose the errors. The standard installation also automatically runs the installation
scripts after copying files to the staging area, but does not install sample data.
Advanced—Choose this option only if you want to allow the installation to proceed
even if errors occur or if you only want to copy files to the staging area now and run
the installation scripts later. If you choose this option, an Advanced Options prompt
displays at the end of the installation wizard, allowing you to change these options
from their default. (See Step 11.)
Click Next.
6. The Script Path frame asks where to put the scripts that build the application in the
database. The default is the SERVER_INSTALL\Apps\DesigntoManufacture\<version> directory.
You can select a different location, if desired, using the Browse button. After
specifying the directory, click Next.
7. On the JDK directory frame, enter the path to the JDK. Click Next.
8. On the Schema installer frame, enter the path to the schema installer.
9. At the Super User/Password frame, enter the User and Password for a user who has
Business and System Administrator privileges, such as creator. If the user has no
password, leave the Password box blank. Click Next.
10. Enter the name of the bootstrap file that points to the database in which you want to
install the schema. This bootstrap file must already exist in installation directory
where Supplier Central suite is installed. When you are done, click Next.
11. If you chose the Advanced install option, the Advanced Options prompt opens.
Choose the options you want based on the descriptions below.
Install to staging area only. Don’t update database—This option is unchecked by
default, which means after you complete the installation wizard, the installation
copies all files to the staging area and runs the installation scripts to update the
database. If you want to copy files to the staging area only and run the installation
scripts later, check this option. When you’re ready to run the installation scripts, run
the installFrameworkVERSION.tcl file, located in the framework directory. To create
log and error files, use the -stderr and -stdout MQL options.
Chapter 16: Installing ENOVIA Products
415
Undo whole transaction in failures—This option is checked by default. Undoing all
transactions makes it easier for you to correct problems with the new installation
without introducing errors into your existing setup. The log file for the framework
lists all transactions even if they are undone. If the transactions are undone, you can
use the log file to identify the error and then re-run setup after correcting the problem.
You should only uncheck this option, allowing transactions to proceed even when
there are errors, if you know how to correct the error or if you are just installing for
testing purposes.
12. The accelerator files are installed. When the schema portion of the install is reached,
you are asked if you want to continue. You must install the schema in order for the
accelerator to work. Click Yes to continue, No to cancel.
13. Next you are asked where custom schema files exist. Enter the path to your custom
schema directory.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered, the setup will have undone all
changes (unless you chose not to undo the transactions). Using a text editor such as
WordPad, check the files named installDesigntoManufacture_VERSION.log and
installDesigntoManufacture_VERSION.err in your installation directory to get details
about errors and to see exactly what items were added and/or modified.
14. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
15. Run the war utility and deploy the application. For information on deploying an
application, see Deploying the J2EE Archive File.
Using ENOVIA Synchronicity DesignSync Data Manager with
ENOVIA Live Collaboration
When you install the Semiconductor Accelerator for Design to Manufacture, you can
optionally enable DesignSync file access (DSFA). This entails the following:
Installing the
Enterprise Project
Management
Accelerator
•
Obtaining and installing a DSFA license key for each ENOVIA Live Collaboration
user that will use the Designsync store. Refer to the DesignSync document,
INSTALL_LICENSE.txt for details.
•
Creating a DesignSync store. Refer to the ENOVIA Live Collaboration
Administrator’s Guide for details.
Installation involves the following steps
1. Installing Prerequisites in the correct order.
2. Installing the Enterprise Project Management Accelerator on UNIX or Installing the
Enterprise Project Management Accelerator on Windows.
3. Configuring EPM.
416
ENOVIA Live Collaboration Installation Guide
4. Enabling source control access if you use Using ENOVIA Synchronicity DesignSync
Data Manager with ENOVIA Live Collaboration.
The war utility only needs to be run one time after the last Accelerator you plan to use is
installed. It does not need to be run after each Accelerator is installed. You must run the
war utility a second time after the Web Service is compiled/generated. Refer to
Configuring EPM for details.
Prerequisites
You should install the SAME VERSION (such as V6R2011x) of the prerequisites in the
following order:
1. Live Collaboration, with its requirements of a supported application server and a
supported database. Be sure to include the schema for the application(s) you are using
when installing the Business Process Services component of the platform.
2. Program Central.
3. DesignSync on a different host machine than ENOVIA Live Collaboration.
You must install Live Collaboration before Program Central, but you may install
DesignSync at any time before configuring the accelerator.
Installing the Enterprise Project Management Accelerator on
UNIX
To install the Accelerator on UNIX
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD if necessary. Use the -i option of the tar
command to avoid errors caused by long path names in the distribution that some
versions of tar can’t handle properly.
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup.EnterpriseProjectManagement
3. First you must choose the Installation Type from the following menu:
Installing Enterprise Project Management
-----------------------------------------------------------Choose Installation Type
-----------------------------------------------------------1. Standard (Recommended)
2. Advanced
Select option (1-2) [1]? 1
Choose option 1 for the recommended Standard installation.
Choose option 2 to change the default settings for the prompts.
4. Next, choose the directories for the installation to use.
Choose Scripts Directories
------------------------------------------------------------
Chapter 16: Installing ENOVIA Products
417
Enter build script directory path [<current_dir>]?
Enter Collaboration Platform Server installation directory
path [<current_dir>]?
The build script directory is the path where the scripts that build the application in
the database are placed. If you specify a directory that does not exist, the setup
program will create the directory. The default value is the current working directory.
The installation directory is the path that contains the ENOVIA Live Collaboration
Server installation. The default value is the current working directory.
5. Next you must tell the setup program where the ENOVIA Studio Modeling Platform
and where the Schema Installer are, as well as the user name and password for a user
that has Business and System Administrator privileges, such as creator. If the user has
no password, accept the default.
Specify Administration Parameters
-----------------------------------------------------------Enter directory path for Modeling Studio scripts [/usr/bin]?
Schema Installer Path
-----------------------------------------------------------Enter where schema installer exists [SERVERHOME/Apps/
Framework/<version>/SchemaInstaller]?
Enter Administrator user for Modeling Studio? [creator]?
Enter Administrator password ? [NONE]?
6. If you selected the Advanced install option, you are prompted for the following. The
Standard option accepts the defaults:
Advanced Install
-----------------------------------------------------------Do you wish to install to staging area only & Don’t update
database ? [no]?
Do you wish to undo the whole Semiconductor Accelerator for
Enterprise Project Management transaction in case of failure
[yes]?
Refer to Step 6. in the Installing ENOVIA products procedure for details on the
options.
7. The system checks to see if there is a version of the accelerator already installed. You
will receive a message asking you to confirm that you want to proceed. If you say yes,
the system creates installation directories, copies files to the directories, and builds the
script files. A file named installEnterpriseProjectManagement_<VERSION>.tcl is
created in Apps/EnterpriseProjectManagement/<VERSION>. <VERSION> is the
software version number, such as V6R2009x.
Then the setup program runs the installation scripts.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered and you chose to undo transactions in
case of errors, the setup will have undone all changes. Check the files named
installEnterpriseProjectManagement_VERSION.log and
installEnterpriseProjectManagement_VERSION.err in your installation script
418
ENOVIA Live Collaboration Installation Guide
directory to get details about errors and to see exactly which items were added and/or
modified. If there are no errors, you may still want to review the log file to see if any
items were renamed to avoid name collisions.
8. The schema installer then creates the selected schema. If errors are encountered and
you chose to undo transactions in case of errors, the setup will undo all changes.
Check the files named installSchemaInstallerVERSION.log and
SchemaChangesMQLVERSION.log, as well as installFrameworkVERSION.log and
installFrameworkVERSION.err in your installation script directory to get details
about errors and to see exactly what items were added and/or modified. If there are no
errors, you may still want to review the log files to see if any items were renamed to
avoid name collisions.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
9. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
10. Run the war utility and deploy the application. For information on deploying an
application, see Deploying the J2EE Archive File.
After the EPM Web Server is compiled/generated, run the war utility again to update
the application. For more information, see Configuring EPM.
Installing the Enterprise Project Management Accelerator on
Windows
The Accelerator is supported for both UNIX and Windows platforms. To install the
Accelerator on UNIX platforms, see Installing the Enterprise Project Management
Accelerator on UNIX.
To install the Accelerator on Windows
1. Log into Windows as a user with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome frame, click Next.
5. At the Installation Type prompt, check the type of install you want to perform:
Standard (Recommended)—Use this option for all standard installations. When you
choose this option, the installation will undo all transactions if it encounters problems.
You can still use the log files to find out what transactions were attempted and to
diagnose the errors. The standard installation also automatically runs the installation
scripts after copying files to the staging area, but does not install sample data.
Chapter 16: Installing ENOVIA Products
419
Advanced—Choose this option only if you want to allow the installation to proceed
even if errors occur or if you only want to copy files to the staging area now and run
the installation scripts later. If you choose this option, an Advanced Options prompt
displays at the end of the installation wizard, allowing you to change these options
from their default. (See Step 11.)
Click Next.
6. The Script Path frame asks where to put the scripts that build the application in the
database. The default is the SERVER_INSTALL\Apps\EnterpriseProjectManagement\<version>\ directory.
You can select a different location, if desired, using the Browse button. After
specifying the directory, click Next.
7. On the JDK directory frame, enter the path to the JDK. Click Next.
8. On the Schema installer frame, enter the path to the schema installer.
9. At the Super User/Password frame, enter the User and Password for a user who has
Business and System Administrator privileges, such as creator. If the user has no
password, leave the Password box blank. Click Next.
10. Enter the name of the bootstrap file that points to the database in which you want to
install the schema. This bootstrap file must already exist in installation directory
where Supplier Central suite is installed. When you are done, click Next.
11. If you chose the Advanced install option, the Advanced Options prompt opens.
Choose the options you want based on the descriptions below.
Install to staging area only. Don’t update database—This option is unchecked by
default, which means after you complete the installation wizard, the installation
copies all files to the staging area and runs the installation scripts to update the
database. If you want to copy files to the staging area only and run the installation
scripts later, check this option. When you’re ready to run the installation scripts, run
the installFrameworkVERSION.tcl file, located in the framework directory. To create
log and error files, use the -stderr and -stdout MQL options.
Undo whole transaction in failures—This option is checked by default. Undoing all
transactions makes it easier for you to correct problems with the new installation
without introducing errors into your existing setup. The log file for the framework
lists all transactions even if they are undone. If the transactions are undone, you can
use the log file to identify the error and then re-run setup after correcting the problem.
You should only uncheck this option, allowing transactions to proceed even when
there are errors, if you know how to correct the error or if you are just installing for
testing purposes.
12. The accelerator files are installed. When the schema portion of the install is reached,
you are asked if you want to continue. You must install the schema in order for the
accelerator to work. Click Yes to continue, No to cancel.
13. Next you are asked where custom schema files exist. Enter the path to your custom
schema directory.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered, the setup will have undone all
changes (unless you chose not to undo the transactions). Using a text editor such as
420
ENOVIA Live Collaboration Installation Guide
WordPad, check the files named
installEnterprisePerformanceManagement_VERSION.log and
installEnterprisePerformanceManagement_VERSION.err in your installation
directory to get details about errors and to see exactly what items were added and/or
modified.
14. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
15. Run the war utility and deploy the application. If you installed Enterprise Project
Management, you must deploy in exploded .war file format for this first deployment.
You will deploy again after the Web Service is compiled/generated, and at that time
you can generate a .war or .ear file if you prefer. Refer to Configuring EPM for
additional steps.
Configuring EPM
Once you have installed Enterprise Project Management and deployed the application in
exploded format, some configuration of the application, the application server, as well as
the DesignSync server, is required as described below.
To Generate the Webservice and Deploy EPM as a .war or .ear file
1. Set the MX_SERVICE_PATH and MX_SERVICE_ADMIN variables in the
enovia.ini files for the Live Collaboration Server and Studio Modeling Platform
(previously ematrix.ini and matrix.ini) (on Windows) or in mxEnv.sh, as well as
desktop startup scripts for MQL, Matrix, Business, and System (on UNIX):
For WebLogic on Windows:
MX_SERVICE_PATH=C:\RMIINSTALL\enovia\WEB-INF\classes
MX_SERVICE_ADMIN=http://HOST:PORT#/enovia
For WebLogic on UNIX:
MX_SERVICE_PATH=/EMATRIXRMI/distrib/enovia/WEB-INF/classes
export MX_SERVICE_PATH
MX_SERVICE_ADMIN=http://HOST:PORT#/enovia
export MX_SERVICE_ADMIN
For WebSphere on Windows:
MX_SERVICE_PATH=C:\WEBSPHEREINSTALL\AppServer\installedApps\
HOSTNAME\enovia\ematrix.ear\ematrix.war\WEB-INF\classes
MX_SERVICE_ADMIN=http://HOST:PORT#/enovia
For WebSphere on UNIX:
MX_SERVICE_PATH=/WEBSPHEREINSTALL/AppServer/installedApps/
HOSTNAME/enovia/STAGING/WEB-INF/classes
export MX_SERVICE_PATH
MX_SERVICE_ADMIN=http://HOST:PORT#/enovia
export MX_SERVICE_ADMIN
For Tomcat on Linux:
MX_SERVICE_PATH /app/jakarta-tomcat/webapps/enovia/WEB-INF/
classes
export MX_SERVICE_PATH
MX_SERVICE_ADMIN=http://HOST:PORT#/enovia
export MX_SERVICE_ADMIN
Chapter 16: Installing ENOVIA Products
421
2. Copy the MX_CLASSPATH setting from the enovia.ini file for the Live
Collaboration Server (previously ematrix.ini) into the enovia.ini file for the Studio
Modeling Platform (previously matrix.ini). (That is, overwrite the MX_CLASSPATH
setting in the enovia.ini file for the Studio Modeling Platform with the
MX_CLASSPATH setting from the enovia.ini file for the Live Collaboration Server.)
3. Login into Business Modeler as someone with privileges to modify Programs. Edit
the program named “emxICDocumentBase” to include the correct SyncServer user
name and password (the same as is used for accessing DesignSyncServer) in
getICUserCredentials:
String UserId = “YOURUSERNAME”;
String Pwd = “YOURPASSWORD”;
Also modify the variable MCS_ClientURI as appropriate for this server, such as:
http(s)://hostname:port#/enovia
Save the program.
Do NOT set the user/password in triggerICDeleteCheck (icUserID, icUserPassword);
these should be kept as empty strings.
4. Login into MQL and compile all JPOs (compile prog * force update).
After successful compilation, check that the .wsdl extension file was created in the
MX_SERVICE_PATH specified in the ini files/shell scripts.
HINT: You can log into the application as a user defined with the Administration Manager
role to run MQL commands, as described in the AEF User’s Guide.
5. Run the war utility and deploy the application.
6. When properly configured, the communication service responds by returning a
greeting when the following URL is submitted from a web browser:
http[s]://hostname:port#/ematrix/services/
EmxProgramCentralServices
ENOVIA Live Collaboration Configuration for EPM
1. Login into the application as someone with Person access. Create a person in
“Company Name” (or Your Company) for the SyncServer user with User Name and
Password the same as you added to the program in Step 3 above.
2. In Business Modeler, open the SyncServer person you added above. Add the “Global
User” Role to the person and save.
3. Back in the application, choose Reload Cache.
DesignSync Server Configuration for EPM
1. Enable RC note generation for tagging.
Bring up the Administer Server panel, either via SyncAdmin& or the
Server->Administer Server link from ProjectSync. Select Server Settings, check Tag,
and hit Apply.
2. Bridge user account.
Using ProjectSync, create a user with username and password that matches the
syncuser and syncpassword established in ENOVIA Live Collaboration.
3. SyncServer URLs and SSL support
422
ENOVIA Live Collaboration Installation Guide
Objects in ENOVIA Live Collaboration are linked to files checked into the
DesignSync Server via the bridge. The link is established in ENOVIA Live
Collaboration Server by providing an explicit URL (IC URL or Project IC URL) that
points to the SyncServer object. These URLs must be of the form sync://
hostname:port/Projects. Note that the format shown assumes non-secure
communication over a cleartext port. In order to utilize secure communication over an
SSL port, you must do the following:
a ) Configure both a cleartext and an SSL port during installation of your
SyncServer.
b ) Specify the secure sync protocol (syncs) and the SSL port in your IC or Project
IC URL, e.g., syncs://hostname:SSLport/Projects. You cannot simply specify the
cleartext port and depend on SSL redirection.
c ) Also configure ENOVIA Live Collaboration Server on an SSL port;
communication should be secure in both directions.
4. Establish the link from the DesignSync object back to the ENOVIA Live
Collaboration object.
When an IC File is created in EPM, the absolute or relative IC URL points to a file that is
or will be checked into DesignSync. At that time, a Policy is chosen for the object,
defining a state sequence. The object starts in the initial state of that policy lifecycle. In the
DesignSync server, that file must be checked in if it is not already. To establish the bridge
connection, the correct version of that file should be tagged in DesignSync with one of the
state names in the policy. After that, either side of the bridge may advance the state of the
object, either with a Lifecycle Promote in Program Central or by manually tagging it in
DesignSync with the next state. When promoting the object in Program Central from state
A to state B, the user is telling the system to apply the B tag to the set of files currently
tagged as A.
Using ENOVIA Synchronicity DesignSync Data Manager with
ENOVIA Live Collaboration
When you install any of the Semiconductor Accelerator components you can optionally
enable DesignSync file access (DSFA). This entails the following:
Installing the IP
Management
Accelerator
•
Obtaining and installing a DSFA license key for each ENOVIA Live Collaboration
user that will use the DesignSync store. Refer to the DesignSync document,
INSTALL_LICENSE.txt for details.
•
Creating a DesignSync store. Refer to the ENOVIA Live Collaboration
Administrator’s Guide for details.
•
If you have used the EPM component prior to version 10.7, you need to run a
migration script to convert the access of DesignSync files from a URL to the store/
server model. Refer to the Schema Reference Guide, Appendix A for details.
Installation involves the following steps
1. Installing Prerequisites in the correct order.
2. Installing the IP Management Accelerator on UNIX or Installing the IP Management
Accelerator on Windows.
Chapter 16: Installing ENOVIA Products
423
3. Enabling source control access if you use Using ENOVIA Synchronicity DesignSync
Data Manager with ENOVIA Live Collaboration.
The war utility only needs to be run one time after the last Accelerator you plan to use is
installed. It does not need to be run after each Accelerator is installed.
Prerequisites
You should install the SAME VERSION (such as V6R2011x) of the prerequisites in the
following order:
1. Live Collaboration, with its requirements of a supported application server and a
supported database. Be sure to include the schema for the application(s) you are using
when installing the Business Process Services component of the platform.
2. Library Central.
Installing the IP Management Accelerator on UNIX
The Accelerator is supported for both UNIX and Windows platforms. To install the
Accelerator on Windows platforms, see Installing the IP Management Accelerator on
Windows.
To install the Accelerator on UNIX
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD if necessary. Use the -i option of the tar
command to avoid errors caused by long path names in the distribution that some
versions of tar can’t handle properly.
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup.IPManagement
3. First you must choose the Installation Type from the following menu
Installing IP Management
-----------------------------------------------------------Choose Installation Type
-----------------------------------------------------------1. Standard (Recommended)
2. Advanced
Select option (1-2) [1]? 1
Choose option 1 for the recommended Standard installation.
Choose option 2 to change the default settings for the prompts.
4. Next, choose the directories for the installation to use.
Choose Scripts Directories
-----------------------------------------------------------Enter build script directory path [<current_dir>]?
Enter Collaboration Platform Server installation directory
path [<current_dir>]?
424
ENOVIA Live Collaboration Installation Guide
The build script directory is the path where the scripts that build the application in
the database are placed. If you specify a directory that does not exist, the setup
program will create the directory. The default value is the current working directory.
The installation directory is the path that contains the ENOVIA Live Collaboration
Server installation. The default value is the current working directory.
5. Next you must tell the setup program where the ENOVIA Studio Modeling Platform
and where the Schema Installer are, as well as the user name and password for a user
that has Business and System Administrator privileges, such as creator. If the user has
no password, accept the default.
Specify Administration Parameters
-----------------------------------------------------------Enter directory path for Modeling Studio scripts [/usr/bin]?
Schema Installer Path
-----------------------------------------------------------Enter where schema installer exists [SERVERHOME/Apps/
Framework/<version>/SchemaInstaller]?
Enter Administrator user for Modeling Studio? [creator]?
Enter Administrator password ? [NONE]?
6. If you selected the Advanced install option, you are prompted for the following. The
Standard option accepts the defaults:
Advanced Install
-----------------------------------------------------------Do you wish to install to staging area only & Don’t update
database ? [no]?
Do you wish to undo the whole Semiconductor Accelerator for
IP Management transaction in case of failure [yes]?
Refer to Step 6. in the Installing ENOVIA products procedure for details on the
options.
7. The system checks to see if there is a version of the accelerator already installed. You
will receive a message asking you to confirm that you want to proceed. If you say yes,
the system creates installation directories, copies files to the directories, and builds the
script files. A file named installIPManagement_<VERSION>.tcl is created in Apps/
IPManagement/<VERSION>. <VERSION> is the software version number, such as
V6R2009x.
Then the setup program runs the installation scripts.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered and you chose to undo transactions in
case of errors, the setup will have undone all changes. Check the files named
installIPManagement_VERSION.log and installIPManagemente_VERSION.err in
your installation script directory to get details about errors and to see exactly which
items were added and/or modified. If there are no errors, you may still want to review
the log file to see if any items were renamed to avoid name collisions.
Chapter 16: Installing ENOVIA Products
425
8. The schema installer then creates the selected schema. If errors are encountered and
you chose to undo transactions in case of errors, the setup will undo all changes.
Check the files named installSchemaInstallerVERSION.log and
SchemaChangesMQLVERSION.log, as well as installFrameworkVERSION.log and
installFrameworkVERSION.err in your installation script directory to get details
about errors and to see exactly what items were added and/or modified. If there are no
errors, you may still want to review the log files to see if any items were renamed to
avoid name collisions.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
9. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
10. Run the war utility and deploy the application. For information on deploying an
application, see Deploying the J2EE Archive File.
Installing the IP Management Accelerator on Windows
The Accelerator is supported for both UNIX and Windows platforms. To install the
Accelerator on UNIX platforms, see Installing the IP Management Accelerator on UNIX.
To install the Accelerator on Windows
1. Log into Windows as a user with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome frame, click Next.
5. At the Installation Type prompt, check the type of install you want to perform:
Standard (Recommended)—Use this option for all standard installations. When you
choose this option, the installation will undo all transactions if it encounters problems.
You can still use the log files to find out what transactions were attempted and to
diagnose the errors. The standard installation also automatically runs the installation
scripts after copying files to the staging area, but does not install sample data.
Advanced—Choose this option only if you want to allow the installation to proceed
even if errors occur or if you only want to copy files to the staging area now and run
the installation scripts later. If you choose this option, an Advanced Options prompt
displays at the end of the installation wizard, allowing you to change these options
from their default. (See Step 11.)
Click Next.
6. The Script Path frame asks where to put the scripts that build the application in the
database. The default is the SERVER_INSTALL\Apps\IPManagement\<version>\ directory.
426
ENOVIA Live Collaboration Installation Guide
You can select a different location, if desired, using the Browse button. After
specifying the directory, click Next.
7. On the JDK directory frame, enter the path to the JDK. Click Next.
8. On the Schema installer frame, enter the path to the schema installer.
9. At the Super User/Password frame, enter the User and Password for a user who has
Business and System Administrator privileges, such as creator. If the user has no
password, leave the Password box blank. Click Next.
10. Enter the name of the bootstrap file that points to the database in which you want to
install the schema. This bootstrap file must already exist in installation directory
where Supplier Central suite is installed. When you are done, click Next.
11. If you chose the Advanced install option, the Advanced Options prompt opens.
Choose the options you want based on the descriptions below.
Install to staging area only. Don’t update database—This option is unchecked by
default, which means after you complete the installation wizard, the installation
copies all files to the staging area and runs the installation scripts to update the
database. If you want to copy files to the staging area only and run the installation
scripts later, check this option. When you’re ready to run the installation scripts, run
the installFrameworkVERSION.tcl file, located in the framework directory. To create
log and error files, use the -stderr and -stdout MQL options.
Undo whole transaction in failures—This option is checked by default. Undoing all
transactions makes it easier for you to correct problems with the new installation
without introducing errors into your existing setup. The log file for the framework
lists all transactions even if they are undone. If the transactions are undone, you can
use the log file to identify the error and then re-run setup after correcting the problem.
You should only uncheck this option, allowing transactions to proceed even when
there are errors, if you know how to correct the error or if you are just installing for
testing purposes.
12. The accelerator files are installed. When the schema portion of the install is reached,
you are asked if you want to continue. You must install the schema in order for the
accelerator to work. Click Yes to continue, No to cancel.
13. Next you are asked where custom schema files exist. Enter the path to your custom
schema directory.
It may take several minutes to run all the scripts. If you have an extensive database in
place, it could take much longer.
When complete, you receive a message telling you if the setup encountered errors or
if setup is complete. If errors were encountered, the setup will have undone all
changes (unless you chose not to undo the transactions). Using a text editor such as
WordPad, check the files named installIPManagement_VERSION.log and
installIPManagement_VERSION.err in your installation directory to get details about
errors and to see exactly what items were added and/or modified.
14. If you have backups of customized properties files, compare your customized files
with the new files from the updated version. Either update the new files with your
customizations or update your customized files with any new settings.
15. Run the war utility and deploy the application. For information on deploying an
application, see Deploying the J2EE Archive File.
Chapter 16: Installing ENOVIA Products
427
Using ENOVIA Synchronicity DesignSync Data Manager with
ENOVIA Live Collaboration
When you install the Semiconductor Accelerator for IP Management, you can optionally
enable DesignSync file access (DSFA). This entails the following:
428
•
Obtaining and installing a DSFA license key for each ENOVIA Live Collaboration
user that will use the Designsync store. Refer to the DesignSync document,
INSTALL_LICENSE.txt for details.
•
Creating a DesignSync store. Refer to the ENOVIA Live Collaboration
Administrator’s Guide for details.
•
Enable the copy from DesignSync function. Refer to the ENOVIA Live Collaboration
Administrator’s Guide for details.
ENOVIA Live Collaboration Installation Guide
Uninstalling an Application, Service Pack or
Hot Fix
If required, full application builds, service packs and hot fixes can be entirely removed by
using the Uninstall program or the Add or Remove Programs option on Windows.
During installation of a full application build, service pack or hot fix, old application files
and administration data are automatically backed up so they can be used at the time of the
uninstall. Saved code is always available in the backup area for customized applications or
if something is not working. For example, if you upgrade from Business Process Services
version V6R2011 to V6R2011x and then uninstall Business Process Services, the program
will return the database and the SERVER_INSTALL\STAGING\ directory to V6R2011.
You will need to run the war utility again.
Applications and service packs must be uninstalled in the reverse order of how they were
installed. This ensures that all the application data and files are recovered from the backup
area in the proper order. For example, if you install Business Process Services, then
Engineering Central and then Program Central, you cannot uninstall Engineering Central
without first uninstalling Program Central. An error message will be generated.
Hot fixes can be uninstalled in any order. Hot fixes that are included in an installed service
pack cannot be uninstalled individually even if you previously installed the hot fixes
separately, since some code in the service pack could be dependent on a hot fix. They can
be uninstalled only by uninstalling the service pack.
The programs (JPO, tcl), UI components (commands, menus, forms, inquiries and tables)
and Web files (jsp, jar, inc, tld, gif, jpg) can be uninstalled by using the procedure
described below, only if they are using Business Process Services provided tcl routines.
Schema changes can only be uninstalled manually. The framework install generates a
document, SchemasChanges.mql, that lists all the MQL commands that were executed to
add/modify schema. This file can be used as a reference if you want to undo any schema
changes.
After you uninstall an application, UnInst.err and UnInst.log files are added to the
SERVER_INSTALL\Apps\APPNAME\<version>\Common\UnInstall\
directory. These files contain any errors that may have occured when recovering the
database from the backup area.
Uninstalling an
Application using
Uninstall Program
To uninstall an application, service pack or hot fix using the uninstall
program
1. Go to the Uninstall directory under the component you want to uninstall. For
example, if you are uninstalling the Engineering Central application, change to the
SERVER_INSTALL\Apps\EngineeringCentral\<version>\UnInstall\
directory.
2. From the appropriate UnInstall directory, type the following command:
For Windows: UnInst.cmd
For UNIX: UnInst.sh
When you uninstall an application on UNIX, you will not be asked for the super
username or password. The program uses the username and password used when the
application was installed.
Chapter 16: Installing ENOVIA Products
429
Uninstalling an
Application using
the Add or
Remove Programs
Option on
Windows
To uninstall an application, service pack or hot fix on Windows
1. From the Control Panel, navigate to the Add or Remove Programs option.
2. Locate the ENOVIA application you wish to uninstall and click Remove.
3. At the Super User/Password frame, enter the User and Password that has Business
and System Administrator privileges, such as creator. If the user has no password,
leave the Password box blank. Click Next.
When you uninstall an application using the Add or Remove Programs option in the
Control Panel, the following items will be removed: the Programs folder containing
TCL scripts, the application specific JPOs, and the application specific web pages
located in the STAGING/enovia folder. The following items will REMAIN: the
application’s installation directory, log files, and the Install folders under the Modules
folder.
Tracking
Customizations
During installation, when a file is modified, a backup of that file is stored in the
SERVER_INSTALL\Apps\APP_NAME\<version>\UI\Backup\ directory.
During uninstall, all of the backed-up directory is copied to web root. This makes web root
look the same as it was before the application was installed.
Service pack and hot fix distributions don’t include whole jar files with all the class files.
It includes only classes that were changed from the last major release. So during service
pack or hot fix installation, the classes in the distribution jar files are inserted into the jar
file under web root. This ensures that customized class files are not affected. Before
inserting classes, old class files are backed up and they are inserted during uninstall,
making the jar file the same as the original. Backing up only changes class files and not
the whole jar file.
430
ENOVIA Live Collaboration Installation Guide
17
Installing the ENOVIA Studio
Federation Toolkit
ENOVIA Studio Federation Toolkit Installation
The ENOVIA Studio Federation Toolkit is an additional option available for creating
Adaplets that can be used to model data from virtually any source as a collection of
ENOVIA objects. Once these Adaplets are in place, other ENOVIA products may be used
to access, create, and modify all the data in their enterprise, extended enterprise, or supply
chain.
When the toolkit is installed, the standard C++ Adaplet is provided. The standard Adaplet
may be configured in your database as-is to connect an alternate data source. Also
included is a zip file containing all the files you’ll need to write a Web service adaplet.
Refer to the Studio Federation Toolkit Adaplet Programming Guide and the Studio
Federation Toolkit Web Service Adaplet Programming Guide for more information.
The C++ ANSI compiler must be used when developing custom adaplets with the mxff
toolkit.
lnstalling the
Studio Federation
Toolkit on UNIX
To mount the CD-ROM and install the software
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD in Chapter 7 if necessary.
431
2. Unzip the tar.gz file to the distribution directory. Change to the directory named “api/
install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/api/install
% ./setup
The following Menu is displayed:
Primary Setup Menu for PLATFORM on HOSTNAME as username
1. Setup ENOVIA Platform Adaplet Toolkit Installation
2. Remove ENOVIA Platform Adaplet Toolkit Installation
9. Exit Setup
3. Select Option 2 to perform the automatic setup of the Studio Federation Toolkit.
4. Setup prompts for the installation and distribution path:
Enter distribution directory path [ ]?
Enter directory for Installation [ ]?
5. The API directory structure is created in the installation directory, and then the Studio
Federation Toolkit files are copied into the appropriate directory.
The toolkit should now be successfully installed. Refer to the Studio Federation Toolkit
Adaplet Programming Guide for more information on the toolkit.
Installing the
Studio Federation
Toolkit on
Windows
To install the Studio Federation Toolkit on Windows
1. Log into Windows as a person with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. Setup first looks for an existing installation. If one is found, it asks if you wish to
install to a new location. The path may be modified as required.
5. Setup then creates the directory structure for the toolkit. Refer to Installation Results
for an understanding of the structure of the Studio Federation Toolkit.
6. The setup application then copies the interface and header files into the appropriate
directories.
The Studio Federation Toolkit should now be successfully installed. Refer to the Studio
Federation Toolkit Adaplet Programming Guide for more information.
432
ENOVIA Live Collaboration Installation Guide
Installation Results
When the ENOVIA Studio Federation Toolkit is installed on Windows, the following
directories are added:
SERVER_INSTALL
| ..... API
| .......lib
Contains mxff runtime requirements. This directory
|
is also installed with the Studio Modeling Platform
|
applications and the Live Collaboration server.
| .......mxff
Contains all the .h, .c, sample map, and .gif files.
| .......ETC
| .......service_mxff.zip Contains the WebService adaplet files.
A similar structure is created on UNIX.
Chapter 17: Installing the ENOVIA Studio Federation Toolkit
433
434
ENOVIA Live Collaboration Installation Guide
18
Installing the Studio
Customization Toolkit
Studio Customization Toolkit Installation
The Studio Customization Toolkit can be used for creating client-side “power” Java
applications that are downloaded to a client machine at runtime, as well as server-side Java
programs such as servlets or JSP applications. Studio Customization Toolkit programs are
compiled against the Live Collaboration Server’s jar file, so a Live Collaboration server is
required for both using the Studio Customization Toolkit and running the programs you
create.
Application development may not require Studio Customization Toolkit/Java
programming. You may be able to meet your requirements by using the ENOVIA
Business Process Services’ configurable components. Refer to the Application
Development Guide for more information.
The Studio Customization Toolkit provides documentation on the java classes, source
code and sample files.
Installing the
Studio
Customization
Toolkit on UNIX
To install the Studio Customization Toolkits on UNIX
1. Copy the tar.gz file from the CD or the ENOVIA Download page to the distribution
directory. Refer to Mounting the CD in Chapter 7 if necessary.
435
2. Unzip the tar.gz file to the distribution directory. Change to the directory named
“install” under the distribution directory and run the setup script as follows:
% cd /DISTRIB_DIR/install
% ./setup
The following Menu is displayed:
Primary Setup Menu for PLATFORM on HOSTNAME as username
1. Setup ENOVIA Collaboration Platform ADK
2. Remove ENOVIA Collaboration Platform ADK
9. Return to Primary Setup Menu
3. Select Option 1 to perform the automatic setup of the Studio Customization Toolkit
directory structure.
4. Setup prompts for the distribution and installation paths.
Perform automatic setup of ENOVIA Collaboration Platform ADK for
PLATFORM on HOST as username
----------------------------------------------Enter distribution directory path [ ]?
Enter installation directory path [ ]?
5. A \enovia directory is now created under the directory entered above. The Studio
Customization Toolkit directory structure is created within this directory. Refer to The
Server’s Directory Structure for an understanding of the structure of the Studio
Customization Toolkit.
6. The setup application then copies the Studio Customization Toolkit files into the
appropriate directories.
The Studio Customization Toolkit should now be successfully installed. Refer to the
online Studio Customization Toolkit Programmer’s Reference and the Application
Development Guide for more information on the Studio Customization Toolkit.
Installing the
Studio
Customization
Toolkit on
Windows
To install the Studio Customization Toolkit on Windows
1. Log into Windows as a person with Administrator privileges.
2. Copy the .zip file from the CD or the ENOVIA Download page to a temporary
directory.
Please note that when transferring the .zip file from the internet, executable files may
be silently excluded when unzipping the file due to Windows security behaviour. To
prevent this from happening, before unzipping the file, right click in the file, select
Properties, and click Unblock.
3. Unzip the zip file and run setup.exe.
4. At the Welcome frame, click Next.
5. Setup asks you to choose the options that you would like to install. Check either or
both of the following:
•
Java ADK files
•
C++ ADK files
6. Setup then asks for the Studio Customization Toolkit install directory. You can accept
the default directory or click the Browse button to choose another directory.
436
ENOVIA Live Collaboration Installation Guide
7. Now Setup asks you to review all the settings you have made, and gives you the
opportunity to make any changes by selecting Back and re-entering the information.
The Studio Customization Toolkit directory structure is created within the specified
directory. Refer to The Server’s Directory Structure for an understanding of the
structure of the Studio Customization Toolkit. The setup application then copies the
files into the appropriate directories.
The Studio Customization Toolkit should now be successfully installed. Refer to the
online Studio Customization Toolkit Programmer’s Reference and the Application
Development Guide for more information on the Studio Customization Toolkit.
Chapter 18: Installing the Studio Customization Toolkit
437
The Server’s Directory Structure
When the Studio Customization Toolkit is installed on Windows, the following directories
are added to the Live Collaboration server installation directory:
•
SERVER_INSTALL\Matrix\cxx\ which contains the C++ Studio Customization
Toolkit files (ematrixmql).
•
SERVER_INSTALL\Matrix\java\ which contains the Java docs.
A similar structure is created on UNIX.
438
ENOVIA Live Collaboration Installation Guide
19
Configuring a Japanese
Web Environment
Overview
The procedures and information in this chapter should be used to configure and deploy the
ENOVIA Live Collaboration Server in Japanese. Other similar instructions found
throughout this guide should not be used in place of the specific information given in this
chapter. You will need to use the rest of this guide for other functions not described in this
chapter, as well as for valuable reference information on the settings and procedures
described in this chapter.
Before you can configure and deploy the ENOVIA Live Collaboration Server in Japanese,
install the server and it’s prerequisites and requirements as described in Preparing to
Install the ENOVIA Live Collaboration Server in Chapter 8.
In addition to configuring and deploying the ENOVIA Live Collaboration Server, see
Configuring Additional Settings for Japanese for other important settings that need to be
configured for Japanese.
The procedures and instructions in this chapter are intended only for Shift_JIS
environments on Japanese operating systems.
439
Configuring the ENOVIA Live Collaboration
Server for use in Japanese
After you install the ENOVIA Live Collaboration Server, the environment is set with the
same variables as needed for other ENOVIA Live Collaboration clients. Use the
instructions to configure the settings described below. See Configuring the ENOVIA Live
Collaboration Server in Chapter 8 to set additional variables not described here.
These settings apply to Shift_JIS environments on Japanese operating systems.
On UNIX
Language Settings
To configure your system to use the Japanese language
1. Modify the LANG setting for the operating system.
For Solaris use: ja_JP.PCK
For RHEL/SuSE use: ja_JP.SJIS
On UNIX, the NLS_LANG value is set in the mxEnv.sh file in SERVERHOME/scripts/.
2. In the mxEnv.sh file, change the line:
NLS_LANG=_UTF8
to:
NLS_LANG=JAPANESE_JAPAN.JA16SJIS
3. Next, set the character set to Shift_JIS:
MX_CHARSET=Shift_JIS
4. Finally, add the following lines:
<mxEnv.sh>
LANG=ja_JP.PCK
export LANG
LC_TIME=C
export LC_TIME
Date and Time Format Settings
To configure the date and time format for your system for use in Japanese
1. Add the following lines to mxEnv.sh in the SERVERHOME/scripts/ directory:
<mxEnv.sh>
MX_NORMAL_DATETIME_FORMAT="moy/dom/yr4 h12:min:sec +mer"
export MX_NORMAL_DATETIME_FORMAT
For more information on how the date and time format settings affect your system, see
Configuring Date and Time Formats.
440
ENOVIA Live Collaboration Installation Guide
TCL Settings
To configure TCL settings for use in Japanese
1. Create the links for libtcl8.5.so and libtk8.5.so libraries in SERVERHOME/
<platform>/code/lib/ (LD_LIBRARY_PATH):
% cd /SERVERHOME/<platform>/code/lib
% ln -s/SERVERHOME/<platform>/code/bin/libtcl8.5.so
libtcl8.5.so
% ln -s/SERVERHOME/<platform>/code/bin/libtk8.5.so libtk8.5.so
The Tcl 8.5.7 library is installed and configured as the default version of Tcl with
installation of the desktop applications. For more information on TCL support, see Tcl
Support.
Additional Server Settings
1. Verify that the following lines are in mxEnv.sh in the SERVERHOME/scripts/
directory:
<mxEnv.sh>
MX_TRIGGER_RECURSION_DETECTION=SIGNATURE
export MX_TRIGGER_RECURSION_DETECTION
MX_ALLOW_DYNAMIC_COMPILATION=true
export MX_ALLOW_DYNAMIC_COMPILATION
On Windows
Language Settings
On Windows, you do not need to configure language settings since Japanese is the default
setting in a Shift_JIS environment. However, you should verify that the NLS_LANG value is
set to JAPANESE_JAPAN.JA16SJIS in the Windows Registry, in case the value was
previously modified to use a different language. The registry key to verify is
HKEY_LOCAL_MACHINE/Software/Oracle/NLS_LANG.
Date and Time Format Settings
To configure the date and time format for your system for use in Japanese
1. Add the following lines to enovia.ini (previously ematrix.ini) in the
SERVER_INSTALL\<platform>\code\bin\ directory:
<enovia.ini>
MX_NORMAL_DATETIME_FORMAT=moy/dom/yr4 h12:min:sec +mer
The intel_a platform is used for 32-bit Windows installations, while the win_b64
platform is used for 64-bit Windows installations.
For more information on how the date and time format settings affect your system, see
Configuring Date and Time Formats.
Chapter 19: Configuring a Japanese Web Environment
441
Additional Server Settings
1. Verify that the following is in enovia.ini (previously ematrix.ini) in the
SERVER_INSTALL\<platform>\code\bin\ directory:
<enovia.ini>
MX_TRIGGER_RECURSION_DETECTION=SIGNATURE
MX_ALLOW_DYNAMIC_COMPILATION=true
2. Verify that the folder specified for TMPDIR=C:\temp in enovia.ini (previously
ematrix.ini) exists. If not, create the folder or change the destination path of
“TMPDIR.”
Tomcat Language
Settings
To configure Tomcat for use in Japanese
1. Set csWindows31J for contentType of JSP in emxContentTypeInclude.inc.
D:\Tomcat 5.5\webapps\ematrix\emxContentTypeInclude.inc
<%@page contentType="text/html; charset=csWindows31J"%>
2. Add the following parameters in web.xml:
D:\Tomcat 5.5\webapps\ematrix\WEB-INF\web.xml
<!-- TomCat csWindows31J setting -->
<filter>
<filter-name>Set Character Encoding</filter-name>
<filter-class>com.matrixone.servlet.SetCharacterEncodingFilter<
/filter-class>
<init-param>
<param-name>encoding</param-name>
<param-value>csWindows31J</param-value>
</init-param>
</filter>
<!-- TomCat csWindows31J filter mapping -->
<filter-mapping>
<filter-name>Set Character Encoding</filter-name>
<url-pattern>/*</url-pattern>
</filter-mapping>
3. Add the attribute useBodyEncodingForURI=”true” to Connector element in
server.xml.
D:\Tomcat 5.5\conf\server.xml
<Connector
port="7070" maxHttpHeaderSize="8192"
maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
enableLookups="false" redirectPort="8443" acceptCount="100"
connectionTimeout="20000" disableUploadTimeout="true"
useBodyEncodingForURI="true" UIREncoding=”Shift_JIS”
/>
442
ENOVIA Live Collaboration Installation Guide
Configuring Additional Settings for Japanese
The settings described in this section should be configured for Japanese environments.
Displaying
Japanese using
KavaChart
To display Japanese contents using KavaChart, make the following modifications to
emxProgramCentral.properties:
On UNIX
1. In the emxProgramCentral.properties file in SERVERHOME/managed/
properties/, change:
<emxProgramCentral.properties>
#Kava Chart Fonts.
eServiceProgramCentral.kcTitleFont = Monospaced
eServiceProgramCentral.kcLavelFont = Monospaced
eServiceProgramCentral.kcLegendFont = Monospaced
On Windows
1. In the emxProgramCentral.properties file in
SERVER_INSTALL\managed\properties\, change:
<emxProgramCentral.properties>
#Kava Chart Fonts.
eServiceProgramCentral.kcTitleFont = \uff2d\uff33
\u30b4\u30b7\u30c3\u30af
eServiceProgramCentral.kcLavelFont = \uff2d\uff33
\u30b4\u30b7\u30c3\u30af
eServiceProgramCentral.kcLegendFont = \uff2d\uff33
\u30b4\u30b7\u30c3\u30af
Creating EBOM
Markups
To create EBOM markups using parts with names in Japanese, you must set the browser
language to “ja” (Japanese).
1. In emxEngineeringCentral.properties, change:
emxEngineeringCentral.ebomMarkUpCharset=UTF-8
to:
emxEngineeringCentral.ebomMarkUpCharset=Shift_JIS
2. Then change:
emxEngineeringCentral.EBOMMarkup.Run_Conversion_Code = false
to:
emxEngineeringCentral.EBOMMarkup.Run_Conversion_Code = true
Chapter 19: Configuring a Japanese Web Environment
443
NLS_LANG setting
in the Matrix client
To display Japanese in the Matrix client on UNIX
Change the NLS_LANG setting in SERVERHOME/scripts/mxEnv.sh from:
NLS_LANG=_UTF8
to:
NLS_LANG=JAPANESE_JAPAN.JA16SJIS
To display Japanese in the Matrix client on Windows
Set the NLS_LANG property to Japanese using one of the following procedures:
444
•
In the Windows Registry, under HKEY_LOCAL_MACHINE/SOFTWARE/ORACLE,
set NLS_LANG=JAPANESE_JAPAN.JA16SJIS.
•
Set the language to Japanese as a system environment variable by setting the
NLS_LANG variable to JAPANESE_JAPAN.JA16SJIS in the system
environment.
ENOVIA Live Collaboration Installation Guide
Configuring the Application Server for use in
Japanese
Before you can use your application server to deploy the J2EE application, you must
configure the application server for the Japanese language. The settings listed in this
section apply to supported WebLogic and Websphere application servers.
WebLogic Servers
Language Settings
The Japanese language setting configured in Configuring the ENOVIA Live Collaboration
Server for use in Japanese is used.
Date and Time Format Settings
To configure the date and time format for your application server for use in
Japanese
1. Verify that the following are in the emxSystem.properties file in SERVERHOME/
STAGING/ematrix/properties (UNIX), or
SERVER_INSTALL\STAGING\ematrix\properties\ (Windows):
<emxSystem.properties>
eServiceSuites.eMatrixDateFormat = MM/dd/yyyy hh:mm:ss a
eServiceSuites.eMatrixInputDateFormat = MM/dd/yyyy hh:mm:ss a
Additionally, after you build the J2EE archive file, you should verify the contents of your
emxSystem.properties file again.
Weblogic.xml Settings
Before building the J2EE archive file, you must define each JSP parameter (such as
inputCharset) in the weblogic.xml file located in
SERVER_INSTALL\ematrixwarutil\.
For example:
<charset-params>
<input-charset>
<resource-path>
/*
</resource-path>
<java-charset-name>
csWindows31J
</java-charset-name>
</input-charset>
</charset-params>
For more information on configuring the weblogic.xml file, see: http://edocs.beasys.co.jp/
e-docs/wls61/webapp/weblogic_xml.html
Chapter 19: Configuring a Japanese Web Environment
445
WebSphere
Servers
Language Settings
To configure your application server to use the Japanese language
1. From the admin console, navigate to Server > Application Server > Select Server >
Process Definition and click Java Virtual Machine.
2. Add the following parameters for the JVM arguments:
-Dfile.encoding=csWindows31J
-Ddefault.client.encoding=csWindows31J
To activate your changes, save them in the master configuration and restart the server.
446
ENOVIA Live Collaboration Installation Guide
Modifying J2EE Settings for the Japanese
Language
Before you run the war utility, you can modify the Web.xml or ematrix.xml files to
configure the web environment for your J2EE web application. For details, see Web.xml in
Chapter 10 or ematrix.xml in Chapter 10. You must configure the following settings before
running the war utility in Japanese.
In web.xml
Add the following lines before creating J2EE archive files in the web.xml file located in
SERVER_INSTALL\ematrixwarutil\:
<context-param id="ContextParam_11">
<param-name>ematrix.encoding</param-name>
<param-value> csWindows31J</param-value>
</context-param>
Content Type
Setting
The following changes are required for the content type setting:
1. In the emxContentTypeInclude.inc file in SERVERHOME/STAGING/ematrix/,
change:
<%@page contentType="text/html; charset=UTF-8"%>
to
<%@page contentType="text/html; charset=csWindows31J"%>
This is required for JSPs.
2. In the emxUICore.js file in SERVERHOME/STAGING/ematrix/common/
scripts/, replace all occurrences of UTF-8 with csWindows31J.
3. In all XSL files, replace UTF-8 with csWindows31J. For example, change:
<xsl:output method="xml" version="1.0" encoding="UTF-8"
indent="no"/>
to:
<xsl:output method="xml" version="1.0" encoding="csWindows31J"
indent="no"/>
Style Sheet
Settings
Make the following changes in SERVERHOME/STAGING/ematrix/common/
scripts/:
emxCreateBody.xsl
emxCreateFooter.xsl
emxCreateHeader.xsl
emxCreatePage.xsl
emxFreezePaneCSV.xsl
emxFreezePaneExcelHTML.xsl
emxFreezePaneHeader.xsl
emxFreezePaneJustRows.xsl
Chapter 19: Configuring a Japanese Web Environment
447
emxFreezePaneLayout.xsl
emxFreezePaneTable.xsl
emxFreezePanePrinterFriendly.xsl
emxFreezePaneRowsWithRoot.xsl
emxFreezePaneSorter.xsl
emxFreezePaneTableBody.xsl
emxFreezePaneTableFragment.xsl
emxFreezePaneTree.xsl
emxFreezePaneTreeBody.xsl
emxFreezePaneTreeFragment.xsl
emxSearchSetFormArray.xsl
emxSearchSetParams.xsl
emxUITypeChooserTree.xsl
emxUITypeChooserType.xsl
emxUITypeChooserTypeChildren.xsl
Change:
<xsl:output method="html" version="1.0" encoding="UTF-8"
indent="XXX"/>>
to:
<xsl:output method="html" version="1.0" encoding="csWindows31J"
indent="XXX"/>
448
ENOVIA Live Collaboration Installation Guide
Building the J2EE Archive File in Japanese
This section describes how to run the war utility on a UNIX and Windows platform using
Japanese. For additional reference information, see Chapter 10, Deploying J2EE.
Running the war
utility on UNIX
To run the war utility for ENOVIA Live Collaboration Server installations on
UNIX
1. Stop the ENOVIA Live Collaboration Server processes.
2. Change directory to SERVERHOME/ematrixwarutil/.
3. Run ./war_setup.
4. Enter the distribution directory path.
This is usually the ematrixwarutil directory.
5. Enter the ENOVIA Live Collaboration Server installation directory path.
This is the path where you installed the ENOVIA Live Collaboration Server.
6. Enter the name of your web application.
This is the web application name known to your J2EE server.
7. Enter the directory where the Java Development Kit is installed.
You should see a message that the system is copying files.
When finished, an EAR file is created and saved under the SERVERHOME/
distrib/ directory.
Running the WAR
utility on Windows
To run the WAR utility for ENOVIA Live Collaboration Server installations on
Windows
1. Stop the ENOVIA Live Collaboration Server processes.
2. Change directory to SERVER_INSTALL\ematrixwarutil\.
3. Run war_setup.bat.
4. On the first screen, change the installation directory or press Enter to accept the
default.
5. Type your Web Application Name, or press Enter to accept the default (“enovia”).
6. Change the directory where your Java Development Kit is installed, or press Enter to
accept the default.
You should see a message stating that the system is generating enovia.ear and
enovia.war files.
When the process is finished, you see another message stating that EAR and WAR
files have been created in the SERVER_INSTALL\distrib\ directory.
7. Press any key to end the setup process and dismiss the console window.
Chapter 19: Configuring a Japanese Web Environment
449
Deploying the J2EE Archive File in Japanese
After you run the war utility to create the J2EE archive files, you use the J2EE application
server to deploy it.
Choose the deployment procedure below for your J2EE server and platform.
An application server can only deploy one ENOVIA .war file (ematrix.war for example).
You can install as many ENOVIA applications as you would like before you run the war
utility to create the .war file. If you decide to install a second set of ENOVIA applications,
you cannot use this application server to deploy this second .war file. In order to deploy
this second .war file, you must install the ENOVIA Live Collaboration server (with an
application server) again and use this second application server to deploy it. Other
non-ENOVIA .war files can be deployed by an application server that has already
deployed an ENOVIA .war file.
Deploying on
WebLogic
To deploy using WebLogic (UNIX and Windows)
1. Start your WebLogic server.
2. Start a browser and access http://SERVERNAME:PORTNUMBER/console to
open the admin console.
3. Type your Username and Password, then click Log In.
4. On the main screen, click Lock & Edit > Deployments and then click Install under
the Control tab.
5. Click the link for your machine name.
6. Next, click on the folder. On the next screen, navigate to the location of the EAR file.
Select the web application (.ear file) to deploy and click Next.
7. Select Install this deployment as an application and click Next.
8. Verify the default settings and click Next.
9. Verify the deployment status and click Finish.
10. When the deployment is finished, the registered web application is displayed. Click
Save.
A message is shown stating “Settings updated successfully.”
11. Next, click Activate Changes.
A message is shown stating “All changes have been activated. No restarts are
necessary.”
12. Click Deployments under Domain Structure.
13. In the Control tab, select the checkbox for the web application and click Start.
14. Select Servicing all requests from the drop-down list and click Yes to continue.
A message is shown stating “Start requests have been sent to the selected
Deployments.”
15. Click Release Configuration.
The Lock & Edit button is enabled. This is the default setting of the button.
450
ENOVIA Live Collaboration Installation Guide
16. Finally, access http://HOSTNAME:PORTNUMBER/enovia/emxLogin.jsp.
If the web application has been successfully deployed, the Login window appears.
Deploying on
WebSphere
To deploy using WebSphere (UNIX and Windows)
1. Start your WebSphere server.
The shell command for starting WebSphere is stored in:
../IBM/WebSphere/AppServer/bin/
2. Start a browser and access http://SERVERNAME:PORTNAME/ibm/console
to open the admin console.
Login so that the changes you make are attributed to you.
3. Click Applications > Install New Application.
4. Select the web application (.ear file) to deploy and click Next.
5. Verify all the settings shown and continue to click Next until you reach the summary
page. Then click Finish.
The registration process begins.
6. When the process is finished, a message stating “Application <name> was
successfully installed” is displayed. Click Save in Directly Save to Master
Configuration.
7. Click Enterprise Applications and select the web application. Click Start.
The registered web application starts
8. Finally, access http://HOSTNAME:PORTNUMBER/enovia/emxLogin.jsp.
If the web application has been successfully deployed, the Login window appears.
Deploying on
Tomcat
There are multiple procedures for deploying the .war file on Tomcat. One of those
procedures is given below.
To deploy using Tomcat on UNIX
1. Stop any Tomcat processes.
2. If a previous version is installed, delete the ematrix folder including the ematrix.war
file from the /app/tomcat_install/webapps directory.
3. Clean up the cache by deleting the ematrix folder from /app/tomcat_install/
work/Catalina/localhost.
4. Copy the new ematrix.war file to /app/tomcat_install/webapps.
5. Login as root at DOS window and run ./startup.sh.
6. Finally, a notification appears when the deployment successfully completes.
To deploy using Tomcat on Windows
1. Stop any Tomcat processes.
2. If a previous version is installed, delete the ematrix folder including the ematrix.war
file from the /app/tomcat_install/webapps directory.
Chapter 19: Configuring a Japanese Web Environment
451
3. Clean up the cache by deleting the ematrix folder from /app/tomcat_install/
work/Catalina/localhost.
4. Copy the new ematrix.war file to /app/tomcat_install/webapps.
5. Double click startup.bat located in app/tomcat_install/bin.
The notification “INFO: Deploying web application archive ematrix.war” appears in
the DOS window.
6. Finally, the notification “INFO: Server startup in xxx ms” appears when the
deployment successfully completes.
452
ENOVIA Live Collaboration Installation Guide
20
Troubleshooting ENOVIA
Live Collaboration
Troubleshooting Topics
This chapter contains topics about troubleshooting the following areas:
•
Server Configuration—using the automated server configuration checker and, if
necessary, performing additional configuration troubleshooting
•
Implementation
•
Applications
•
Web Navigator
•
Desktop
•
Miscellaneous
The Server Startup Configuration Checker section describes diagnostics that the
automated configuration checker performs when a kernel is started. It provides error
messaging that can help you troubleshoot your server environment. If after running the
configuration checker you still experience performance or server shutdown problems,
refer to the Additional ENOVIA Live Collaboration Server Configuration Troubleshooting
section.
Other sections discuss various topics for troubleshooting ENOVIA Live Collaboration
implementations and miscellaneous issues.
453
Server Startup Configuration Checker
An automated configuration checker reports on common ENOVIA Live Collaboration
configuration problems that can cause severe performance degradation or server
shutdowns. The checker writes diagnostic information to an mxAudit.log file. Users can
also view diagnostic information via the MQL print config command. Refer to the
MQL Guide for details.
In a typical ENOVIA Live Collaboration environment a Live Collaboration server can
consist of one or more ENOVIA Live Collaboration kernels. The ENOVIA Live
Collaboration kernel acts like a server engine. The ENOVIA Live Collaboration kernel
encapsulates session level information and provides database independent access among
other tasks.
The Live Collaboration server can be set up for different modes of operation:
•
RMI mode—where one or more Live Collaboration kernels (RMI servers) are
running in their own Java process and the application server talks to the server(s) via
the RMI protocol. This is generally a more fault-tolerant mode; the installation script
will prompt for the number of ENOVIA Live Collaboration Servers required (gateway
setup).
•
RIP mode—where the Live Collaboration kernel is running in the same process space
as the application server and communication is made using direct calls. This is faster
than RMI mode since all code is within the same process; however, because of this,
RIP mode is not as fault-tolerant as RMI mode.
•
Gateway— If there is more than one ENOVIA Live Collaboration Server, an RMI
gateway is used to distribute tasks to each server. The server(s) do not need to be on
the same machine as the application server because the RMI protocol itself runs over
TCP/IP, and therefore the ENOVIA Live Collaboration Servers can be running
remotely.
For more information about these ENOVIA Live Collaboration Server modes, refer to
Chapter 8, Installing the Live Collaboration Server.
When each kernel loads, its initialize function calls the configuration checker, which
evaluates the settings listed below. Topics or headings in the following table have a link to
the section that describes it later in this chapter.
Setting Checked
Category
Error Range
-Xms
Critical
!=Xmx
-Xmx
Critical
<256M
-Xss
Critical
<384K
-XX:NewSize
Warning
>0.45*Xmx ||
<0.50*Xmx
-XX:MaxNewSize
Warning
!=NewSize
JVM Settings for Application Server
* On Windows platforms running non-RIP RMI, application server JVM settings are not audited. Use your application server console to
check and set recommended JVM settings.
-XX settings apply to Sun’s JVM only. These warnings should be ignored when using WebSphere’s JVM.
454
ENOVIA Live Collaboration Installation Guide
Setting Checked
Category
Error Range
-XX:SurvivorRatio
Warning
!=2
Other Java Settings
Obsolete versions of eMatrixServletXXX.jar
Critical
JVM Mode
Critical
!=Server Mode
Java Version
Critical
<1.3.1
MX_CONNECTION_POOL_SIZE
Critical
==1
MX_CONNECTION_POOL_SIZE
Warning
<10
MX_PROGRAM_POOL_SIZE
Warning
<10
MX_BOS_EXPAND_LIMIT
Warning
not set
MX_BOS_FIND_LIMIT
Warning
not set
MX_MAX_THREAD
Warning
<200
MX_TRANSACTION_TIMEOUT
Warning
not set
MX_ABORT_DANGLING_TRANSACTION
Critical
!=TRUE
MX_MEMORY_SYSTEM_LIMIT
Critical
not set
Trace Settings
Warning
Key ENOVIA Live Collaboration Environment Variables
* On Windows platforms running non-RIP RMI, application server JVM settings are not audited. Use your application server console to
check and set recommended JVM settings.
-XX settings apply to Sun’s JVM only. These warnings should be ignored when using WebSphere’s JVM.
Each setting is evaluated by the configuration checker, which reports diagnostic
information using the following categories:
•
Informational—information-only messages that might be useful when tracking down
performance issues and minor problems
•
Warning—messages indicating that a setting could cause a problem and should be
corrected
•
Critical—messages alerting that a setting will cause a problem and must be changed
These messages can be viewed using the mxAudit.log file or the MQL print config
command.
mxAudit.log File
The mxAudit.log file contains the following message types:
•
Warning
•
Critical
Informational messages generated from the application server kernel only are also written
to mxAudit.log. Informational messages from all other servers are not written to the log
file but can be viewed using the MQL print config command.
The mxAudit.log file can be found in the mxtrace file path, for example:
Chapter 20: Troubleshooting ENOVIA Live Collaboration
455
E:\enovia\server\logs\mxAudit.log
Below is an example of messages written to a sample mxAudit.log file. The log starts by
listing header information, identifying the process ID (in this case, 1870) and the
command line used to start the process being audited.
1870 10/2/2003 4:44:41 PM RMI server Process Id: 1870
1870 10/2/2003 4:44:41 PM ****Begin Kernel Audit check****
1870 10/2/2003 4:44:41 PM /usr/java/jdk1.3.1_06/jre/bin/i386/native_threads/java
-Djava.rmi.activation.port=1101 -Djava.security.policy=/app/rmi1010/java/security/
rmid.policy -Djava.rmi.server.codebase=file:/app/rmi1010/java/lib/
eMatrixServletRMI.jar -Xss512k -Xms256m -Xmx256m -Djava.library.path=/app/rmi1010/bin/
linux sun.rmi.server.ActivationGroupInit
1870 10/2/2003 4:44:41 PM ****CRIT**** JVM mode is not in server mode, add -Server to
the java command line
1870 10/2/2003 4:44:41 PM ****CRIT**** eMatrix jar version is 10.0.1.0 current version
is 10.0.1.0.CC.Linux
1870 10/2/2003 4:44:41 PM ****WARN**** Warning trace option set:
MX_VERBOSE_TRACE=verbose.log
1870 10/2/2003 4:44:41 PM ****WARN**** MX_ABORT_DANGLING_TRANSACTION environment
variable should set
1870 10/2/2003 4:44:41 PM ****WARN**** MX_MAX_THREAD environment variable should set to
at least 200
1870 10/2/2003 4:44:41 PM ****WARN**** MX_BOS_FIND_LIMIT environment variable should
set
1870 10/2/2003 4:44:41 PM ****WARN**** MX_BOS_EXPAND_LIMIT environment variable should
set
1870 10/2/2003 4:44:41 PM ****WARN**** MX_TRANSACTION_TIMEOUT environment variable
should set
1870 10/2/2003 4:44:41 PM ****WARN**** MX_PROGRAM_POOL_SIZE environment variable should
not be less than 10
1870 10/2/2003 4:44:41 PM ****CRIT**** MX_CONNECTION_POOL_SIZE environment variable
cannot be default (1)
1870 10/2/2003 4:44:41 PM ****WARN**** MX_CONNECTION_POOL_SIZE environment should be at
least ten
1870 10/2/2003 4:44:41 PM ****WARN**** Class garbage collection should be enabled
(remove -Xnoclassgc)
The above log content shows several warning and critical messages to which you should
respond. For information about any of the settings, see Evaluation Details.
On the Sun Java System Application Server platform, mxAudit.log does not report the JVM
command line that Sun Java System Application Server is running.
When running the following platforms, MxAudit.log reports invalid output:
•
Any application server running on Windows as a service in RIP mode and uses an
executable to launch rather than the command line (such as launching WebLogic
using “beasvc”).
•
Sun Java System Application Server (a.k.a. SunONE) on Solaris
The workaround is while configuring and testing, don’t enable the service as the startup
mechanism, so that the process is started by a call to Java and so mxAudit will report the
correct results. Once any problems are resolved you can turn off the audit log and switch
to the service startup.
456
ENOVIA Live Collaboration Installation Guide
Disabling the Audit Log
Once you are up and running you may want to turn off the Audit log so it doesn’t run every
time you restart the server.
To turn off the Live Collaboration Server Audit
1. Add the following to the enovia.ini for the Live Collaboration Server (previously
ematrix.ini) (Windows) or mxEnv.sh or startup script (UNIX):
MX_DISABLE_AUDIT=true
export MX_DISABLE_AUDIT
You only need to export the setting on UNIX.
2. In the web.xml file set the following to false, for example:
<context-param id="ContextParam_12">
<param-name>ematrix.audit.log</param-name>
<param-value>false</param-value>
</context-param>
Evaluation Details
This section describes the configuration settings that are evaluated by the automated
configuration checker. It describes why certain settings are preferable in a ENOVIA Live
Collaboration environment. You should consult this section if you want information about
a setting, especially if you need to change a setting based on a warning or critical message.
Note that the introduction to the Server Startup Configuration Checker section contains a
table that lists configuration settings with links to topics in this section.
JVM Options
Java Virtual Machine options are one of the most important groups of settings. They are
passed on the command line to the JVM at run time and affect both the ENOVIA Live
Collaboration Servers and application servers running with the ENOVIA Live
Collaboration. Each server mode has its own set of options; the list of options for the
application server in RMI mode are a subset of the settings for the ENOVIA Live
Collaboration Server and for the application server in RIP mode.
JVM options can affect both server stability and performance and therefore are considered
critical.
Note that in ENOVIA Live Collaboration, objects generally have a relatively short
lifecycle, which accounts for some JVM option recommendations. If a JVM option in the
tables is not set, the JVM will assume a default that will not be correct. JVM defaults are
intended for a small number of objects having a long lifespan, which is the opposite of
what ENOVIA Live Collaboration requires.
Java options that are not supported on AIX will not be present in the mxEnv.sh or
rmireg.sh files for the AIX platform.
-Xms
-Xms (minimum heap size) should match the maximum heap size value. Since the JVM
will begin by allocating the minimum heap size and grow from there, it will spend time
requesting memory from the system once it crosses the minimum memory boundary.
Setting both the maximum and minimum heap sizes to the same value allows the JVM to
Chapter 20: Troubleshooting ENOVIA Live Collaboration
457
allocate the maximum amount up front and not request any more from the system. This
also shields the JVM from other processes in the system taking all the available memory
and starving the JVM.
-Xmx
-Xmx is the maximum heap size. Since a large number of objects can be temporarily
cached by the server, this parameter should not be left at its default size (64M). A value of
256M is recommended even for the smallest installations. As a rule, if there are hundreds
of users, this value should be doubled, and tripled if there are thousands. This setting is
platform-dependent, but should never exceed 1.5G. For more information about
determining the value of -Xmx, see Calculating Maximum Heap Size (-Xmx JVM option).
-Xss
-Xss sets the maximum stack size to be used by threads. Every thread that is spawned
during the execution of the program passed to Java has this value as its stack size.
Therefore, this setting sets the stack size of threads running in the Live Collaboration
server. If this option is omitted, the JVM will select values for some operating systems and
for others it will use the operating system's default thread size. This system value is
different depending on the operating system used (i.e. on Windows 2000 it's 1M, but on
some Unix versions it can be as low as 64K). It's important to use this option to guarantee
that the Live Collaboration server has enough stack space to function correctly.
For Sun Java System Application Server, increase the StackSize setting in /var/opt/
SUNWappservere7/ domains/domain1/server1/config/init.conf to
at least 512 KB, particularly if you are running RMI in process (RIP). Refer to Sun
documentation for tuning recommendations. The default setting is 130 KB, which is not
large enough, and if not set correctly, will cause certain operations in ENOVIA products to
fail.
-XX:NewSize
This setting governs the size of the eden memory pool allocated (i.e. the amount of
memory allocated for new objects versus the amount of memory allocated for keeping
older objects). This should be calculated as between .45 to .50 of the maximum heap size
value. Newer objects are transferred by the JVM's “garbage collection” system to the older
pool. Keeping the NewSize relatively high (compared to the maximum heap size) benefits
ENOVIA Live Collaboration processing because ENOVIA Live Collaboration objects are
not expected to persist for a long time-most not long enough to be transferred to the old
pool.
-XX:MaxNewSize
This is set to the same size as the NewSize to save time allocating more memory for the
eden pool.
-XX:+DisableExplicitGC
This option prevents Java code executing within the Java process from forcing garbage
collections by calling, for example, system.gc().
This setting is no longer checked by the configuration checker. In general, explicit garbage
collection should be enabled; that is, this setting should not be used.
Use of this setting has been found to delay fullGC from occurring and thus remote objects
with c++ references might be kept active longer than necessary.
-XX:SurvivorRatio
458
ENOVIA Live Collaboration Installation Guide
This is the ratio of the eden space (the memory pool allocated for newer objects that have
been created) versus the pool for older objects. The Sun JVM default is 25, but ENOVIA
recommends a value of 2 since most objects have a short lifespan.
-XX:MaxPermSize
This setting is the amount of memory set aside for loading all necessary classes that are
needed by an application. This setting may need adjustments, particularly in a WebLogic
7/RMI RIP configuration. Refer to Installing a WebLogic Server in Chapter 8 for details.
-XX settings are for use with Sun’s JVM only.
JVM Options for ENOVIA Live Collaboration Servers
For ENOVIA Live Collaboration Servers, JVM settings can usually be retrieved from
either the rmireg.sh file (on Unix/Linux) or the rmireg.bat file (on Windows). An
exception is when the ENOVIA Live Collaboration RMI service is used. A service called
rmiservice will be running at machine startup; each ENOVIA Live Collaboration Server is
spawned by this service and the JVM options are kept in the registry.
ENOVIA Live Collaboration Servers are spawned by the rmid (also known as the RMI
daemon), which is a process shipped with the Java Development Kit (JDK). The
rmireg.bat, rmireg.sh, or the rmiservice will spawn this process and pass it a list
of the JVM options. Each option is prefixed by "-C". For example, the initial heap size
option would typically be -C-Xms256m. The rmid must know that this is a JVM option
in order to be passed to any ENOVIA Live Collaboration Servers it creates. On Windows,
open the rmireg.bat file and find the rmid start line. (Unix is the same except from the
"start "RMI Daemon 1099" /min" line is at the beginning.). Then using the JVM Settings
for Application Server table, verify that the JVM options are at least the minimum value.
Following is a sample rmireg.sh file:
JAVA_OPTIONS="-C-Xss512k -C-Xms256m -C-Xmx256m -C-XX:NewSize=128m
-C-XX:MaxNewSize=128m -C-XX:SurvivorRatio=2"
JAVA_SECURITY=-Djava.security.policy=/matrix/rmi1100_EPC/<platform>/docs/
security/rmid.policy
${JAVA_PATH}/rmid $1 $JAVA_OPTIONS -J$JAVA_SECURITY -port 1100
-XX settings are for use with Sun’s JVM only.
JVM Options for ENOVIA Live Collaboration Servers on
Windows
For rmiservice, the JVM options are kept in the registry and can be viewed by running
regedit. Under the
HKEY_LOCAL_MACHINE\SYSTEM\SOME_CONTROL_SET\Services path is a list
of all installed services. The rmiservice settings are in a key called "eMatrix RMI Server".
The registry editor shown below displays a typical list of parameters for the RMI service.
The JAVAOPTIONS value that is highlighted contains a list of the options the rmid will
pass to the spawned ENOVIA Live Collaboration Server. By double-clicking on the value
Chapter 20: Troubleshooting ENOVIA Live Collaboration
459
the list may be modified. Once again, verify the JVM options against the JVM Settings for
Application Server table.
JVM Options for Application Servers
If the application server is setup for RIP mode, the JVM options for the application
server's own JVM must also be verified. Finding the command line information that
created the JVM varies among the application servers. The table below contains a list of
default file names and command lines that start the application server JVM:
Application Server
Default files to find JVM options
WebSphere (All
versions)
INSTALL-DIR\AppServer\config\cells\HOST\nodes\HOST\servers\server1\server.xml. These
can be set via the WebSphere Administrative Console. Refer to WebSphere JVM Options.
WebLogic version 7.x
INSTALL-DIR/user_projects/yourDomain/startWeblogic.sh
Tomcat 4.1x
INSTALL-DIR/bin/Catalina.sh
Sun Java System
Application Server
version 7.x
INSTALL-DIR/domains/yourDomain/yourServer/config/server.xml
With the exception of the Sun Java System Application Server and WebSphere servers, all
other files are startup scripts or batch files. For all servers (except for Sun Java System
Application Server) edit the startup file and locate the Java command line.
Following is an example from the tomcat.sh file:
460
ENOVIA Live Collaboration Installation Guide
$JAVACMD $TOMCAT_OPTS -Djava.security.manager
-Djava.security.policy==${TOMCAT_HOME}/conf/tomcat.policy
-Dtomcat.home=${TOMCAT_HOME}
org.apache.tomcat.startup.Tomcat "$@" &
Note the TOMCAT_OPTS environment variable, which can be used to pass in JVM
options. It is necessary to check both the command line itself and the TOMCAT_OPTS
environment variable to verify the JVM options in use.
Below is an example from the WebLogic 7 default startWeblogic.bat file:
%JAVA_HOME%\bin\java %JAVA_VM% %JAVA_OPTIONS% %DB_JVMARGS% -Xmx256m -classpath
%WLISERVERCP%
-Dweblogic.servlet.ClasspathServlet.disableStrictCheck=true
-Dwli.bpm.server.evaluator.supportsNull=false
-Dweblogic.management.username= -Dweblogic.management.password=
-Dweblogic.Name=codonnell -Dweblogic.RootDirectory=%WLI_DOMAIN_HOME%
-Djava.security.policy=%WL_HOME%\lib\weblogic.policy
-Dweblogic.management.discover=false
-Dweblogic.ProductionModeEnabled=%STARTMODE%
weblogic.Server
Note the JAVA_VM variable allows JVM options to be specified from the environment.
Additionally, WebLogic sets a default heap size of 256M (the -Xmx256m in the command
line). Because it is in the command line after the JAVA_VM environment variable, it will
probably override any value set by JAVA_VM.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
461
If you are using the Sun Java System Application Server, the administrative console must
be used, as shown below. Using the console, JVM options for each configured server may
be added, deleted, or modified.
Check all options in the JVM Settings for Application Server table. If any of the options do
not exist or are wrong, you can change them using the JVM Settings panel shown above.
For all Application servers or ENOVIA Live Collaboration Servers using the
Sun JVM:
Note that IBM JVMs are derived from Sun's JVM, so the following tip may also work for
those JVMs. Below is a quick way to check the parameters used to load the JVM:
SET _JAVA_LAUNCHER_DEBUG=1
On Unix, enter the following before running the server:
export _JAVA_LAUNCHER_DEBUG
The JVM will send each option it parses to stdout, usually the console of the window
running the JVM. This will show the complete list of options passed to the JVM and
directly allow verification of the options. Remember to switch this off after verifying the
values, even though it is only a startup diagnostic and will not affect server operation other
than having the server load a little slower.
WebSphere JVM Options
462
ENOVIA Live Collaboration Installation Guide
JVM options in WebSphere can be found using the WebSphere Administrative Console, as
shown below.
To see the JVM settings panel shown above, select Nodes > YOUR DOMAIN >
Application Servers > YOUR SERVER NAME > Process Definition > JVM Settings.
Verify that the Initial Heap Size field does not have a value less than the minimum value
for the -Xms parameter listed in the JVM Settings for Application Server table. Then
verify the Maximum Heap Size value, which corresponds to the -Xmx option. The
Generic Command Line Arguments field should contain all other options found in the
JVM Settings for Application Server table. For example, for a maximum heap size of
256M running in RIP mode, the Generic Command Line Arguments might contain:
<jvmEntries xmi:id=’JavaVirtualMachine_1’ verboseModeClass=’false’
verboseModeGarbageCollection=’false’ verboseModeJNI=’false’ initialHeapSize=’0’
maximumHeapSize=’256’ runHProf=’false’ hprofArguments=’’ debugMode=’false’
debugArgs=’-Djava.compiler=NONE -Xdebug -Xnoagent
-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=7777’ genericJvmArguments=’’>
<classpath></classpath>
<bootClasspath></bootClasspath>
</jvmEntries>
For more information, refer to http://publib.boulder.ibm.com/infocenter/wasinfo/v6r1/
index.jsp.
Calculating Maximum Heap Size (-Xmx JVM option)
A simple way to calculate the value for the -Xmx option is to use the figure for half the
available memory on the system and divide that among the number of JVMs that both the
application server and ENOVIA Live Collaboration Server (if used) are running. Using
system commands described in previous sections, the number of JVMs can be counted
manually; however, you should know how to calculate the number of Java processes
(JVMs) that should be running since this could help track down any unwanted Java
processes during troubleshooting. Reading the installation guide that comes with your
Chapter 20: Troubleshooting ENOVIA Live Collaboration
463
application server is highly recommended since it should include details of features, such
as load balancing, that may add more JVMs than would normally be expected. Because
these extra JVMs will consume memory, they should be subtracted from the total available
memory. One such JVM is the so-called nanny process, which is described below.
Starting with no applications running on the system, use the methods described in
Checking Memory Usage to find the current amount of available memory. If a high degree
of accuracy is required, take readings over several days, and calculate an average value. If
the machine runs a backup program, find the amount of memory used by the backup
program and subtract it from the amount of available memory. Now you will have
determined the actual amount of available memory for the application and Live
Collaboration servers.
Calculating the maximum heap size involves a simple formula that requires knowing the
number and type of JVMs that will run on the machine. This number depends first on the
whether RMI or RIP mode is used. The ENOVIA Live Collaboration Servers may or may
not be running on the same server; if they are not, the number of JVMs will equal the
number of JVMs running in the application server. The number of Java processes in the
application server depends on whether the server has one or more nanny processes. For
example, WebSphere and WebLogic both have a nanny process, which is a monitoring
process that requires at least 128M. Refer to your application server guide for information
about nanny processes and whether they are used.
The number of application server JVMs denotes the number of Java processes configured
to support the ENOVIA Live Collaboration domain. If a second domain is running on the
application server, the amount of available memory will be affected by the memory
consumed to run that domain and therefore should be subtracted from the current amount
of memory to become the available memory figure used in the formulas below.
If a nanny process is used, subtract 128m from the available memory before applying any
of the formulas below.
Following are the formulas for maximum heap size:
RMI mode where the ENOVIA Live Collaboration Servers are not running on the
same machine:
server JVM memory = available memory - 128m
maximum heap size = server JVM memory / number of application server JVMs / 2
The number of application server JVMs is typically one per application server domain
running on the machine.
RMI mode where ENOVIA Live Collaboration Servers are running on the same
machine:
If there is more than one ENOVIA Live Collaboration Server, the RMI gateway is used.
This is similar to an application server nanny process but is used to monitor and distribute
the load for multiple ENOVIA Live Collaboration Servers. It requires 128M.
RMI mode with one ENOVIA Live Collaboration Server:
server JVM memory = available memory - 128m
per process memory = server JVM memory / (number of application server JVMs +
1)
maximum heap size = per process memory / 2
464
ENOVIA Live Collaboration Installation Guide
RMI mode with more than one ENOVIA Live Collaboration Server:
server JVM memory = available memory - 128m
per process memory = server JVM memory / (number of ENOVIA Live Collaboration
Servers + number of application server JVMs)
maximum heap size = per process memory / 2
RIP mode:
server JVM memory = available memory - 128m
per process memory = server JVM memory / (number of application server JVMs)
maximum heap size = per process memory / 2
In RIP mode, the Live Collaboration Server kernel shares the same process as the
application server.
The Java Process Command Line
This section provides a quick way for finding JVM options for application and ENOVIA
Live Collaboration Servers running on Unix. It involves using the ps command to retrieve
the Java process command line, as described in Checking for Other Running Processes.
For example, checking the JVM options for a particular server can be done simply by
looking at the command line of the server's Java process.
Application server startup scripts typically pass their home directory as a property on the
command line to their Java processes. Java properties are prefixed with a -D and are a
means of passing a parameter to any Java code running in the process, such as the
application server's own code or the Live Collaboration server running in RIP mode. For
example, if the Java command line contains
-Dtomcat.home=${TOMCAT_HOME}
then the Java process is a Tomcat application server and its home directory can be found in
the TOMCAT_HOME environment variable. This is the home directory for the application
server and can be used to locate startup scripts and configuration files, as required in
Collecting Logs and Core Files.
The following table shows a list of properties that can be used to locate a Java process.:
Process
Identifier
java.rmi.activation.port
ENOVIA Live Collaboration
Server
catalina.home
Tomcat version 4 Server
weblogic.home
WebLogic Server
com.sun.aas.installRoot
Sun ONE Server
server.root
WebSphere Server
The java.rmi.activation.port property is in the following format:
-Djava.rmi.activation.port=1099
Chapter 20: Troubleshooting ENOVIA Live Collaboration
465
It shows the ENOVIA Live Collaboration Server port, which is useful when using the RMI
Gateway with multiple ENOVIA Live Collaboration Servers running on different ports.
When running in RMI mode, a process called rmid is loaded and used to start ENOVIA
Live Collaboration Server(s) on demand. Its command line includes the JVM options that
will be passed to any ENOVIA Live Collaboration Server it creates and the port on which
the ENOVIA Live Collaboration Server will be listening.
Process Limitations
Most of the Java options described above relate to settings that control memory allocation.
Keep in mind that there are other factors that may limit the resources available to a process
and thereby constrain a process beyond the memory settings discussed above. Examples of
such factors are:
•
Limit settings in the environment, such as ulimit (sh) or limit (csh) on Unix
•
The binary itself. For example, AIX defines the addressable memory in the
executable. (See TechTip 11237.)
•
The data parameter for ulimit should be set to “unlimited” for AIX.
Other Java Settings
The startup configuration checker evaluates these other key Java settings:
•
Obsolete versions of eMatrixServletXXX.jar
•
JVM Mode
•
Java Version
All settings may be retrieved using the startup files listed in the Application Server table.
For all application servers, except for Sun Java System Application Server, edit the startup
script and find the JAVA_HOME variable in the file. This will point to the java.exe (it may
be in a bin or jre directory beneath this path). Run this java.exe from a command line with
the -version argument to retrieve the Java version, and use the value in the above table to
verify that the number is not less than the minimum value.
The configuration checker checks for obsolete versions of eMatrixServletXXX.jar by
comparing Java and native versions of eMatrixServletXXX.jar. Any obsolete versions will
generate a Critical error.
The JVM mode may not be obvious since most application servers leave it at the default
value. The available modes for the Sun JVM can be, for example, classic, client or server.
Server mode must be the mode used for all configurations.
There are two ways to set the JVM mode:
1. Make the first parameter in the Java command line -server.
2. Edit the jvm.cfg file pointed to by the JAVA_HOME variable and make -server the
first line after the comments in the file. If your platform does not have jvm.cfg,
refer to your JVM documentation for the location of -server.
Using the second method avoids a problem in which you cannot add -server to the
RMI daemon command line in the rmireg.sh file since it fails.
It can be assumed that if the Java version is correct then the JVM version should also be
compatible. However, on Windows particularly, care must be taken to ensure that there are
no other jvm.dlls in the Windows or Windows system directories that could cause a JVM
mismatch and shut down the JVM.
466
ENOVIA Live Collaboration Installation Guide
The JVM version and mode is actually displayed in the startup messages for the Sun Java
System Application Server. WebLogic also displays a list of the Java system properties on
load, which also contains the JVM version and mode.
If the JVM is controlled by the application server, the configuration checker may not be
able to detect the presence of -server and it will generate an error. If this situation occurs,
verify that your application server does set -server and ignore the error in mxAudit.log.
Key ENOVIA Live Collaboration Environment Variables
The configuration checker evaluates key ENOVIA Live Collaboration environment
variables that can be easily overlooked. Setting them appropriately for system-wide use
can improve performance dramatically. These variables may have been set originally by an
ENOVIA engineer, but during upgrades of an application server the variables may be lost
because a new application server startup script is used.
For RIP mode, check the application server's startup script (see the Application Server
table) for the environment variables or for a script that gets executed that may set them
externally.
A good tip for checking what is being set is to locate the line in the script files that starts
the JVM (usually it's near the end and will begin with java-install-path/bin/java) and insert
a line that pipes the environment to a file.
Example for Unix:
env > env.fil
and for Windows:
set > env.fil
Start the application server and edit the env.fil file. Search for the environment
variables listed in the ENOVIA Live Collaboration environment variable table.
The MATRIXHOME environment variable should be noted since most traces and scripts are
found using this path.
This method should be used if using ENOVIA Live Collaboration Servers. In this mode
ENOVIA Live Collaboration Servers are started using rmireg.sh (Unix) or
rmireg.bat (Windows).
A good practice to ensure that the environment variables are set is to create a script or
batch file that contains them and call the script from the application server startup script or
from rmireg directly.
In Windows, environment variables are checked as follows: the enovia.ini file is checked
first; if the variable does not exist then the environment is checked. If still not found,
internal defaults are used.
When using the RMI service, environment variables may be also set in the registry. In the
Windows Registry Editor a registry key called "Env" can exist under the following key:
HKEY_LOCAL_MACHINE\SYSTEM\Services\eMatrix Rmi
Service\Parameters
This key can contain ENOVIA Live Collaboration environment variables as registry
values. When the RMI service starts it will add these to its environment. These variables
can be changed or added directly using regedit or by using the rmiservice with some
parameters, for example:
Chapter 20: Troubleshooting ENOVIA Live Collaboration
467
rmiservice -config "eMatrix RMI Server" -javaoptions
"-C-Xss256k"
or
rmiservice -config "eMatrix RMI Server" -setenv LANG=C
-setenv
NLS_LANG= American_America.UTF8 -setenv MX_CHARSET=UTF8
Note that "eMatrix Rmi Server" is the default RMI registry key name.
For more information about each ENOVIA Live Collaboration environment variable, see
Configuring ENOVIA Live Collaboration in Chapter 9 and Installing the Live
Collaboration Server in Chapter 8.
System Scaling
To properly scale your system to meet loads for the maximum number of concurrent users,
you need to correctly set the MX_CONNECTION_POOL_SIZE and your Oracle Sessions.
The default value setting depends on the Java Heap size entered during installation.
However, you should monitor the ENOVIA Live Collaboration instance in the database
under typical production usage levels over a period of time and observe the number of
sessions opened. This will provide a good indication of the value to use for your
MX_CONNECTION_POOL_SIZE.
If more connections are required, you could increase this value by 10 or more to the value
that works for your implementation under typical production usage levels.
You may also need a larger MX_CONNECTION_POOL_SIZE value if numerous errors
like the following are thrown:
Error #4000045 Creating new database connection, pool size
insufficient
This message is generated when the server needs to open a new connection. If this
happens on a regular basis, the current MX_CONNECTION_POOL_SIZE value is too low.
Additionally, you should consider the Java heap sizes. -Xms (minimum heap size) should
be at least 768m for large systems. -Xmx (maximum heap size) is platform-dependent, but
should never exceed 1.5g.
Note that when determining the Java heap size, you need to consider that a similar amount
of memory is also needed by the ENOVIA Live Collaboration C++ kernel, which runs in
the same process as the JVM but in a separate memory space, and which is not controlled
by the Java heap size setting.
Trace Settings
Traces that are accidentally left switched on can greatly affect server performance. When
you encounter performance problems, a check for these is advised. Refer to Overview in
Chapter 21 for details.
468
ENOVIA Live Collaboration Installation Guide
Additional ENOVIA Live Collaboration Server
Configuration Troubleshooting
If performance problems or server shutdown persist after changing settings resulting from
the server startup configuration checker, there are other areas you can check. Performance
problems and server shutdown can be caused by improper configuration settings resulting
in insufficient memory. Problems can occur if memory requirements that change due to
objects cached in memory grow to exceed the amount of allocated memory within a Java
Virtual Machine or even the entire system. Other problems may contribute, such as lack of
disk space or inadequate memory for a machine's current load. It is sometimes difficult to
determine the source of these problems. Environments vary in type of application server,
platforms, server machine specifications, and operating system versions—to name some
of the obvious configuration components.
When problems occur after you have diagnosed your system with the configuration
checker, you should check your system for these potential problem areas:
•
Checking Disk Space
•
Checking Memory Usage
•
Checking for Other Running Processes
•
Reviewing Other Configuration Issues
•
Collecting Logs and Core Files
Collecting logs and cores file is optional and needs to be performed only if the problem
has not been resolved using the previous procedures.
Tables in this section may contain a column entitled "Category". Settings in these tables
fall into one of three categories:
•
Critical
•
Warning
•
Information
The category refers to the level of priority that should be given to the particular setting. For
example, if a setting is referred to as Critical, the ENOVIA Live Collaboration Server
should not be run if the setting either does not exist where it should appear or it is outside
the minimum range specified in the table. Settings that are Warnings should be set within
the minimum range of values in the table. Information settings have the lowest priority but
have been known to cause problems. In other words, they may not be a problem in a
particular environment, but they should not be ignored.
The guidelines described in this section are intended to provide basic methods for
investigating and resolving performance and quality-of-services issues. Recommended
settings may not always result in better performance and may require further tuning.
The following sections describe each troubleshooting procedure in detail.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
469
Checking Disk
Space
The table below shows how to check for available disk space on each platform.
Platform
Command
Examples
Windows
chkdsk or dir
dir c:\
Solaris
df -Pk
df -k /tmp
AIX
df -Pk
df -k /tmp
In a production environment, the database should not be on the same machine as the
application server. Any disks in use should have more than ten percent free space. In
particular, the drive pointed to by the workspace environment variable
MX_BOS_WORKSPACE should have enough space. The workspace is a space where files
can be stored temporarily during file checkouts and other operations; as a rule, it should be
as large as the largest file that would be checked out, multiplied by the number of users on
the system. For Unix users, the /tmp directory should be relatively free too.
Checking Memory
Usage
For some versions of Unix, the "top" utility is a very powerful tool. It usually comes
installed on the machine and can give live CPU and memory stats on a configurable
refresh time. For Windows, the Task Manager is very useful.
On Unix platforms, you can also use the vmstat command to check available memory:
Platform
Command
Solaris
vmstat
AIX
vmstat svmon -g
Note that when using "top" or vmstat, the figures for process memory usage can be
artificially inflated because some Unix versions of the memory manager do not always
show freed memory returned to the system "pool". If the system has enough free memory
to satisfy its current needs, memory freed by a process will not automatically be shown as
freed. Therefore, utilities such as "top" tend to show the peak amount (or "high water
mark") of memory that a process has allocated rather than what the process is currently
using.
If "top" is not available, on Solaris use prstat, or on AIX, use topas. On Solaris,
another useful command is prtconf, which shows the system configuration. Also on
Solaris, the /usr/proc/bin/pmap -x PID will print the details of memory used by
a process and indicate which PID is taking up the memory.
It's a good idea to monitor the amount of swap in use. The system should not swap, and all
processes should be in physical memory. Use a utility, such as "top" or vmstat, to
determine swap activity. You should also note the process path (the path where the process
was loaded from) and its command line. Since there usually are multiple Java processes
running at the same time, the command line should give a clue as to whether a particular
process is an application server or an ENOVIA Live Collaboration Server. Since "top"
does not typically show the process path, you should note the process id (PID) of the
larger processes from top's PID column. You can get the process path and command line
using the "ps -ef" command and using the PID to find the process in the resulting list.
470
ENOVIA Live Collaboration Installation Guide
Checking for Other
Running
Processes
Other processes can cause problems; for example, you might have unnecessary processes
still running. You should check for orphaned Java processes or executables, which may be
consuming available memory. Use the ps command as shown in the table below and
check the command line parameters.
Platform
Command
Description
Solaris, AIX
ps -ef | more
Lists all processes.
ps -ef | grep java
Lists all processors using
Java.
ps -u <username>
Use the userid of the
ENOVIA Live Collaboration
installation user to see the
process for that user.
Because the ps command can truncate the command line, you might check whether your
ps command supports the "auxwww" argument, which provides a listing with the full
command line for each process. You should use the UCB version of the ps command, if
installed. It is usually found in the /usr/ucb/bin directory.
A Java process's command line provides quick access to a lot of information required
while checking your configuration. The next section shows how the command line can
help you determine whether a Java process is ENOVIA Live Collaboration-related (i.e.
related to an application server or a Live Collaboration server) or related to some other
application.
Reviewing Other
Configuration
Issues
This section describes configuration settings you should check that pertain to your
application server, kernel and device driver settings, and your operating system patch
level.
Application Server Settings
Most application servers have some performance tuning parameters available, some of
which are highly recommended. For example, WebLogic has an execute thread count that
is used when trying to ensure that a pool of threads is available to process servlet requests
as the overhead of creating new threads within the application server can be expensive.
Config.xml has:
Server ExternalDNSName="acme.net"
ListenAddress="acme.net" Machine="MyMachine"
Name="myserver" ServerVersion="7.0.1.0"
StdoutDebugEnabled="true" StdoutEnabled="true"
StdoutSeverityLevel="64" WeblogicPluginEnabled="true"
XMLEntityCache="XMLCacheMBean_myserver">
<COM Name="myserver"/>
<ExecuteQueue Name="default" ThreadCount="15"/>
Other application servers have an equivalent to this setting.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
471
Settings are viewed or changed using the WebLogic Administration Console, as shown
below. The console requires an administrator userid/password to log on.
To view and change WebLogic settings:
Use the WebLogic Server Console, as shown above.
1. Select Servers from the left pane.
2. Select the Live Collaboration server from the left pane.
3. Select the Configuration tab from the right pane.
4. Select the Tuning tab from the right pane.
On WebLogic 7.x the Accept Backlog parameter is found on the Tuning tab from the
Connections tab.
WebSphere Settings
WebSphere typically uses the IBM HTTP Web server, which is Apache-based and has the
equivalent of WebLogic's acceptBacklog parameter, which is the MaxConnectBacklog
472
ENOVIA Live Collaboration Installation Guide
parameter. The parameter can be configured using the Administrative Console, as shown
below:
Choose Nodes > YOUR DOMAIN > Application Servers > YOUR SERVER > Web
Container > HTTP Transports > YOUR PORT.
From this panel the MaxConnectBacklog parameter can be modified. However, the default
of 511 is usually sufficient.
If WebSphere is running on Windows with Microsoft's IIS server as its Web server, the
equivalent of WebLogic's acceptBacklog parameter is ListenBackLog, which has a default
value of 25. IIS reads this value from the registry entry, which is shown below:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\InetInfo\Parameters\
ListenBackLog
The value should be changed to 250, and IIS must be restarted.
Additionally, if the settings listed below appear on your Administrative Console, check
that their values are at least equal to the minimum values. If not found on your console,
ignore them.
WebSphere Settings from IBM HTTP Server's
httpd.conf
Category
Minimum Value
ListenBackLog
Warning
>= 511 (default)
MaxClients (Unix Only)
Critical
>= 150 (default)
ThreadPerChild (Windows only)
Critical
>= 50 (default)
Maximum Pool size
Critical
>= 30 (default)
Chapter 20: Troubleshooting ENOVIA Live Collaboration
473
Operating System Patches
Bugs in operating systems can take a long time to diagnose. Therefore, a check for patch
levels is highly recommended.
The table below shows a list of commands that retrieve the operating system patches on
supported Unix platforms. On Windows, simply type winver at a command prompt. Piping
the output from the Unix patch list to a file is advisable since this can be sent to ENOVIA
Support for further diagnosis.
Unix Platform
Category
AIX
istfix; smit
(Use smit only if patches were
originally installed using smit;
if not, use istfix.)
Solaris
showrev -p
Kernel and Device Driver Settings
As described in Collecting Logs and Core Files, kernel settings can be extremely
important. File descriptors are another problem source, though typically for earlier
versions of Solaris since most Unix platforms have fairly large default values. Windows
does not have this problem (except when portable code uses file descriptors for winsock
IO).
To find the maximum number of file descriptors available:
•
in ksh use "ulimit -n"
•
in csh use "limit descriptors"
Some parameters have an affect on performance, including TCP settings on Solaris, as
shown below.
Solaris TCP Parameter
Description
Suggested Value
tcp_close_wait_interval
On high connection rates if netstat shows
many sockets in CLOSE_WAIT or
FIN_WAIT_2 state
60000
tcp_fin_wait_2_flush_interval
Checks the fin wait interval (some versions of
solaris can be 10 times the normal value)
67500
Use the following command to get a parameter from the table:
ndd -get /dev/tcp parameter
Use the following command to set a parameter in a table:
ndd -set /dev/tcp parameter
474
ENOVIA Live Collaboration Installation Guide
Symbolic Links
Previous versions of the Live Collaboration server created symbolic links to /usr/lib for a
library in the installation directory. If not removed, these links frequently caused problems
with mismatching library versions. Use "ls -l /usr/lib" to verify library versions.
Depending on the operating system, ENOVIA Live Collaboration libraries are only loaded
through appropriate settings of LD_LIBRARY_PATH or SHLIB_PATH. Other methods
of configuring the operating system loader, such as /etc/ld.so.conf, should not be used for
ENOVIA Live Collaboration.
Collecting Logs
and Core Files
If checking the configuration yields no errors, then all useful log files should be collected
for further investigation. This section lists a minimum set of logs that should be gathered.
Logs and Files to Collect
Stack traces
Cores
Application server logs
Any trace logs
Java stack trace logs (hs_err_pid*.log)
access.log (application server)
Rmireg.sh (Unix) or rmireg.bat (Windows) or the registry if rmid is
running as a service
mxtrace.log
Custom logs (redirected stdout and stderr)
Use the following table as a quick reference for stack trace commands. Sometimes it's
useful to generate a stack trace from a core and save it to a file.
Platform
Stack Trace Command
Solaris
pstack core > core.txt
AIX
use dbx
Refer to the Tech Tip, “About Core Dumps”, for using the pstack command; also see the
Tech Tip named “How To Analyze Core Dumps using GDB.” For more information about
the dbx command, contact ENOVIA Support.
The Live Collaboration server will log error messages to the mxtrace.log and other log
files, as described in Chapter 21, Server Diagnostics.
The ENOVIA Live Collaboration Server uses a set of log files to maintain state
information. These log files can be found by checking the rmireg.sh or rmireg.bat files,
and locating the rmid daemon load line with the -log option, as shown below:
$JAVA_PATH/rmid $JAVA_OPTIONS $JAVA_LIB -J$JAVA_SECURITY
-port 1099 -log /opt/eMatrixRMI9052/logs/RMI1099 &
Chapter 20: Troubleshooting ENOVIA Live Collaboration
475
These log files are not useful for diagnostic purposes, and you should delete all files from
this directory. If there are multiple rmid processes started from the startup script (i.e. the
RMI gateway is in use) then each set of logs should be deleted.
If a shutdown occurs, a file called the Java stack dump log is created. It is named
hs_err_pidxxxx.log, where xxxx is the process id number of the process that shut down.
These logs can be found in the same directory from which the ENOVIA Live
Collaboration kernel loads, usually the SERVER_INSTALL path under
intel_a\code\bin\.
These logs are critical for reporting a shutdown-related problem to ENOVIA Live
Collaboration, especially if no core is found. If the System has produced a core file for the
shutdown (Unix-only and the file is simply called core), this file will usually appear in the
directory from which the Live Collaboration kernel was loaded.
Missing Core Dumps
Shutdowns on Unix almost always cause the system to dump a core file, usually in the
directory from which the process initially loaded.
If no core dump file is generated, you might need to enable core files, as described below:
Enabling Core Files
Java Activation
Error on the
ENOVIA Live
Collaboration
Server
Solaris
in the /etc/system file, set sys:coredumpsize =
(maxsize of core dump file)
AIX
Use ulimit -c unlimited
and
chdev -l sys0 -a fullcore=true
When running on the ENOVIA Live Collaboration Server in non-RIP mode, an activation
exception may occur, which may look like the following:
java.rmi.activation.ActivateFailedException: failed to
activate object; nested exception is:
java.rmi.activation.ActivationException: unable to create
activation group; nested exception is:
java.io.IOException: The pipe is being closed"
The solution is to choose the proper configuration for your installation based on available
memory. Choose your Java heap settings as recommended in Calculating Maximum Heap
Size (-Xmx JVM option).
mx_err_pid.log for
Windows
476
When the Java Virtual Machine initializes itself, it installs a handler which gains control
when segmentation violations and other unexpected signals/events occur. From this
handler, the hs_err_pid.log file is generated. On Windows, an MX handler has been
chained to this process to catch these events, create a ENOVIA Live Collaboration specific
error log, and then pass control back to the JVM’s handler. Since tracing may not have
been enabled, this means that the events don’t need to be recreated to begin
troubleshooting.
ENOVIA Live Collaboration Installation Guide
When the MX handler is called on Windows, a file called mx_err_pidID#.log (where ID#
is the process number of the failing process) is created in the same directory as the JVM
creates the hs_err_pid123.log file (that is, the directory in which the server or MQL was
started, generally SERVER_INSTALL\intel_a\code\bin\). The mx_err_pid.log
file includes the same information as monitor server output as well as a hex dump at the
end of the file. Administrators can use this file for the monitor server output; the rest of the
file is meant for diagnosis by ENOVIA and should be included with details of the problem
to ENOVIA Customer Support.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
477
ENOVIA Studio Modeling Platform Stability
Troubleshooting
This section describes troubleshooting considerations for the ENOVIA Studio Modeling
Platform, including stack traces, Studio Customization Toolkit origin tracing, and memory
management.
Stack Traces
In the event of a core dump, it is advisable to generate stack traces from the core dump and
send the traces to ENOVIA support.
1. Generate stack traces from the core dump. This will provide information about where
all running threads were in the code at the time of the crash.
2. Be sure to examine the core file on the system that generated it.
•
On Solaris 8, you can run pstack.
3. Examine the stack trace. The first thread in the stack trace output will be the one that
caused the crash. Normally, there is an entry that reads "sighdlr" and the entry just
after it is the one that caused the "signal" (usually SIGSEGV) and the crash.
4. Send the stack trace to ENOVIA support.
Studio
Customization
Toolkit Origin
Tracing
Studio Customization Toolkit Origin Tracing supplements verbose tracing by adding an
origin stack trace for each Studio Customization Toolkit call made, thus enabling an
engineer to determine the exact line in the JSP, applet, bean, or application code where a
problematic call was made.
You enable Studio Customization Toolkit Origin Tracing on the server. Refer to Studio
Customization Toolkit Origin Trace Facility in Chapter 21.
Memory Pools
To troubleshoot memory bottlenecks it is important to understand ENOVIA Live
Collaboration architecture and the various memory pools in use. ENOVIA Live
Collaboration Server can be configured in two different ways:
•
•
478
Two-tier (ENOVIA Live Collaboration Server): The ENOVIA Live Collaboration
kernel lives in its own process as an ENOVIA Live Collaboration Server and has its
own memory space. In this case three memory pools are relevant:
•
The C++ memory of the ENOVIA Live Collaboration Server, which is used to
cache data and evaluate server operations.
•
The Java heap in the ENOVIA Live Collaboration Server used to temporarily
store data for requests, until the request is completed.
•
The Java heap in the application server, used to store all Java objects of the
application, like sessions, beans, properties and temporary objects.
Single tier (RIP). The ENOVIA Live Collaboration kernel is part of the application
server and shares the same address space. The memory pools in C++ memory and the
Java heap in the ENOVIA Live Collaboration Server (listed above) are relevant in this
configuration.
ENOVIA Live Collaboration Installation Guide
Memory
Management
In contrast to typical memory managers, the ENOVIA Live Collaboration’s memory
manager is suited for long running server processes. The system allocates memory in
multiples of 16 bytes. Instead of freeing memory blocks under 512 bytes, the system
maintains its own free list. This free list is subdivided into buckets, for holding blocks of
the same size. The maximum amount of memory held by this list is controlled by the
parameter MX_MEMORY_KEEP_LIMIT, which has a default value of 256m. This
algorithm ensures fast allocation and prevents memory fragmentation. Furthermore,
ENOVIA Live Collaboration’s memory manager contains the following trace parameters,
which can be used to resolve memory related problems.
MX_MEMORY_TRACE
MX_VERBOSE_MEMORY_TRACE
For more information on the above parameters, see Configuring Memory Manager in
Chapter 21.
Memory
Troubleshooting
Procedures
Tool Selection
Depending on where the memory problem is, different tools are needed to diagnose it. An
ENOVIA Live Collaboration Server configuration and a growth of the ENOVIA Live
Collaboration Server process suggest a problem in the C++ core. Growth of the
application server process or Java OutOfMemoryExceptions indicate a problem with the
Java heap. There may be no clear initial indication of a memory problem in a RIP
environment. In this case, run the application server JVM with -verbose:gc and graph the
heap over time. If this indicates a Java side leak, use a profiler or similar tool to find the
problem. See Java Memory Problem below for details
Java Memory Problem
The first step is to run the application server JVM with the option "-verbose:gc" and
capture the output in a file. This will print verbose garbage collection records, which look
similar to the following:
[GC
[GC
[GC
[GC
137851K->122823K(260160K),
139015K->123987K(260160K),
140179K->125151K(260160K),
141343K->126313K(260160K),
0.0128460
0.0126110
0.0128070
0.0131270
secs]
secs]
secs]
secs]
Then use a tool like gcviewer from www.tagtraum.com or GC Portal from SUN
Microsystems to visualize the output. In the following example a JSP was supposed to
print a record of the last ten requests, but instead of saving data for the ten most recent
requests, it saved all requests. The code looks like the following:
<%! static Vector vClients=new Vector(100);
class clsRow {
Date _dTime=null;
String _sSession=null;
String _sHost=null;
public clsRow(String sSession, String sHost) {
_dTime=new Date();
_sSession=sSession;
_sHost=sHost;
}
Chapter 20: Troubleshooting ENOVIA Live Collaboration
479
public String toString() {
StringBuffer sb=new StringBuffer("<tr>");
sb.append("<td>");
sb.append(_dTime.toString());
sb.append("</td><td>");
sb.append(_sSession);
sb.append("</td><td>");
sb.append(_sHost);
sb.append("</td>");
sb.append("</tr>\n");
return( sb.toString() );
}
};
%>
<%
vClients.add(0,
new clsRow(session.getId(), request.getRemoteHost())
);
%>
The JSP ran in a Tomcat 4 application server and was requested by five jmeter threads
about 150000 times. The verbose garbage collection log was visualized with gcviewer.
Note the blue line, which shows the total heap used, the amount of memory recovered with
each garbage collection and a clear upslope. The upslope indicates a Java memory leak.
Finding the leak is the much more difficult part. One method is to run the JVM with the
built-in profiler, which is available in the JVM from SUN Microsystems. For the example
above, the application server JVM was run with the option
"-Xrunhprof:heap=sites,depth=10,thread=y". This will not currently work with a
WebLogic server because it monitors heap usage itself and interferes with this setting;
only Tomcat has been successfully used with -Xrunhprof. Use of the option generates a
480
ENOVIA Live Collaboration Installation Guide
very large file java.hprof.txt and also has a significant performance impact. The generated
file could be reviewed manually or with a tool like Hpjmeter from www.hp.com.
It is preferable to perform such an investigation in a controlled environment. A repetitive
test should be used and executed by a load-generating tool, like LoadRunner, grinder, or
jmeter. Also after the test has completed, the test instance should be left idle until all active
sessions have timed out.
For our example we used Hpjmeter and displayed the Metric "Residual Objects (Count)",
which produced the list below.
There are obviously many system objects, making it difficult to identify the culprit.
However, upon closer inspection, tst_jsp$clsRow stands out. It is a class from the
example, of which about 51000 instances exist, but only 10 should exist.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
481
Implementation Troubleshooting
The design of the ENOVIA Live Collaboration allows customers to build their own
applications to interface with it. When building applications, users may unknowingly
employ coding practices that are detrimental to system stability. This section summarizes
implementation best practices and provides references to other ENOVIA Live
Collaboration documentation that explains these practices more fully.
Queries
A major cause of performance problems are poorly structured queries. Query performance
problems can be broken down into two categories: memory issues and time taken to
complete the query. With memory issues, the result of the query is so large that the
computer system cannot handle the result. In the time issue, the processing time of the
query is much longer than needed. ENOVIA has identified some strategies to prevent
query problems, which are described in detail in the “Working with Workspace Objects”
chapter in the MQL Guide.
Tcl Statements
Additionally, users may write MQL programs that contain Tcl statements. Some of the
more common problems with Tcl statements are related to Tcl syntax. The Tcl executable
has strict rules regarding syntax. For a description of common Tcl syntax errors, see “Tcl
Syntax Troubleshooting” in the MQL Language chapter in the MQL Guide.
JSP Development
User-created JSP pages may access variables in a non-thread-safe way. A solution to this
problem is discussed in the “Using the Context Object” topic in the Creating a Login Page
chapter of the Programming Guide. Other common problems that occur when developing
JSPs are discussed in the “Programming Notes” topic in the Programming Guide.
482
ENOVIA Live Collaboration Installation Guide
Web Navigator Troubleshooting
This section contains information to help users address problems that they may encounter
with the Web Navigator. To have a successful install, you must completely remove all
references to the old version. Refer to Removing Web Navigator in Chapter 12 for details.
Set Context
Problems
The table below shows possible causes and solutions to typical errors starting up a Web
client.
Symptom
Possible Causes
Solution
Server throws a General
Protection Fault (GPF)
or “Dr. Watson” error
when setting context
No connection file was found.
Confirm that the connection file(MATRIX-R file) is
located in MATRIXHOME, as defined in the enovia.ini
file, and that a defined Oracle database alias matches the
connect string entry in the connection file.
Installation on
UNIX
Database alias not defined.
Connect string in connection file
doesn’t match database alias.
Problem
After installing an ENOVIA Live Collaboration client (either the Studio Modeling
Platform or the Live Collaboration Server), when you attempt to connect to an Oracle
database you receive the following error:
ORA-07268: szguns: getpwuid error
Solution
Open the passwd file from the /etc directory and append a plus sign followed by a colon
(+:). This allows both NIS and local users.
Look and Feel
Problem
Web Navigator appears with the metal look and feel instead of the Windows or motif look
and feel.
Solution
If the Web client has installed applications that include a JDK, the PATH and
CLASSPATH variables may be set for use with the other application. Check your PATH
and CLASSPATH to ensure that they do NOT refer to other JDKs like Symantic Visual
Cafe 3.0. If they do, you can either remove these entries from the PATH and CLASSPATH
values on the client, OR you can add the following parameter to the HTML page on the
server that contains Web Navigator:
<param name="LAF" value="windows">
Chapter 20: Troubleshooting ENOVIA Live Collaboration
483
The value may also be “motif”. Refer to Configuring Web Navigator in Chapter 12 for
more information on this and other parameters.
484
ENOVIA Live Collaboration Installation Guide
ENOVIA Studio Modeling Platform
Troubleshooting
This section discusses issues users must be aware of when using the Studio Modeling
Platform. Some of these are platform-specific and others apply to all installations.
Accessing Remote
File Systems
Problem
When accessing or storing files on a remote host machine, you receive the following
message:
Storage Manager: Cannot create or open file
hostname: /path/filename(Permission denied) (100101)
This occurs if you are attempting to access a remote captured store and the host machine is
not currently allowing you access.
Solution 1
ENOVIA Live Collaboration uses NFS or FTP to access remote captured stores. In order
for FTP to work appropriately, the remote system must be set up as an FTP server. If NFS
is in use, check that the remote machine’s file system is exported to the NFS clients. Ask
your System Administrator to export the necessary file systems. This is controlled by
appropriate entries in the remote system’s /export file.
All machines that contain ENOVIA Live Collaboration captured stores that will be
accessed via NFS must be running:
•
the RPC portmapper daemon
•
NFS
•
mountd daemons
The mounted daemons must be started with the appropriate options so unreserved ports
may be used for NFS mounts. Failure to do this will result in access only being allowed
when users are logged in as root. The options for various platforms are described below.
Sun Solaris platforms default to the “-n” option on startup of the rpc.mountd daemon.
However, on IBM RS6000 the rpc.mountd daemon must be manually started with the
“-n” option. On IBM RS6000 this is typically done by running the following command at
the root:
chssys -s rpc.mountd -a -n
Crash on Checkin
Problem
ENOVIA Live Collaboration crashes when the network connection goes down while
checking in a file.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
485
Reason
If ENOVIA Live Collaboration cannot commit or abort a transaction, an error dialog
explains that a non-recoverable error has occurred. When the dialog is dismissed,
ENOVIA Live Collaboration gracefully exits. The application is not crashing.
Errors during
Administration
Problem
Attempts to add a new type or perform other administrative functions fail with errors
similar to:
Error #1200060 Can't create new derived from for the type
ORA-12154: TNS:could not resolve service name
Solution
For administrative work done in the Business, System, or MQL applications, all server
objects are accessed. For this reason, machines used for these functions must have an
Oracle database alias configured for each server object. For example, for a system with
two servers with connectstring values of “SanDiego” and “SanJose”, administrator's
machines must have two Oracle database aliases configured named “SanDiego” and
“SanJose”.
Installation on
UNIX
Problem
After installing an ENOVIA Live Collaboration client (either Studio Modeling Platform or
the Live Collaboration server), when you attempt to connect to the database you receive
the following error:
ORA-07268: szguns: getpwuid error
Solution
Open the passwd file from the /etc directory and append a plus sign followed by a colon
(+:). This allows both NIS and local users.
Localized
Character display
Problem
German umlauts or other European characters are not displayed correctly on Windows.
Solution
In some cases, Oracle Instant Client may not find the proper NLS registry settings. To
override the registry settings, set NLS_LANG as an environment variable. For example:
NLS_LANG=GERMAN_GERMANY.WE8ISO8859P15
486
ENOVIA Live Collaboration Installation Guide
Localized Decimal
Character Settings
Problem
When the database and localization files are setup to use European character sets with a
comma as the decimal character, the following Oracle error message may be generated:
ORA-01722 invalid number ...
Solution
The system decimal symbol must be synchronized with the character implied by the
Oracle database setting for NLS_LANG. The System Administrator can use the following
MQL command to set the system decimal symbol:
<mql> set system decimal .;
Refer to the MQL Guide for more information about the “set system decimal” command.
Overriding defaults in NLS_LANG
NLS_NUMERIC_CHARACTERS specifies the decimal character (the character that
separates the integer and decimal parts of a number) as well as the group separator (the
character that separates integer groups, i.e. thousands, millions, etc.), overriding the
defaults established by the territory defined in either NLS_LANG or NLS_TERRITORY,
whichever is in use. The characters are specified in the following format:
NLS_NUMERIC_CHARACTERS = “[DEC_CHAR][GROUP_SEP]”
The two characters specified must be single-byte, and different from each other. The
characters CANNOT be any numeric character, plus (+), hyphen (-), less than sign (<), or
greater than sign (>), but either MAY BE a space. For example, to set the decimal
character to a comma and the group separator to a period, the parameter should be set in
the Oracle initialization file (init<SID>.ora) as follows:
NLS_NUMERIC_CHARACTERS = “,.”
Using alternate decimal characters with SQL
When the decimal character is not a period (.) or when a group separator is specified,
numbers appearing in SQL statements must be enclosed in quotes. For example, with the
value of NLS_NUMERIC_CHARACTERS as set above, the following SQL statement
requires quotation marks around the numeric literals:
INSERT INTO SIZES (ITEMID, WIDTH, QUANTITY) VALUES (618, '45,5',
TO_NUMBER('1.234','9G999'));
Using alternate decimal characters with Tcl
Tcl 8.0 does not tolerate anything but a period as a decimal separator. The problem
exhibits itself if you try to use the tcl 'expr' command as follows:
set retVal [expr 8,5 + 4,2]
If MX_DECIMAL_SYMBOL is set to comma(,) (Oracle only) all real numbers from the
ENOVIA Live Collaboration database will be converted to have comma as a decimal
separator before being output. If you must perform Tcl arithmetic, and you have any users
that have MX_DECIMAL_SYMBOL set to comma(,), you should incorporate the
following program into the users’ Tcl library, and call it in place of the Tcl “expr”
procedure to evaluate decimal numbers.
#############################################################
# File Name: mxExpr.tcl
# Description: Workaround for tcl-proc \"expr\" working with
\",\"
Chapter 20: Troubleshooting ENOVIA Live Collaboration
487
#############################################################
proc Expr { args } {
if { [ regsub -all \",\" $args \".\" args ] } {
set sRet [ expr $args ]
regsub \\\\\\. $sRet \",\" sRet
} else {
set sRet [ expr $args ]
}
return $sRet
}
#############################################################
If you must perform O/S arithmetic with Tcl, such as working with file sizes or other real
numbers from the O/S, and LANG is set to define comma as decimal separators, you may
need to use the Expr function defined above to handle those calculations.
ENOVIA Live Collaboration supports a deprecated environment setting
(MX_TCL_ANSI_NUMERIC) to force the decimal separator to be period(.) when tcl
programs run, but this is only suitable for use in single-threaded (Studio Modeling
Platform) environments, since it modifies the system LOCALE setting which affects all
other threads in the process.
The behavior of a multi-threaded server running with this setting is unpredictable, and is
not supported.
When used in a desktop environment, the behavior is as follows:
.Rollback Segment
Error
•
if MX_TCL_ANSI_NUMERIC=true, ENOVIA Live Collaboration overrides the
LC_NUMERIC setting during execution of Tcl programs to establish a period (.) as
the decimal setting. This causes operating system utilities to return floating point
values in a form that is suitable for performing arithmetic using the Tcl "expr"
procedure. Values obtained from MQL commands will continue to be returned using
the character set as MX_DECIMAL_SYMBOL.
•
if MX_TCL_ANSI_NUMERIC=false, (the default) the setting for LC_NUMERIC is
used and Tcl calls to the operating system will return floating point values according
to the LOCALE settings in the OS.
An error similar to the following may occur if Oracle rollback segments are not large
enough:
System Error: #1: ORA-01562: failed to extend rollback segment
number 2 ORA-01650: unable to extend rollback segment R01 by 64
in tablespace RBS
This means that the rollback segment being used needs to be enlarged. Generally this
occurs in the following circumstances:
•
Deleting lots of IconMail;
•
Data loading using explicit transaction boundaries;
•
Upgrading the database
•
Clearing vaults or the entire database (clear all;)
•
Any customization that uses large transaction boundaries;
The storage manager or sqlplus may be used to increase the size of the “next extent” for
the rollback segment to accommodate the size of the transaction. Typically, there is a
488
ENOVIA Live Collaboration Installation Guide
maximum of 121 rollback segments, so the product of the next extent and 120 must exceed
the total size of all files being accessed within this one transaction. Refer to Oracle
documentation on Storage Manager for information on performing this task.
Color Mapping
Problem
•
When entering the Studio Modeling Platform, the colors are incorrect or unavailable
after other external applications have exhausted the color resources. The Studio
Modeling Platform colors display incorrectly or you receive the error message “xalloc
color cells.”
•
After exiting the desktop, colors for the desktop are incorrect.
Reason
The problem occurs because the desktop works best when sharing the default colormap as
originally defined by MIT’s X11 standard. However, ENOVIA Live Collaboration,
requires large amounts of color.
Solution 1 (UNIX)
Run the X standard colormap utility to define the standard colormap properties. This
utility, xstdcmap, is provided in the <INSTALL_PATH>/etc/<PLATFORM>/ directory.
Executing the following will correct the color mapping problem by automatically loading
the default color mapping:
<INSTALL_PATH>/ etc/<PLATFORM>/ xstdcmap -delete default
<INSTALL_PATH>/ etc/<PLATFORM>/ xstdcmap -default
The default colormap should generally be loaded after the X server is started and before
the desktop (and the Window Manager), can allocate color cells. This can be accomplished
through methods that vary with each platform, and are described as follows:
SPARCstations (Solaris)
Edit the .xinitrc file in the user’s home directory and put the xstdcmap commands at the
beginning of the file. If there is no .xinitrc file in the user's home directory, copy the
default file from the /usr/openwin/lib/Xinitrc.
IBM RS6000 (AIX)
Edit the .xinitrc file in the user’s home directory and put the xstdcmap commands at the
beginning of the file. If there is no .xinitrc file in the user's home directory, copy the
default file from /usr/lpp/X11/defaults/xinitrc.
Solution 2 (UNIX and WINDOWS)
There are two flags available that can be passed to the desktop that will regulate colormap
usage. The flags may be added to the command line or setup scripts as follows:
-standardcolormax <DECIMAL>
-sharedcolormax <DECIMAL>
Where <DECIMAL> represents a real number between 0 and 1.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
489
The standard flag represents the fraction of the standard colormap that ENOVIA Live
Collaboration will control. The default is .75, which should be adjusted to ensure that
appropriate colors are available to other desktops. Setting this flag to zero will cause no
standard colors to be allocated.
The shared flag represents the fraction of the shared colormap (that is, the Windows or X
default colormap) that is allocated for ENOVIA Live Collaboration. This defaults to 1,
which means that ENOVIA Live Collaboration has access to the entire colormap for
custom colors. Setting this value to zero means that ENOVIA Live Collaboration will use
a private colormap. When the private color map is used, the active desktop window will
look fine, but the inactive windows may give up their colors until they become active. This
may appear as “flashes” when switching between desktop applications.
If both of the above solutions are used in unison and the problem still occurs, the
colormapping of the other applications should be examined.
Launching
Applications in
Windows
Problem
On all Windows platforms, Studio Modeling Platform windows are not repainted while
the launched desktop is executing. This causes no harm, but can be visually unappealing.
Solution
By setting a preference called MX_WIN_MIN_ON_LAUNCH, a user can cause all
Studio Modeling Platform windows to be minimized during the execution of the launched
desktop. When the launched desktop terminates, the Studio Modeling Platform windows
are restored. The value assigned to this preference is True or False. When set to True, the
Studio Modeling Platform windows are minimized. The default is False. This preference
is read from the enovia.ini file prior to each launching.
490
ENOVIA Live Collaboration Installation Guide
Miscellaneous Troubleshooting
This section contains troubleshooting issues that are either common to several areas or
belong to an area separate from server configuration, Web Navigator, or Studio Modeling
Platform.
FTP Connection
Timeouts
All supported operating systems provide a TCP KeepAlive socket feature which ENOVIA
Live Collaboration uses for all FTP connections. When ENOVIA Live Collaboration
creates a socket for use in a FTP transfer (that is, for checkin/checkout operations with
FTP stores or with FCS), the socket utilizes the TCP SO_KEEPALIVE option. If
ENOVIA Live Collaboration is unable to set the SO_KEEPALIVE option on the
socket(s), it will print a warning.
With the proper OS TCP stack configuration, large file transfer attempts through firewalls
and other intermediary network devices, including proxies, no longer fail due to the FTP
control connection time outs and termination.
Below are guidelines for enabling and configuring TCP KeepAlives on the various
platforms.
Platform
Relevant parameters
Command to check
Command to change
AIX
tcp_keepidle
tcp_keepintvl
no –o tcp_keepidle
no –o tcp_keepintvl
no –po tcp_keepidle=14400
no –po tcp_keepintvl=240
LINUX
tcp_keepalive_time
tcp_keepalive_intvl
tcp_keepalive_probes
cat /proc/sys/net/ipv4/
tcp_keepalive_time
cat /proc/sys/net/ipv4/
tcp_keepalive_intvl
cat /proc/sys/net/ipv4/
tcp_keepalive_probes
In /etc/sysctl.conf
net.ipv4.tcp_keepalive_time = 7200
net.ipv4.tcp_keepalive_intvl = 75
net.ipv4.tcp_keepalive_probes = 9
#sysctl -p
Solaris
tcp_keepalive_interval
ndd /dev/tcp
tcp_keepalive_interval
ndd -set /dev/tcp
tcp_keepalive_interval 290000
Windows
HKLM\SYSTEM\CurrentControlSe
t\Services\Tcpip\Parameters
KeepAliveInterval
KeepAliveTime
regedit
Regedit or .reg file
Changing the keepalive interval is a server wide and not per connection / process setting.
Before making changes to the TCP stack in a production system these changes must be
qualified in a comparable test environment.
If you find you have long data transfers (replication) between stores on separate sides of a
firewall that is configured to time out TCP connections that remain idle for a given
interval, then you will want to configure your operating system’s TCP stack to send
KeepAlives at an interval smaller than the interval at which the firewall times out idle TCP
connections. You should contact your IT infrastructure staff to determine what is the
maximum time the infrastructure hardware will allow a connection to remain active. An
industry standard is 300 seconds (5 minutes). You would be safe to set the keepalive
interval to 290 seconds. If the hardware is not dedicated to ENOVIA Live Collaboration,
then you must determine the impact of lowering the keepalive interval for any other
application on the server.
Chapter 20: Troubleshooting ENOVIA Live Collaboration
491
Laptop
Performance
Problem
From a laptop computer, opening ENOVIA Web pages, setting context and performing
finds seem to take longer than should be necessary.
Solution
Check the following:
1. Set your browser default page to a local file instead of the browser’s default
homepage of www.microsoft.com or www.mozilla.org. Browser initialization and
host name resolution as well as anything using TCP/IP will all perform faster.
2. Check that the hostname for the DNS settings is set to the machine’s network name.
Open the Network option from the Control Panel. Click the Protocols tab and choose
TCP/IP protocol properties. Click the DNS tab and make sure the host field specifies
the correct machine network name.
3. Open the \winnt\system32\drivers\etc\hosts file. Make sure your
machine IP and name are listed. This helps resolve the host name more quickly.
Session Timed Out
Error
Problem
The following error is received when performing any operation:
java.lang.Exception: Session timed out
Solution
Timeout limits are set and enforced in the Web or application server. If a period of
inactivity occurs that is greater than the limit set, for security reasons, users are forced to
login again. Consult your Web server's documentation for information on setting this limit.
Tar Error When
Unpacking
Distributions
If you receive LongLink error(s) when attempting to untar an ENOVIA distribution file
such as ENOVIALiveCollaborationServer-VERSION.tar, install GNU tar 1.14 or higher
and unpack with “gtar”. The original POSIX format can only handle 100 characters for
link names.
Problems with JSP
Path for ENOVIA
products
If you have problems with the path for the JSPs when using an ENOVIA product, make
sure the following settings are defined as follows in the web.xml file.
492
ematrix.login.page=/ematrix/emxLogin.jsp
ematrix.home.page=/ematrix/emxHome.jsp
ENOVIA Live Collaboration Installation Guide
21
Server Diagnostics
Overview
You can use the following server diagnostic tools for the Live Collaboration Server:
•
The Monitoring Agent tool which periodically gathers information on a Live
Collaboration Server instance and maps it to standard IBM CBE (Common Base
Event) monitoring log format. For details, see Monitoring the Live Collaboration
Server using the Monitoring Agent.
•
Tracing tools which send trace information to either a file or a standard output. For
details, see Tracing Types.
493
Monitoring the Live Collaboration Server using
the Monitoring Agent
The ENOVIA Live Collaboration Server can be monitored using a tool called the
Monitoring Agent. The monitoring agent is delivered with the Live Collaboration Server
and can be used to monitor availability, performance, security, and usage throughout the
different layers of ENOVIA Live Collaboration and other ENOVIA components like the
DS License Server. These layers include the kernel, VPM and ENOVIA applications.
The monitoring agent is a standalone process launched from a command-line. After the
agent is configured to monitor a Live Collaboration Server instance (the agent can only
monitor one server instance at a time) it will periodically gather monitoring information
on the server, map it to standard IBM CBE (Common Base Event) monitoring log format,
and save it to the local machine where it runs.
The monitoring agent can either run on the same machine as the Live Collaboration Server
or on different machine to reduce its impact on Live Collaboration Server performance.
Setting up the
Monitoring Agent
Setting up the monitoring agent involves creating a keystore file and initially starting the
agent with your configuration options. A keystore file only needs to be created if the agent
is monitoring a component that requires authentication. For example, the Live
Collaboration Server requires authentication but the DS License Server does not. This
means if the agent will only be monitoring a DS License Server, a keystore file is not
needed.
Creating a
keystore File
For security reasons, you cannot start the monitoring agent by entering a username and
password directly in the command-line. Instead, the agent must be started using a keystore
file that conceals the username and password.
The username and password used to create the keystore file must be licensed to use the
Live Collaboration Server. No specific roles or access are required for this username and
password. A