SmartPlant Materials Open Ident Interface (OII)

SmartPlant Materials Open Ident Interface (OII)

Version 2011 SP5 (7.0.5)

December 2011

DMAR1-PE-200007H

Copyright Copyright © 2002-2011 Intergraph® Corporation. All Rights Reserved. Intergraph is part of Hexagon.

Including software, file formats, and audiovisual displays; may be used pursuant to applicable software license agreement; contains confidential and proprietary information of Intergraph and/or third parties which is protected by copyright law, trade secret law, and international treaty, and may not be provided or otherwise made available without proper authorization from Intergraph Corporation.

U.S. Government Restricted Rights Legend Use, duplication, or disclosure by the government is subject to restrictions as set forth below. For civilian agencies: This was developed at private expense and is "restricted computer software" submitted with restricted rights in accordance with subparagraphs (a) through (d) of the Commercial Computer Software - Restricted Rights clause at 52.227-19 of the Federal Acquisition Regulations ("FAR") and its successors, and is unpublished and all rights are reserved under the copyright laws of the United States. For units of the Department of Defense ("DoD"): This is "commercial computer software" as defined at DFARS 252.227-7014 and the rights of the Government are as specified at DFARS 227.7202-3.

Unpublished - rights reserved under the copyright laws of the United States.

Intergraph Corporation 300 Intergraph Way Huntsville, AL 35813

Documentation Documentation shall mean, whether in electronic or printed form, User's Guides, Installation Guides, Reference Guides, Administrator's Guides, Customization Guides, Programmer's Guides, Configuration Guides and Help Guides delivered with a particular software product.

Other Documentation Other Documentation shall mean, whether in electronic or printed form and delivered with software or on Intergraph Smart Support, SharePoint, or box.net, any documentation related to work processes, workflows, and best practices that is provided by Intergraph as guidance for using a software product.

Terms of Use a. Use of a software product and Documentation is subject to the End User License Agreement ("EULA") delivered with the

software product unless the Licensee has a valid signed license for this software product with Intergraph Corporation. If the Licensee has a valid signed license for this software product with Intergraph Corporation, the valid signed license shall take precedence and govern the use of this software product and Documentation. Subject to the terms contained within the applicable license agreement, Intergraph Corporation gives Licensee permission to print a reasonable number of copies of the Documentation as defined in the applicable license agreement and delivered with the software product for Licensee's internal, non-commercial use. The Documentation may not be printed for resale or redistribution.

b. For use of Documentation or Other Documentation where end user does not receive a EULA or does not have a valid licenseagreement with Intergraph, Intergraph grants the Licensee a non-exclusive license to use the Documentation or Other Documentation for Licensee’s internal non-commercial use. Intergraph Corporation gives Licensee permission to print a reasonable number of copies of Other Documentation for Licensee’s internal, non-commercial. The Other Documentation may not be printed for resale or redistribution. This license contained in this subsection b) may be terminated at any time and for any reason by Intergraph Corporation by giving written notice to Licensee.

Disclaimer of Warranties Except for any express warranties as may be stated in the EULA or separate license or separate terms and conditions, Intergraph Corporation disclaims any and all express or implied warranties including, but not limited to the implied warranties of merchantability and fitness for a particular purpose and nothing stated in, or implied by, this document or its contents shall be considered or deemed a modification or amendment of such disclaimer. Intergraph believes the information in this publication is accurate as of its publication date.

The information and the software discussed in this document are subject to change without notice and are subject to applicable technical product descriptions. Intergraph Corporation is not responsible for any error that may appear in this document.

The software, Documentation and Other Documentation discussed in this document are furnished under a license and may be used or copied only in accordance with the terms of this license. THE USER OF THE SOFTWARE IS EXPECTED TO MAKE THE FINAL EVALUATION AS TO THE USEFULNESS OF THE SOFTWARE IN HIS OWN ENVIRONMENT.

Intergraph is not responsible for the accuracy of delivered data including, but not limited to, catalog, reference and symbol data. Users should verify for themselves that the data is accurate and suitable for their project work.

2 SmartPlant Materials Open Ident Interface (OII)

Limitation of Damages IN NO EVENT WILL INTERGRAPH CORPORATION BE LIABLE FOR ANY DIRECT, INDIRECT, CONSEQUENTIAL INCIDENTAL, SPECIAL, OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO, LOSS OF USE OR PRODUCTION, LOSS OF REVENUE OR PROFIT, LOSS OF DATA, OR CLAIMS OF THIRD PARTIES, EVEN IF INTERGRAPH CORPORATION HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

UNDER NO CIRCUMSTANCES SHALL INTERGRAPH CORPORATION’S LIABILITY EXCEED THE AMOUNT THAT INTERGRAPH CORPORATION HAS BEEN PAID BY LICENSEE UNDER THIS AGREEMENT AT THE TIME THE CLAIM IS MADE. EXCEPT WHERE PROHIBITED BY APPLICABLE LAW, NO CLAIM, REGARDLESS OF FORM, ARISING OUT OF OR IN CONNECTION WITH THE SUBJECT MATTER OF THIS DOCUMENT MAY BE BROUGHT BY LICENSEE MORE THAN TWO (2) YEARS AFTER THE EVENT GIVING RISE TO THE CAUSE OF ACTION HAS OCCURRED.

IF UNDER THE LAW RULED APPLICABLE ANY PART OF THIS SECTION IS INVALID, THEN INTERGRAPH LIMITS ITS LIABILITY TO THE MAXIMUM EXTENT ALLOWED BY SAID LAW.

Export Controls Intergraph Corporation’s software products and any third-party Software Products obtained from Intergraph Corporation, its subsidiaries, or distributors (including any Documentation, Other Documentation or technical data related to these products) are subject to the export control laws and regulations of the United States. Diversion contrary to U.S. law is prohibited. These Software Products, and the direct product thereof, must not be exported or re-exported, directly or indirectly (including via remote access) under the following circumstances:

a. To Cuba, Iran, North Korea, Sudan, or Syria, or any national of these countries. b. To any person or entity listed on any U.S. government denial list, including but not limited to, the U.S. Department of Commerce

Denied Persons, Entities, and Unverified Lists, http://www.bis.doc.gov/complianceandenforcement/liststocheck.htm, the U.S. Department of Treasury Specially Designated Nationals List, http://www.treas.gov/offices/enforcement/ofac/, and the U.S. Department of State Debarred List, http://www.pmddtc.state.gov/compliance/debar.html.

c. To any entity when Licensee knows, or has reason to know, the end use of the Software Product is related to the design, development, production, or use of missiles, chemical, biological, or nuclear weapons, or other un-safeguarded or sensitive nuclear uses.

d. To any entity when Licensee knows, or has reason to know, that an illegal reshipment will take place. e. Any questions regarding export or re-export of these Software Products should be addressed to Intergraph Corporation’s Export

Compliance Department, Huntsville, Alabama 35894, USA.

Trademarks Intergraph, the Intergraph logo, Intergraph Smart, PDS, SmartPlant, SmartMarine, FrameWorks, I-Sketch, IntelliShip, ISOGEN, SmartSketch, SPOOLGEN, SupportManager, SupportModeler, Sapphire, and FreeView are trademarks or registered trademarks of Intergraph Corporation or its subsidiaries in the United States and other countries. Microsoft and Windows are registered trademarks of Microsoft Corporation. MicroStation is a registered trademark of Bentley Systems, Inc. Other brands and product names are trademarks of their respective owners.

SmartPlant Materials Open Ident Interface (OII) 3

Contents Preface .......................................................................................................................................................... 7

Documentation Comments ..................................................................................................................... 7

Introduction .................................................................................................................................................. 9

Features and Functionality ....................................................................................................................... 11

Imported Data ....................................................................................................................................... 11 Reference Data .............................................................................................................................. 11 Context of Import Execution ........................................................................................................... 11 Idents .............................................................................................................................................. 11 Ident Descriptions ........................................................................................................................... 12 Ident Attributes ............................................................................................................................... 12 Ident Structures .............................................................................................................................. 12

Job Execution........................................................................................................................................ 12 Error Handling ....................................................................................................................................... 13 Import Protocol ...................................................................................................................................... 13

Prerequisites .............................................................................................................................................. 15

Required Data in the SmartPlant Materials Database .......................................................................... 15 NLS ................................................................................................................................................. 15 Commodity Codes .......................................................................................................................... 15 Geometrics ..................................................................................................................................... 15 Attributes ........................................................................................................................................ 15 Units................................................................................................................................................ 16 Unit Conversion Rules .................................................................................................................... 16 DBA Settings .................................................................................................................................. 16

File Format ............................................................................................................................................ 16 Supported Record Types and Their Processing Rules .................................................................. 17 Record Structure ............................................................................................................................ 19 File Format Example ...................................................................................................................... 20

Data Import ................................................................................................................................................. 23

Extracting the Data from the 3rd Party or Legacy System ................................................................... 23 File Placement ...................................................................................................................................... 23 Defining an Import Job .......................................................................................................................... 24 Starting Job Execution .......................................................................................................................... 25

File Transfer into the Interface Table ............................................................................................. 25 Import Main Program ...................................................................................................................... 25 Log File Creation ............................................................................................................................ 25

Reviewing the Logfile ............................................................................................................................ 26 Erroneous Import Data ................................................................................................................... 27 Correcting Import Data and Starting Over ...................................................................................... 27

Viewing and Modifying Imported Data .................................................................................................. 27 Idents and Ident Values .................................................................................................................. 27 Assembly Data ............................................................................................................................... 28


Contents Data Export ................................................................................................................................................ 31

Setting Up Where Conditions ................................................................................................................ 31 Starting Job Execution .......................................................................................................................... 32 Reviewing the Export File ..................................................................................................................... 32

Implementation .......................................................................................................................................... 33

SmartPlant Materials Tables ................................................................................................................. 33 Stored PL/SQL Program Units .............................................................................................................. 33 Transaction Control ............................................................................................................................... 33 Exclusive Object Locks ......................................................................................................................... 34 Dependencies on Other SmartPlant Materials Modules ....................................................................... 34

Appendix: Setup and Configuration ........................................................................................................ 35

Directories and Files ............................................................................................................................. 35 Instance Configuration Tasks ............................................................................................................... 35 File Placement ...................................................................................................................................... 36 Adjusting the SQL*Loader Parameter File ............................................................................................ 36 Configuring SmartPlant Materials Settings ........................................................................................... 36

OII Export ....................................................................................................................................... 36 OII Import ........................................................................................................................................ 37

Appendix: Error Messages ....................................................................................................................... 39

Error Messages on S.80.11 .................................................................................................................. 39 Error Messages on S.80.14 .................................................................................................................. 41 Error Messages in the Import Protocol ................................................................................................. 43

General Messages ......................................................................................................................... 43 Messages Related to Missing or Invalid Data ................................................................................ 44 Messages Related to IDENT Records ........................................................................................... 44 Messages Related to IDENT_NLS records .................................................................................... 45 Messages Related to IDENT_ATTR Records ................................................................................ 45 Messages Related to IDENT_STRUC Records ............................................................................. 45 Messages Related to SQL*Loader Import...................................................................................... 46

Appendix: SQL*Loader Control/Parameter File ..................................................................................... 47

Control File oii500.ctl ............................................................................................................................ 47 SQL*Loader Parameter File oii500.par ................................................................................................. 48

Appendix: Import Protocol Script ............................................................................................................ 49

Appendix: Export Script ........................................................................................................................... 51

Index ........................................................................................................................................................... 55


This document describes the Open Ident Interface (OII).

Documentation Comments Send documentation comments or suggestions to [email protected] (mailto:[email protected]?subject=documentation comments).

Preface


mailto:[email protected]?subject=documentation%20comments

Preface


S E C T I O N 1

SmartPlant Materials, being a flexible and open materials management system, incorporates open interfaces to those engineering systems and CAD systems with the highest market significance and thus allows several convenient ways to exchange data with these systems.

With the Open Ident Interface, new import functionality that addresses an important area of data take-on has been added. The OII interface allows the import of unstructured ident data into the standardization module of a SmartPlant Materials database. The most valuable application of this interface is the import from 3rd party systems or legacy systems where the old data does not fit into the SmartPlant Reference Data, but where it is required to quickly and easily have this data available for the SmartPlant Materials Bill of Material module or for BOM data import via the SmartPlant Materials Open MTO interface (OMI).

Introduction


Introduction


S E C T I O N 2

The SmartPlant Materials Open Ident Interface offers the following features with regard to the extent of imported data, job execution control, and protocol generation.

Imported Data Reference Data

Generally, import of ident data requires the existence of reference data down to the commodity code level. The assignment of ident data to a specific commodity code will then be done by processing the content of the imported ASCII files.

So, the Open Ident Interface is not meant to replace the SmartPlant Reference Data functionality by means of an import interface, but rather to complement it in order to make external data available to SmartPlant Reference Data in a quick and convenient way.

Context of Import Execution Data is imported into that product group or project which the user who starts the import job execution is logged into.

Commodity groups / commodity parts from the import file is validated against the user's login discipline. If this standardization data has been created within another discipline, a warning will be logged to the import protocol.

Attribute values (ident attributes) from the import file is validated against the allowed values for the user's login language.

Idents The ident code from the import file will be imported into SmartPlant Reference Data. The import main program will generate the internal ident. The import main program will check the validity of the commodity code and its relation to the commodity group and commodity part that are also part of a physical import record. The import program will create the relation between the commodity code and the ident code from the import file. The new ident will be imported with Size 1 – Size 5 attributes as specified in the import file. Only new idents will be created; the import program will not modify data that has been created by SmartPlant Reference Data.

Features and Functionality



Ident Descriptions For each ident, language-dependent descriptions can be imported for several languages in one single import file. However, this will only be done for idents that have been imported by the Open Ident Interface; the import program will not modify descriptions for existing idents created by SmartPlant Reference Data.

Ident Attributes For each ident it is possible to import several attribute values. However, this will only be done for idents that have been imported by the Open Ident Interface; the import program will not modify attribute values for existing idents that have been created by SmartPlant Reference Data.

Ident Structures The Open Ident Interface supports import of assembly structures (that is, ident structures) for those idents that have been imported. Ident structures that have been built by SmartPlant Reference Data will not be modified; only new structures will be created.

Job Execution Import jobs can only be executed online from the S.80.11 OII – Import Jobs screen..

The first step of data import is to transfer the file content into an interface table (that is, a working table) using the Oracle® tool SQL*Loader. The structure of this interface table reflects the file format specification. In the second step, data in this table will be processed sequentially; this process includes validation, foreign key data lookup, and insertion of valid data into the central SmartPlant Reference Data tables.

The Open Ident Interface is implemented as a tool for importing master data, not as a tool for regular imports of transaction data. Because of this usage pattern, the components of this interface are not multi-user-enabled, which means that at the start time of import job execution, exclusive locks will be placed on several database objects to ensure that several import jobs that accidentally have been started at the same time do not interfere with each other. Instead, one of these jobs will be cancelled immediately with an error message.

All steps involved in an import job execution are integrated with the SmartPlant Materials user interface. The import protocol, however, will be created externally as a protocol file that can be accessed by any tool that can handle flat ASCII files.

For the purpose of import data validation, a simulation mode, similar to that of the OMI interface, has been implemented. This simulation mode will do all the validations and plausibility checks that imported ident data must conform to, but it will not write any data to SmartPlant Materials standardization tables. The protocol of the job execution can then be used to get an overview of the quality of the data.



Error Handling There are two distinct levels of error handling in the Open Ident Interface main program. For ident records, data validation must succeed for each individual record in order to get it imported. Detail data for an ident such as language-dependent descriptions or ident attributes will be left out of the imported data if it does not meet the constraints on this type of data; however, the previous import of the ident master record is not affected by the failure of validation for its detail records.

For ident structure import, however, data validation will be performed on a global level: Either all assembly records in an import file conform to all constraints on the data, or none of these records will be imported at all. This makes it much easier to correct erroneous assembly data and start over with the corrected file, because it does not burden the user with the need of partly re-mapping hierarchical assembly data to a corrected version of the flat ASCII file. If such assembly errors occur, all previously imported assembly records of the job execution will be rolled back.

Once an assembly record is not valid, no other assembly records will be processed in order

to not import incomplete assembly definitions.

The validation or import of ident data is not affected by assembly errors, although assembly errors in turn may indirectly be caused by a failed data validation for the associated parent ident record.

Import Protocol For each import job, several protocols and log files will be created. The main protocol will include all error messages and warnings that the main import program found while processing and validating the ASCII data. The log files will be created by a SQL*Plus script that is started in the last step of each import job execution. The log files will be placed in the file system where the ASCII file is situated.

Furthermore, a job execution summary will be created in the file system of the database server. You can access this summary directly from the Open Ident Interface S.80.11 job control screen. Logged information includes initiating user, start date, end date, target project/product group, and job outcome, as well as several progress statistics.


S E C T I O N 3

Required Data in the SmartPlant Materials Database NLS

It is necessary to have those language definitions in the SmartPlant Materials database for which you want to import ident descriptions. In a standard SmartPlant Materials installation, definitions for English and German will already be present.

Commodity Codes Commodity groups, commodity parts, commodity codes as well as a "dummy" geometrics definition for these commodity codes (assigned via commodity geometric relation) must be present. Please refer to the SmartPlant Reference Data Setup and User’s Guide for details on how to create this data.

Geometrics The commodity codes to which you want to import idents data must have a "dummy" geometrics series assigned so that each combination of commodity code and size 1 – size 5 remains unique. If you have set the project default parameter ZI_OII_S80 to ‘N’, it is not necessary to set up a geometric series this way; however, the mentioned combination still has to be unique in your import data and in SmartPlant Reference Data; otherwise, the software rejects the import record.

Attributes Attributes for which you want to import values for ident records must be present along with all attribute related definitions, for example, unit assignment, data type, an attribute domain definition (that is, a set of allowed values that can be defined as either general or language-dependent), and the like.

Prerequisites


Prerequisites

Units Units for ident attribute values in the import file must be defined in SmartPlant Materials. They will be validated against the unit that is assigned to the associated attribute.

Unit Conversion Rules If the unit of an ident attribute record does not match that of the attribute definition, the Open Ident Interface main program will attempt to perform a unit conversion for numerical attributes. If such a conversion rule is not defined in SmartPlant Materials, import of this specific attribute record will fail.

DBA Settings DBA settings with significance for the Open Ident Interfaces are:

LOG_ONLINE_JOBS

LOG_FILE_DEST

PLUS_EXECUTABLE

SQLLDR_EXECUTABLE

RBS_OII

OII_IMPORT_PATH.

For detailed information on the available configuration options and their meanings, refer to the SmartPlant Materials DBA Settings guide, available from the Printable Guides page in the software. Refer also to the SmartPlant Materials Project Defaults guide if you need to set up interface directories using a project/discipline-specific structure.

File Format Import data must be present as a flat ASCII file. Language-dependent special characters can only be processed if the installed database character set supports them.

The decision for which database character set will be used is made when the database is created. You cannot change the character set later on.

An import file can include two sections: the first one contains the ident records along with the associated detail records, which may have the types IDENT, IDENT_NLS, and IDENT_ATTR. The detail records will always be processed in the context of the preceding ident record. The second section contains the assembly records, that is, records of type IDENT_STRUC. Although the import program is capable of processing ident data and assembly data in any sequence, it is highly recommended that you at least partition the import files in the way described above, to make the tracking of incorrect data in your files much easier. For large volumes of import data, it may even be a good idea to split the import: first you would import files that only contain ident data, and if all of it has been imported successfully, you would import assembly data from separate files.


Prerequisites

Supported Record Types and Their Processing Rules In the following sections, the processing logic for each record type will be described in detail. The text 'Error!' that you will find in this section for certain conditions means that for an ident record, processing will generate an error log entry, skip the detail records for this ident, and continue with the next ident record found.

If you have assembly records in your import file that depend on this rejected ident record, then processing of this record (and with it, import of all subsequent assembly records) will fail because one of the idents of an assembly is not present. This processing rule has been implemented this way because import of incomplete assembly structure definitions must not take place.

IDENT This record type defines one and only one SmartPlant Materials ident. For each of these records, one and only one record will be created in the SmartPlant Materials table M_IDENTS, if all validations succeed.

The specified commodity group must be present on S.10.02 - Commodity Groups, else: Error!

The specified commodity part must be present on S.10.03 – Commodity Parts, else: Error!

The specified commodity code must be present on S.30.01 – Commodity Codes, else: Error!

The commodity group and commodity part must match the commodity code, else: Error!

If either the commodity group or commodity part has been defined in a discipline other than the discipline the user is logged into, a warning message will be written to the import protocol, but processing will continue.

If the specified ident code is already present in the scope of the target project or the product group: Error!

If the combination of commodity code and size 1 - size 5 is already present on S.80.04 - All Idents: Error!

If the project/discipline default ZI_OII_S80 is set to Y, and if the commodity code is of an item type with item rule 'STD' or item rule 'SWT', the combination of commodity code and input 1 – input 5 must be present on S.80.01 – Build New Idents, else: Error!

If the project/discipline default ZI_OII_S80 is set to N, then the check against S.80.01 will not be performed.

If the specified commodity code is of an item type with item rule 'TOM' or item rule 'TWM', the check against S.80.01 will not be performed, either (so no dummy geometric series needs to be assigned to this commodity code in order to import idents); however, the combination of commodity code and size 1 – size 5 still needs to be unique.

If you specify a unit system, it must match a unit system defined on A.10.06 – Unit Systems, else: Error! If you don’t specify a unit system in your file, the project default is used.


Prerequisites

IDENT_NLS This record type defines one language-dependent ident short description and description for the ident that preceded this record. If that ident could not be imported, the IDENT_NLS record will not be processed at all.

For each valid record, a record will be inserted into the SmartPlant Materials table M_IDENT_NLS, or updated if the record already exists and the job runtime option settings allow this update.

For each ident, multiple description records, referencing different languages, may be imported.

These languages must be defined in SmartPlant Materials, else: Error!

IDENT_ATTR This record type defines an attribute assignment along with an associated attribute value for the ident that preceded this record. If that ident could not be imported, the IDENT_ATTR record will not be processed at all.

For each valid record, a record will be inserted into the SmartPlant Materials table M_IDENT_VALUES, or updated if the record already exists and the job runtime option settings allow this update.

The attribute must be defined on A.50.01 – Attributes, else: Error!

The attribute value must match the data type definition and allowed field length, else: Error!

If a set of allowed values has been defined for this attribute, the attribute value in the import file must match one of these values, else: Error!

If the definition of these allowed values is language dependent, then the validation will be done using the user's login language.

The specified unit for the attribute assignment must be defined on A.10.12 – Units of Measure, else: Error!

If the unit from the ASCII file does not match that of the attribute definition:

If the attribute data type is numerical, a value conversion according to A.10.13 – Unit to Unit must be possible, else: Error!

If the attribute data type is not numerical, only a warning will be issued.

IDENT_STRUC This record type defines an assembly structure record by relating a parent ident to a child ident along with supplying the position descriptor of the child ident within its parent, and specifying a quantity.

For each record, a record will be inserted into the SmartPlant Materials table M_IDENT_STRUCTURES.

All records of this type must conform to the integrity constraints that are defined on the target table, else: Error!

The idents referenced by the assembly structure records must have been imported by the Open Ident Interface; either by the currently running import job, if the option 'All Assemblies' is not


Prerequisites selected; or by any Open Ident Interface import job, if the option 'All Assemblies' is selected. Otherwise: Error!

If an assembly record would supplement or complete an existing assembly structure, then this existing assembly structure must have been imported by the Open Ident Interface; either by the currently running import job, if the option 'All Assemblies' is not selected; or by any Open Ident Interface import job, if the option 'All Assemblies' is selected. Otherwise: Error!

Because SmartPlant Materials assemblies are represented by the use of hierarchical data structures, no such assembly record may create a cyclic reference. Otherwise: Error!

These processing rules guarantee that no data created by SmartPlant Materials standardization programs will ever be modified or deleted by the Open Ident Interface.

Record Structure Generally, the record structure that must be used for OII import files is very similar to that of the SmartPlant Materials Open MTO Interface (OMI). The first field contains the record type description, and the ‘Pipe’ special character separates the remaining fields from each other: '|' (ASCII code 124). The last field of a physical record must be terminated by the '|' character followed by a new line character (this is platform-dependent; it is a combination of the CR and the LF characters on PC platforms, while on Unix platforms, it is the LF character only).

The record type descriptor determines which field must be included in a record, what significance each of the fields has, as well as the optionality and the allowed field size according to the following record type specification.

IDENT IDENT|GROUP_CODE|PART_CODE|COMMODITY_CODE|IDENT_CODE|IN1|IN2|IN3|IN4|IN5|USY_CODE| IDENT Record type mandatory GROUP_CODE Commodity Group Code Char(10) mandatory PART_CODE Part Code Char(10) mandatory COMMODITY_CODE Commodity Code Char(60) mandatory IDENT_CODE Ident Code Char(13) mandatory IN1 - IN2 Input 1 - Input 2 Char(7) mandatory IN3 - IN5 Input 3 - Input 5 Char(7) optional USY_CODE Unit System Char(10) optional

IDENT_NLS IDENT_NLS|LANGUAGE|SHORT_DESC|DESC| IDENT_NLS Record type mandatory LANGUAGE Language (Description) Char(60) mandatory SHORT_DESC Ident-NLS Short desc Char(255) mandatory DESC Ident-NLS Description Char(2000) mandatory


Prerequisites

IDENT_ATTR IDENT_ATTR|ATTR_CODE|UNIT_CODE|ATTR_VALUE| IDENT_ATTR Record type mandatory ATTR_CODE Attribute Code Char(30) mandatory UNIT_CODE Unit Code for the attribute Char(10) mandatory ATTR_VALUE Attribute value Char(255) optional

IDENT_STRUC IDENT_STRUC|PARENT_IDENT_CODE|CHILD_IDENT_CODE|POS|QTY| IDENT_STRUC Record type mandatory PARENT_IDENT_CODE Ident Code (Parent) Char(13) mandatory CHILD_IDENT_CODE Ident Code (Child) Char(13) mandatory POS Position descriptor Char(4) mandatory QTY Relative child ident quantity Number(7,3) mandatory

File Format Example Here is an example of a simple import file:

IDENT|F|ORW|FORWABFA3C1D06*2|I000|2|XS|0|0|0|| IDENT_NLS|English|E-Text:I000|E-Lang-Text:I000|||||||| IDENT_NLS|Deutsch|D-Text:I000|D-Lang-Text:I000|||||||| IDENT_ATTR|ECCENTR|MM|0.0|||||||| IDENT|F|ORW|FORWABFA3C1D06*2|I001|2|STD|0|0|0|| IDENT_NLS|English|E-Text:I001|E-Lang-Text:I001|||||||| IDENT_NLS|Deutsch|D-Text:I001|D-Lang-Text:I001|||||||| IDENT_ATTR|ECCENTR|MM|0.1|||||||| IDENT|F|ORW|FORWABFA3C1D06*2|I002|2|XXS|0|0|0|| IDENT_NLS|English|E-Text:I002|E-Lang-Text:I002|||||||| IDENT_NLS|Deutsch|D-Text:I002|D-Lang-Text:I002|||||||| IDENT_ATTR|ECCENTR|MM|0.2|||||||| IDENT|F|ORW|FORWABFA3C1D06*2|I003|2|SCH10S|0|0|0|| IDENT_NLS|English|E-Text:I003|E-Lang-Text:I003|||||||| IDENT_NLS|Deutsch|D-Text:I003|D-Lang-Text:I003|||||||| IDENT_ATTR|ECCENTR|MM|0.3|||||||| IDENT|F|ORW|FORWABFA3C1D06*2|I004|2|SCH160|0|0|0|| IDENT_NLS|English|E-Text:I004|E-Lang-Text:I004|||||||| IDENT_NLS|Deutsch|D-Text:I004|D-Lang-Text:I004|||||||| IDENT_ATTR|ECCENTR|MM|0.4|||||||| IDENT|F|ORW|FORWABFA3C1D06*2|I005|2|SCH40S|0|0|0|| IDENT_NLS|English|E-Text:I005|E-Lang-Text:I005|||||||| IDENT_NLS|Deutsch|D-Text:I005|D-Lang-Text:I005|||||||| IDENT_ATTR|ECCENTR|MM|0.5|||||||| IDENT|F|ORW|FORWABFA3C1D06*2|I006|2|SCH5S|0|0|0|| IDENT_NLS|English|E-Text:I006|E-Lang-Text:I006|||||||| IDENT_NLS|Deutsch|D-Text:I006|D-Lang-Text:I006|||||||| IDENT_ATTR|ECCENTR|MM|0.6|||||||| IDENT|F|ORW|FORWABFA3C1D06*2|I007|2|SCH80S|0|0|0|| IDENT_NLS|English|E-Text:I007|E-Lang-Text:I007||||||||


Prerequisites

IDENT_NLS|Deutsch|D-Text:I007|D-Lang-Text:I007|||||||| IDENT_ATTR|ECCENTR|MM|0.7|||||||| IDENT_STRUC|I000|I001|10|3||||||| IDENT_STRUC|I000|I002|20|5||||||| IDENT_STRUC|I001|I003|A10|7||||||| IDENT_STRUC|I001|I004|A20|11||||||| IDENT_STRUC|I001|I005|A30|13||||||| IDENT_STRUC|I002|I006|B10|17||||||| IDENT_STRUC|I002|I007|B20|19|||||||

The file structure that the OII Export Interface creates will look very much the same; however, additional job information (that is, job code, date the job ran, query conditions that were used to restrict the export data, and so forth) will be embedded into the comment section of exported ASCII files. An export file can look like the following:

-- -- ************************ -- * * -- * SPMat 2011 (7.0.4) * -- * * -- ************************ -- -- Open Ident Interface - Data Export File -- -- Copyright (C) 2011 Intergraph Corporation -- -- -- Call parameters: -- -- OIIE Job ID : 5120 -- Job Code : J2 -- Project (PG) : J8888 -- Query Cond (Idents) : PS_FITTINGS -- Query Cond (Assembly) : None -- Started on : 02-FEB-2011 -- Server side log file : /home06/oracle/log_data/m5k/OIIE_15032.log -- Spoolfile : C:\TEMP\oii_exp.dat -- -- ------------------------------------------------------- -- ---------------- Data Section starts ---------------- -- ------------------------------------------------------- -- IDENT|F1_FITTING|01|F101XX1S1VXXXX|I523392|.125|0|0|0|0|| IDENT_NLS|ENGLISH|NPS .125 SCH |Nominal Pipe Size: .125 Schedule/WT: |||||||| IDENT|F1_FITTING|01|F101XX1S1VXXXX|I523393|.25|0|0|0|0|| IDENT_NLS|ENGLISH|NPS .25 SCH |Nominal Pipe Size: .25 Schedule/WT: |||||||| IDENT|F1_FITTING|01|F101XX1S1VXXXX|I523394|.375|0|0|0|0|| IDENT_NLS|ENGLISH|NPS .375 SCH |Nominal Pipe Size: .375 Schedule/WT: |||||||| -- -- -------------------------------------------------------


Prerequisites -- ----------------- Data Section ends ----------------- -- ------------------------------------------------------- -- -- OII Export done. --


S E C T I O N 4

This chapter illustrates how to use the Open Ident Interface by presenting a step-by-step example. The prerequisite for the use of the interface is that all its components have been properly installed and configured as described in the appendix of this documentation.

Extracting the Data from the 3rd Party or Legacy System

The first step necessary for using the Open Ident Interface is to extract the data you want to import into SmartPlant Materials from the system where it currently resides. This problem is closely related to the technical details of this system, so it is not possible to give a general description here. If the other system happens to be another Oracle database, you should look closely at the SmartPlant Materials scripts B200144.SQL and OII_LOG.SQL. These scripts can serve well as a template on how to extract large amounts of data out of an Oracle database by writing a quite simple SQL*Plus script with a more than acceptable performance. For very large quantities of data, the best throughput is normally achieved by writing a specialized Pro*C program or a C program that utilizes low-level OCI calls.

File Placement For information on where OII expects to find its related files, please refer to the appropriate chapter in the installation and configuration appendix of this document. If your SmartPlant Materials database runs on a Unix server, you must make sure that you transfer your import files in ASCII mode to their proper location. Otherwise, SQL*Loader will fail to interpret the file format correctly.

Data Import


Data Import

Defining an Import Job To define an import job, open the S.80.11 OII – Import Jobs screen.

The runtime options are the most important options for the job definition.The options have the following meanings:

Transfer: This check box toggles the simulation mode for ident data. Note that the simulation is of no particular use if the import file contains ident data as well as assembly data that depends on the import of the former section; or if assembly data with more than one hierarchy level is present in the import file. The reason is that the data necessary for assembly record validation will not be present if the job runs in simulation mode.

All Descriptions: If checked, IDENT_NLS data for idents imported by any (that is, any other) import job may be created. If unchecked, the job will only create such data for those idents that are in their own import file.

All Attributes: If checked, IDENT_ATTR data for idents imported by any (that is, any other) import job may be created. If unchecked, the job will only create such data for those idents that are in their own import file.

All Assemblies: If checked, IDENT_STRUC data for either ident or ident structures imported by any import job may be created. If unchecked, the job will only create such data if all the idents and all the existing ident structure to which it requires to add records have been imported by this import job.

Allow Replace: This check box is meaningful only in conjunction with the 'All Description' and/or the 'All Attributes' runtime options. If one of these options, or both, are checked, then additionally checking this check box means that existing IDENT_NLS or IDENT_ATTRS may also be updated by the contents of the import file.

Please note that in a normal SmartPlant Materials configuration, even the most restrictive setting requires that you check the 'Allow Replace' options and uncheck the 'All descriptions' option, because after ident creation, a set of default system-generated ident descriptions will already be present. If you want this default data to be replaced by imported descriptions, you must have the options set at least as described.


Data Import

Starting Job Execution Click the Start button to invoke job execution. The subsequent steps are described in the following chapters.

File Transfer into the Interface Table The first step calls SQL*Loader to import your ASCII file.

Regardless of the overall success or failure of the import job, you should carefully check the loader log files to see if any records have been discarded or written to the bad file. The loader parameters are set so that the SQL*Loader stops at the first data error. You must not change this configuration, as doing so would possibly harm data consistency.

Import Main Program When SQL*Loader has finished, the import main program will be called. Its purpose is to validate all data from the interface table and write the individual records to the appropriate central SmartPlant Reference Data tables. For large amounts of data, this process may take due time, because it has to perform many of these checks to guarantee the highest extent of data consistency possible.

Log File Creation The final step is to call SQL*Plus, which will create and spool out an import protocol log file. After that step is done, your screen may look like the following:


Data Import In the lower half of the screen, a message area has been opened, in which the calling and the outcome of each single step will be displayed. It will also show what the name of the import protocol report file is and where it has been created. Once you have located and opened or printed this file, you have the option to review the import statistics file that has been created on the database server.

Once you close this message area, its contents are gone, so you should at least note the name and location of the import protocol file before closing the screen.

Reviewing the Logfile You can click the View Online Log button to open a new window where the log file content is displayed.


Data Import

Erroneous Import Data If data errors have occurred, you should refer to the error section in the appendix of this document. It contains a list of the possible errors and warnings along with explanations of their meanings.

Correcting Import Data and Starting Over Depending on the kind of errors encountered, it may be necessary to resubmit certain parts of the import file again. If, for example, incorrect data has accidentally been included in the assembly data section, all assembly records will have been rolled back by the import main program. Simply correct the data and store it in a new, separate file, which you can resubmit using a new job definition. Please be sure to set the runtime options for this new job accordingly.

Viewing and Modifying Imported Data Two screens are provided to view and modify the imported data, the S.80.12 screen for imported ident data, where ident value assignments may be maintained, and S.80.13 for assemblies (that is, ident structure data), respectively.

Idents and Ident Values On the S.80.12 OII – Imported Idents screen, you can review and modify idents that have been imported by the Open Ident Interface.


Data Import The mechanism to query for specific idents adheres to the SmartPlant Reference Data components hierarchy. In the first (Commodity Groups) block, you can query any commodity group. In the second (Commodity Parts) block, you can query the associated commodity parts. In the third (Commodity Codes) block, the commodity codes for this part are displayed. In the fourth (Idents) block, the idents that belong to the selected commodity code.

In the last (Ident Values) block, you can assign attributes to selected idents. The Attribute field shows the name of the attribute, with its unit in the Unit field. You can assign an attribute value to the attribute in the Value field. The Created by field shows the screen on which this attribute is assigned to the ident. The Manual indicator shows whether this attribute was created manually.

Assembly Data On the S.80.13 OII – Imported Assemblies screen, you can review and modify assemblies that have been imported by the Open Ident Interface.

The mechanism to query for specific assembly master idents adheres to the SmartPlant Reference Data components hierarchy. In the first (Commodity Groups) block, you can query any commodity group. In the second (Commodity Parts) block, you can query the associated

commodity parts. Click the Next Block button to open Window 2.

In the first (Commodity Codes) block of Window 2 for the selected part, the commodity codes for this part are displayed if they have associated idents .

In the second (Idents) block, the idents that belong to the selected commodity code are displayed. You can click the Show only Idents with imported assemblies button to display only assembly parent idents. The label of the button will change to Show all Idents.


Data Import

Click the Next Block button to open Window 3.

In the first (Ident Structure) block, you can view and modify the assembly structure.

The assembly child idents are displayed with their position in the Pos field, their quantity in the Quantity field, their ident in the Ident field, their ident code in the Ident Code field, their sizes in the Input 1 and Input 2 fields, and their description in the Short Desc field.

In the second (Ident Structure Values) block, you can assign attributes to selected assembly positions. These attributes will serve as attribute templates when the assembly is resolved and copied to the BOM using the fixed check job definition 'BOM_COPY' (Copy Assemblies to BOM) on the B.20.01.41 screen.

The order sequence number for the attribute assignment is displayed in the Pos field. The Attribute field shows the name of the attribute. You can assign an attribute value to the attribute in the Value field. The Manual indicator shows whether this attribute was created manually.


Data Import


S E C T I O N 5

Data export jobs can be defined, executed, and controlled from the S.80.14 OII – Export Jobs screen.

You need to enter job information similar to that required on S.80.11OII - Import Jobs. Additionally, you must specify the file name and directory for your export file.

Setting Up Where Conditions SmartPlant Materials needs to know which idents and which assemblies you want to export. You can specify this information by entering a Where condition that defines this data. You can have both kinds of data (ident and assembly) in one export file by entering both Where conditions here. In the LOVs in the Where Condition for Idents and Where Condition for Assemblies fields, all Where conditions that have been set up on A.60.06 with a module reference to S.80.14 are available.

Data Export


Data Export

Starting Job Execution After you have defined the job and saved it, click the Start button to start the job execution.

Reviewing the Export File Once the job has finished, you can review the export file with any ASCII editor of your choice. The file format will be the same that is needed for Open Ident Interface import files. Please refer to the section outlining the format specification above in this manual.


S E C T I O N 6

SmartPlant Materials Tables M_IDENT_VALUES. Intersection table between M_IDENTS and M_ATTRS. Stores imported attributes for idents.

M_OII_IMPORT_JOBS. Stores the job definitions.

M_OII_IMPORT_DATA. Interface table into which the ASCII file will be loaded in the first step via SQL*Loader. Detail table to M_OII_IMPORT_JOBS.

M_OII_IMPORT_JOB_ERRORS. This table stores the import protocol. Detail table to M_OII_IMPORT_JOBS.

M_OII_IMPORTED_IDENTS. Intersection table between M_OII_IMPORT_JOBS and M_IDENTS. For each ident that has been imported, one trace record will be stored in this table.

M_OII_IMPORTED_ASSEMBLIES. Intersection table between M_OII_IMPORT_JOBS and M_IDENT_STRUCTURES. For each assembly structure record that has been imported, one trace record will be stored in this table.

M_OII_EXPORT_JOBS. Stores the definition for export jobs.

M_OII_EXPORT_DATA. Interface table into which the export main program writes the extracted data. The SQL*Plus export script performs a query against this table to spool the data out to a flat ASCII file.

Stored PL/SQL Program Units The main import program and the SQL*Loader Environment Interface programs are implemented in the PL/SQL package M_PCK_OII. Log file handling is implemented in the packages M_PCK_LOG_FILE and M_PCK_FILE_IO. Export functionality is implemented in the PL/SQL package M_PCK_OII_EXP.

Transaction Control The execution of the main program for an import job consists of a single transaction. You can define a specific rollback segment that will be used by the main import program. This assignment can be done on the A.60.04 - DBA Settings screen by supplying a value for the setting RBS_OII.

Implementation


Implementation

Exclusive Object Locks Before the SQL*Loader for the file import is called, an exclusive lock is placed on the job definition table. This lock is then held by the calling session as long as SQL*Loader is running to avoid any interference among different import jobs concurrently accessing the interface table.

Dependencies on Other SmartPlant Materials Modules

Internal message handling is done by the PL/SQL package M_PCK_M in conjunction with MPCK_LOGIN and M_PCK_LOG_FILE.

Access to global SmartPlant Materials configuration options is done by use of the M_PCK_DBA_SETTINGS API package.

Open Ident Interface transaction management utilizes the M_PCK_ROLLBACK API package.


A P P E N D I X A

In order to use this interface, your DBA or SmartPlant Materials administrator at your site needs to perform some manual steps to set up the directory structure for OII. Please refer to the following topics for further setup information.

In This Appendix Directories and Files ...................................................................... 35 Instance Configuration Tasks ........................................................ 35 File Placement ............................................................................... 36 Adjusting the SQL*Loader Parameter File .................................... 36 Configuring SmartPlant Materials Settings .................................... 36

Directories and Files The files for the Open Ident Interface are stored on the application server in the following directory structure:

%SPMAT_HOME%\Sql\Install\OII\ SQL*Loader control file / OII Import/Export scripts

oii_log.sql SQL*Plus script for import protocol creation

oii500.ctl SQL*Loader control file for OII

oii500.par SQL*Loader parameter file for specification of bind array size

oie_510.sql SQL*Plus script for data export from interface table

Instance Configuration Tasks Before using the Open Ident Interface, you should configure a database server directory for use as an UTL_FILE_DIR, if you have not already done so. If you have chosen to have many separate directories, for example, on a per-project/discipline basis, you need to supply a UTL_FILE_DIR line for each of these directories in your instance parameter file.

You should not use the option UTL_FILE_DIR=* (which would allow the PL/SQL file system access to all local drives on your database server), because this configuration would seriously compromise server and database security. Intergraph strongly discourages using this configuration option.

Appendix: Setup and Configuration



File Placement Please note that for online import/export execution, it is mandatory that you keep the files from the sql\ directory together in one single directory. This directory is also the place where you must put the import ASCII files, and where your export files get created, so that all files can be accessed by the SmartPlant Materials Open Ident Interface programs.

Adjusting the SQL*Loader Parameter File You can adjust the bind array size that is used by the SQL*Loader run for file import into the OII working table. This parameter is located in the oii500.par file.

You must not configure any other SQL*Loader options or settings in this file.

Configuring SmartPlant Materials Settings Configure the LOG_ONLINE_JOBS and LOG_FILE_DEST settings on the A.60.04 screen if you want the Open Ident Interface to create log files for online jobs. You must configure the SQLLDR_EXECUTABLE and PLUS_EXECUTABLE settings for online imports/exports.

If you would like to have the default OII server directory available by clicking the Default Dir button on S.80.11, you should configure the OII_IMPORT_PATH setting on the A.60.04 screen . If you need finer control over the directory structures , you can additionally configure the ZI_OII_IN (maps to OII_IMPORT_PATH) and/or ZI_OII_OUT (maps to OII_EXPORT_PATH) settings on a project group, project, or project/discipline basis on the A.20.11, A.20.12 and A.20.13screens, respectively.

For imports and exports with any remarkable import file size or export data volume, it is highly recommended that you also assign a value to the RBS_OII setting. This setting should point to an available online rollback segment. Keep in mind that each import job execution will run in a single transaction, so you should make sure that the assigned segment is sufficiently large. If you have any questions, you should contact your SmartPlant Materials DBA.

For more information about DBA settings, refer to the SmartPlant Materials DBA Settings guide, available on the Printable Guides page in the software.

OII Export Clicking the Online button on S.80.14 to create an OII-formatted file with SQL*PLUS. Edit the OII_DOWNLOAD_DEST setting on A.60.04 to set the destination of the OMI file on the application server. The value can look like the following:

c:\spmat\ident_downloads\

The path can be user-defined, but it must exist on the application server. Append a trailing backslash here.

After creating the file in the destination directory, SmartPlant Materials will open a new browser window displaying the result. Edit the OII_DOWNLOAD_URL setting on A.60.04 to enable the web server to find the OMI file on the application server. A valid entry for the setting is:

your_web_server/ oii_download


Appendix: Setup and Configuration The name of your web server is followed by a virtual directory name. Do not append a trailing slash. You must define an alias in the web server configuration. In the spmat2011.conf file on the application server, there should be a line that looks like the following:

AliasMatch ^/oii_download/(..*) "C:\spmat\ident_uploads/$1"

The right hand entry must match the OII_DOWNLOAD_DEST setting, except that the backslash is replaced by a slash. The left hand entry must match the OII_DOWNLOAD_URL, but the server name is omitted and a trailing slash is added.

The PLUS_EXECUTABLE setting must be set in order for the download to happen. The oie_*.sql script must be placed in the directory specified in OII_DOWNLOAD_DEST.

OII Import Clicking the Upload button on S.80.11 opens a new browser window displaying an upload form. Make sure the SERVLET_PATH setting on A.60.04 is set. The value can look like the following:

your_web_server/servlets

The name of your web server is followed by the string /servlets. Do not append a trailing slash.

When the user picks up the file from his file system, he can click the Submit button to send the file to the server. The destination path on the application server, where the file is stored, must be maintained in the OII_UPLOAD_DEST setting on A.60.04. The following is a valid format for the value (with trailing backslash):

c:\spmat\oii_uploads\

When the upload is finished, the user can close the additional browser window. The directory and file name of the uploaded file are automatically stored in the appropriate fields of B.40.01. The file name is concatenated by the string 'OIJID' and the ID of the actual OII job.

The directory stored in OII_UPLOAD_DEST must contain the OII control (*.ctl) and .parameter (*.par) files that are needed by the SQL*Loader.

After entering the remaining parameters on S.80.11, you can click the Start button to run the job.


A P P E N D I X B

In This Appendix Error Messages on S.80.11 ........................................................... 39 Error Messages on S.80.14 ........................................................... 41 Error Messages in the Import Protocol .......................................... 43

Error Messages on S.80.11 The following error messages can be issued by SmartPlant Materials on the S.80.11 – OII Import Jobs screen.

MAR-15800

Cause:

Action:

No import file specified

You tried to start an import job without specifying an import file.

Specify a valid import file.

MAR-15801

Cause:

Action:

Setting 'OII_IMPORT_PATH' not defined

You tried to use the default directory setting, but it is not defined on A.60.04 or A.20.12/13.

Define the setting on A.60.04 DBA Settings, on A.20.12 Project Defaults, or on A.20.13 Project/Discipline Defaults.

MAR-15802

Cause:

Action:

No job code specified

You attempted to submit an import job without specifying a valid job code.

Specify a valid job code and commit the job definition.

MAR-15803

Cause:

Action:

Please commit your changes first

You attempted to start a job without committing the definition.

Commit the job definition.

MAR-15804

Cause:

Action:

Please enter a complete job definition first

You failed to supply all job details that are mandatory.

Supply all information that is needed.

MAR-15805

Cause:

Action:

Import job finished with return status #1

The online job execution finished. (This is not necessarily an error message)

Depending on the outcome of the job execution, you may proceed with reviewing the import protocol. If the return status is 'ERROR', more information about the kind of error will be given in the info panel on the S.80.11screen.

Appendix: Error Messages


Appendix: Error Messages MAR-15806

Cause:

Action:

OII-SQL*Loader: #1

SQL*Loader failed to finish the first step (importing the file into the interface table) successfully. This error may merely be a file access error, or it could be related to the import data itself. Please review the SQL*Loader log file, bad file, and discard file.

The necessary action depends on the exact cause of the error. If, for example, you simply specified a non-existent file, then you could create a new job definition with a valid file and start over.

MAR-15807

Cause:

Action:

Could not lock OII Job table exclusively

This error indicates that another concurrent OII import job is running, or another pending transaction against the job definition table exists, holding a lock.

For the reasons outlined in Job Execution (on page 12), the Open Ident Interface is not multi user-enabled. Retry the operation when the other job has finished.

MAR-15810

Cause:

Action:

#1 records of import data for this job have been deleted

On the S.80.11 screen, you are given the option of deleting all interface table data for a specific import job in order to free that database space. This message tells you how many records in the interface table been deleted. This message is only an informational message.

No action is required. Please note that deleting the interface data records will not affect the ident data or assembly data that has been imported by this job. It will only delete the imported ASCII file from the interface table, and after doing so, you will not be able to see the import record that is related to specific protocol messages on S.80.11. You should only perform this operation if you do not need any online access to the protocol details anymore.

MAR-15811

Cause:

Action:

Call to #1 raised SQL error #2

This error is an internal error message not normally issued.

Please make sure to record all details, especially all accompanying SQL error messages that are displayed or appear in the log file, and then contact SmartPlant Materials Support.

MAR-15812

Cause:

Action:

Setting 'SQLLDR_EXECUTABLE' not defined

You attempted to start an online import; however, the necessary setting on A.60.04 that tells SmartPlant Materials how Oracle SQL*Loader must be called is not configured.

Configure this setting on A.60.04, and start over with a new import job definition.



Cause:

Action:

OII Online import aborted due to fatal error

A fatal error occurred that made further execution of the import job impossible. This error message may be accompanied by SmartPlant Materials error message MAR-15811 or MAR-15808. In case of an internal error, it may be accompanied by an Oracle error message from the database server.

If the accompanying messages in the info panel or in the log file do not reveal the exact cause of this error, or if they do, but you are not sure about how you could avoid the circumstances under which this error occurs, you should contact SmartPlant Materials Support. Please be sure to record all details, especially all accompanying SQL error messages that are displayed or appear in the log file.

MAR-15814

Cause:

Action:

Setting 'PLUS_EXECUTABLE' not defined

You attempted to start an online import; however, the necessary setting on A.60.04 that tells SmartPlant Materials how the ORACLE SQL*Plus program must be called is not configured (SQL*Plus is needed to generate the import protocol file).

Configure this setting on A.60.04, and start over with a new import job definition.

MAR-15815

Cause:

Action:

File I/O Error #1

On the S.80.11 screen, you attempted to view the log file that was created for an online import job. However, for some reason that is detailed by this error message, access to the server file system failed.

Contact your DBA, SmartPlant Materials administrator, or database server system administrator to have one of them check why file access is not possible. One reason may be that your SmartPlant Materials installation is configured to store SmartPlant Materials log files in a temporary directory that will be deleted by a background job at regular intervals.

Error Messages on S.80.14 The following error messages can be issued on the S.80.14 – OII Export Jobs screen:

MAR-15816

Cause:

Action:

No query condition specified

You did not specify any query condition that determines your export data.

You need to specify at least one query condition, either for ident data or for assembly data.

MAR-15817

Cause:

Action:

Setting 'OII_EXPORT_PATH' not defined

You tried to use the default directory setting, but it is not defined on A.60.04 or A.20.12/13.

Define the setting on A.60.04 DBA Settings, on A.20.12 Project Defaults, or on A.20.13 Project/Discipline Defaults.



Cause:

Action:

No export file specified

You tried to start an export job without specifying an export file.

Specify a valid export file.

MAR-15819

Cause:

Action:

Export job finished with return status #1

The online job execution finished. (This is not necessarily an error message)

Depending on the outcome of the job execution, you can proceed with reviewing the export file that has been created. You should also check the export protocol. If the return status is 'ERROR', more information about the kind of error will be given in the info panel on the S.80.14 screen.

MAR-15820

Cause:

Action:

OII Online export aborted due to fatal error

A fatal error occurred that made further execution of the export job impossible. In case of an internal error, this error may be accompanied by an Oracle error message from the database server.

If the accompanying messages in the info panel or in the log file do not reveal the exact cause of this error, or if they do but you are not sure about how you could avoid the circumstances under which this error occurs, you should contact SmartPlant Materials Support. Please be sure to record all details, especially all accompanying SQL error messages that are displayed or appear in the log file.

MAR-15822

Cause:

Action:

Query condition for #1 is invalid

A query condition that you specified for selection of your export data is not valid for this purpose.

Check the query condition on the A.60.06 Where Conditions screen. You must make sure that you have already generated the database view for this condition, and that the view is not outdated. Furthermore, your query condition must have a mapping for the physical SmartPlant Materials database table.column m_idents.ident, and the query must also retrieve at least one ident record (check the result set of your query using the RESULT button on A.60.06).

MAR-15823

Cause:

Action:

Ident #1 for ident structure not available

This error is an internal error message not normally issued.

Please be sure to record all details, especially all accompanying SQL error messages that are displayed or appear in the log file, and contact SmartPlant Materials Support.



Error Messages in the Import Protocol This section provides an overview of warnings or error messages that can appear in the import protocol and that are related to the import data.

General Messages OII Import Job <job_code> for Project <project/product group code>, starting…

Building indexes…

Initializing use of rollback segment…

Processing of interface data starts…

Processing of interface data finished.

Dropping indexes…

Import finished successfully: <#w> warnings, <#e> errors

These messages are only informational status messages.

*** Could not drop index. ORA-01418: specified index does not exist

This message is only informational , indicating that a specific index has not been established, so the import main program goes ahead and creates it.

Unsupported record type

The import file contains a record type that does not belong to the types described in the file format specification.

Import of assemblies has been aborted completely because of inconsistent import data

During import processing, invalid or inconsistent assembly data has been found. For this reason, all assembly records that had been imported before this error occurred have been rolled back, and no more assembly records have been processed by the import job. Please check the log file for the offending assembly record, correct the data, and repeat the assembly import.

Ins/Upd not allowed, ident not imported.

Ins/Upd not allowed, <runtime_option> = N

Replacing existing <descriptions|attribute value> not allowed.

These messages indicate that the required operation is either not possible because it would change non-imported ident data (in the case of the first message), or that the operation is not allowed because of the specified runtime options for 'All <Attributes|Descriptions|Assemblies> 'or the 'Allow Replace' option for ident descriptions and ident attribute values.



Messages Related to Missing or Invalid Data Mandatory field is empty: #1

Field too long: #1

These messages display if your import data does not conform to the required record structure as outlined in Record Structure (on page 19). Correct your import data and start over.

Messages Related to IDENT Records Commodity Group #1 is defined in another discipline.

Part #1 is defined in another discipline.

These warning messages indicate that your import data references SmartPlant Materials standardization data that has been created by a discipline other than your own. These messages will not affect import processing.

Unit System #1 not found.

Commodity Code #1 not found.

Part #1 not found.

Commodity Code and Group/Part do not match.

Ident Code #1 exists, but has a different Commodity Code.

Ident Code #1 found multiple times.

These messages indicate that your import data is inconsistent with respect to SmartPlant Materials standardization data.

Commodity Code / Geometric Data already exists in S.80.01.

Indicates that the combination of commodity code and size 1 – size 5 would not be unique if this ident record is inserted.

Commodity Code / Geometric Data for STD item not in S.80.01.

Indicates that this combination of commodity code and size 1 – size 5 does not belong to the valid combinations on S.80.01 – New Idents. Check the setup of the 'dummy' commodity code/geometric relation.

Ident Code #1 already exists (<S|I|J>)

This message indicates that the specified ident codes have been found. Status code S means that SmartPlant Materials standardization data may not be changed; status code I means that the data has been imported by another OII import job; and status code J indicates that the data has been imported previously by the job currently running. Depending on the job runtime options, this ident data may or may not be completed by IDENT_NLS or IDENT_ATTR data from the import file.



Messages Related to IDENT_NLS records No current ident

This internal message is not normally issued. Report this as a bug to SmartPlant Materials Support.

Language #1 not found

The language reference from the import file is not defined in SmartPlant Materials.

More than one NLS_ID for language #1 found.

This internal message is not normally issued. Report this as a bug to SmartPlant Materials Support.

Messages Related to IDENT_ATTR Records Attribute #1 not found.

Attribute #1 has no unit assigned.

Attribute value not numerical.

Attribute value is not a valid date.

Attribute value too long.

Unit #1 not found.

No conversion rule for: unit#1 to unit#2

Attribute value not in allowed domain (A.50.01).

Attribute value not in allowed NLS domain (A.50.01).

Attribute value #1 not within specified bounds (#min, #max)

These messages indicate that an attribute record has been rejected due to the reason outlined in the message text itself.

Unit mismatch (unit#1, unit#2) for non-numerical data.

This warning message indicates that the attribute has another unit assigned than that specified by the import record. Because the data type is not numerical, unit conversion is not necessary, and the record will be imported as it appears in the file.

Messages Related to IDENT_STRUC Records Parent Ident Code #1 does not exist.

Child Ident Code #1 does not exist.

The referenced ident code is not in the database, so the assembly record could not be created. If the ident code is included in the import file, it has failed data validation for some reason, so this message may be a consequential error.

Assembly not allowed, parent ident #1 (S) not imported.

Assembly not allowed, child ident #1 (S) not imported.


Appendix: Error Messages The required operation would create assemblies for SmartPlant Materials standardization data. This operation is not possible through the Open Ident Interface. Use the appropriate functions in the standardization module instead.

Such an assembly record already exists (IDS_UK).

This assembly record would violate a unique-key constraint.

<runtime_option> = N, and parent ident #1 (#status_code) not from current import file.

<runtime_option> = N, and child ident #1 (#status_code) not from current import file.

<runtime_option> = N, cannot create on top of non-imported assembly.

<runtime_option> = N, cannot create below non-imported assembly.

<runtime_option> = N, cannot add to non-imported assembly.

The specified runtime options do not allow you to create, add to, or modify assembly structures that have been created by another OII import job.

Cannot create on top of non-imported assembly.

Cannot create below non-imported assembly.

Cannot add to non-imported assembly.

Assembly record would create loop, cannot import.

The specified runtime options allow you to create, add to, or modify assembly structures that have been created by another OII import job; however, the existing assembly structures to which the import data refers have been created by SmartPlant Materials standardization, so they may not be modified in the way that the import file would require.

Messages Related to SQL*Loader Import These messages can appear in the SQL*Loader main log file.

MAR-15806 #1 Host session not found

MAR-15806 #1 More than one host session found

MAR-15806 #1 Invalid client info format

MAR-15806 #1 Invalid client info data type

MAR-15806 #1 User not found

MAR-15806 #1 Job not found

If you experience any of these error messages, contact SmartPlant Materials Service Support.


A P P E N D I X C

In This Appendix Control File oii500.ctl ..................................................................... 47 SQL*Loader Parameter File oii500.par ......................................... 48

Control File oii500.ctl Do not modify this file.

-- ---------------------------------------------------------- -- File: oii500.ctl -- Open Ident Interface -- ----------------------------------------------------------- Options (Errors = 0, Rows = 2000) -- ------------------------------------------------------------ LOAD DATA -- ----------------------------------------------------------- APPEND INTO TABLE m_sys.m_oii_import_data WHEN (1:2) <> '--' TRAILING NULLCOLS ( rec_type TERMINATED BY "|", f1 TERMINATED BY "|", f2 TERMINATED BY "|", f3 CHAR(2000) TERMINATED BY "|", f4 TERMINATED BY "|", f5 TERMINATED BY "|", f6 TERMINATED BY "|", f7 TERMINATED BY "|", f8 TERMINATED BY "|", f9 TERMINATED BY "|", f10 TERMINATED BY "|" ) -- End of SQL*Loader-Control-File oii500.ctl ----------

Appendix: SQL*Loader Control/Parameter File


Appendix: SQL*Loader Control/Parameter File

SQL*Loader Parameter File oii500.par bindsize=1000000

This file specifies the bind array size for SQL*Loader. You must not add any other SQL*Loader parameters to this file. It is absolutely necessary that the import take place using the conventional path method. You can, however, adjust the size of the bind array to another value that better suits your data volume.


A P P E N D I X D

The name of the script file is oii_log.sql. After the execution of an import job, the software will query the protocol table and spool the results out to a file. Formatting commands are suited for printout in DIN A4 landscape format or DIN A3 portrait format. You can alter any of the formatting commands, but you should not modify the script parameters.

REM ----------------------------------------------------------- REM SPMat REM ----------------------------------------------------------- REM REM File: OII_LOG.SQL REM OII Import Protocol for last import, REM will be called immediately after import REM main procedure has finished REM Author: PSchneider, UBH REM Created: 27-FEB-1998 REM Changed: 30-Jan-2001, NR, Exchanged copyright information REM ----------------------------------------------------------- REM REM REM Parameters for script call are: REM REM &1: oij_id m_oii_import_jobs.oij_id%TYPE -> NUMBER(12) REM &2: proj_id m_projects.proj_id%TYPE -> VARCHAR2(10) REM &3: Fully qualified name for spoolfile REM WHENEVER SQLERROR EXIT FAILURE WHENEVER OSERROR EXIT FAILURE SET TIMING OFF SET FEEDBACK OFF SET LINESIZE 500 SET TRIMSPOOL ON SET PAGESIZE 66 SET ARRAYSIZE 1 SET VERIFY OFF SPOOL &3 PROMPT PROMPT PROMPT ****************** PROMPT * * PROMPT * SPMat * PROMPT * * PROMPT ****************** PROMPT PROMPT Open Ident Interface - Import protocol PROMPT PROMPT Copyright (c) 2001, Intergraph CorporationPROMPT PROMPT

Appendix: Import Protocol Script


Appendix: Import Protocol Script PROMPT Call parameters: PROMPT PROMPT OII Job ID: &1 PROMPT Project: &2 PROMPT Spoolfile: &3 PROMPT PROMPT COLUMN err_line_number HEADING Line# FORMAT 9999999 COLUMN state HEADING ST FORMAT a2 COLUMN kind HEADING Kind FORMAT a12 COLUMN msg_text HEADING Text FORMAT a50 WORD_WRAPPED COLUMN rec_type HEADING Type FORMAT a11 COLUMN f1 HEADING F-1 FORMAT a20 TRUNCATED COLUMN f2 HEADING F-2 FORMAT a20 TRUNCATED COLUMN f3 HEADING F-3 FORMAT a20 TRUNCATED COLUMN f4 HEADING F-4 FORMAT a20 TRUNCATED SET TERMOUT OFF SELECT oije.err_line_number, oije.state, oije.kind, oije.msg_text, oid.rec_type, oid.f1, oid.f2, oid.f3, oid.f4 FROM m_oii_import_data oid, m_oii_import_job_errors oije WHERE oije.oij_id = &1 AND oije.proj_id = '&2' AND oije.oid_id = oid.oid_id (+) AND oije.proj_id = oid.proj_id (+) ORDER BY oije.oije_id; SET TERMOUT ON PROMPT PROMPT PROMPT OII Import protocol done. PROMPT SPOOL OFF EXIT


A P P E N D I X E

This script is called when the main export program has finished spooling the data out to a flat ASCII file.

REM --------------------------------------------------- REM SPMat REM --------------------------------------------------- REM REM File: OIE_510.SQL REM Spool script for Open Ident Interface - REM Online Export of Data. REM Will be called immediately after export REM main procedure has finished REM Author: PSchneider, UBH REM Created: 27-NOV-1998 REM Changed: 30-Jan-2001, NR, Reading version and REM copyright from database REM --------------------------------------------------- REM REM REM Parameters for script call are: REM REM &1: oiiej_id m_oii_import_jobs.oij_id%TYPE -> NUMBER(12) REM &2: Fully qualified name for spoolfile REM WHENEVER SQLERROR EXIT FAILURE WHENEVER OSERROR EXIT FAILURE SET TAB OFF SET ECHO OFF SET TIMING OFF SET FEEDBACK OFF SET LINESIZE 4320 SET TRIMSPOOL ON SET PAGESIZE 0 SET ARRAYSIZE 1 SET VERIFY OFF SPOOL &2 SELECT '--' || chr(10) || '-- ******************' || chr(10) || '-- * *' || chr(10) || '-- * SPMat ' || m_pck_install_infos.marian_version || ' *' || chr(10) || '-- * *' || chr(10) || '-- ******************' || chr(10) || '--' || chr(10) || '-- Open Ident Interface - Data Export File' || chr(10) || '--' || chr(10) || '-- ' || m_pck_install_infos.copyright_1 || chr(10) ||

Appendix: Export Script


Appendix: Export Script '--' || chr(10) || '--' || chr(10) || '-- Call parameters:' || chr(10) || '--' || chr(10) || '-- OIIE Job ID : ' || o.oiiej_id || chr(10) || '-- Job Code : ' || o.oiiej_code || chr(10) || '-- Project (PG) : ' || o.proj_id || chr(10) || '-- Query Cond (Idents) : ' || NVL(aqci.aqc_code, 'None') || chr(10) || '-- Query Cond (Assembly) : ' || NVL(aqca.aqc_code, 'None') || chr(10) || '-- Started on : ' || to_char(o.job_start_date, 'DD-MON-YYYY') || chr(10) || '-- Server side log file : ' || o.mar_logfile_name || chr(10) || '-- Spoolfile : &&2' || chr(10) || '--' || chr(10) || '-- -------------------------------------------------------' || chr(10) || '-- ---------------- Data Section starts ----------------' || chr(10) || '-- -------------------------------------------------------' || chr(10) || '--' FROM m_sys.m_adm_query_conds aqca, m_sys.m_adm_query_conds aqci, m_sys.m_oii_export_jobs o WHERE o.oiiej_id = &&1 AND o.aqc_id_idents = aqci.aqc_id (+) AND o.aqc_id_assemblies = aqca.aqc_id (+); SET TERMOUT OFF SELECT rec_type || '|' || f1 || '|' || REPLACE(REPLACE(f2, chr(10), ' '), chr(13), ' ') || '|' || REPLACE(REPLACE(f3, chr(10), ' '), chr(13), ' ') || '|' || f4 || '|' || f5 || '|' || f6 || '|' || f7 || '|' || f8 || '|' || f9 || '|' || f10 || '|' FROM m_sys.m_oii_export_data WHERE oiiej_id = &&1 ORDER BY oiied_id; SET TERMOUT ON DELETE FROM m_sys.m_oii_export_data WHERE oiiej_id = &&1; COMMIT WORK; SELECT '--' || chr(10) || '-- -------------------------------------------------------' || chr(10) || '-- ----------------- Data Section ends -----------------' || chr(10) ||


Appendix: Export Script '-- -------------------------------------------------------' || chr(10) || '--' || chr(10) || '--' || chr(10) || '--' || chr(10) || '-- OII Export done.' || chr(10) || '--' || chr(10) FROM dual; SPOOL OFF EXIT


Appendix: Export Script


A Adjusting the SQL*Loader Parameter File •

36 Appendix

Error Messages • 39 Export Script • 51 Import Protocol Script • 49 Setup and Configuration • 35 SQL*Loader Control/Parameter File • 47

Assembly Data • 28 Attributes • 15

C Commodity Codes • 15 Configuring SmartPlant Materials Settings •

36 Context of Import Execution • 11 Control File oii500.ctl • 47 Correcting Import Data and Starting Over •

27

D Data Export • 31 Data Import • 23 DBA Settings • 16 Defining an Import Job • 24 Dependencies on Other SmartPlant

Materials Modules • 34 Directories and Files • 35

E Erroneous Import Data • 27 Error Handling • 13 Error Messages in the Import Protocol • 43 Error Messages on S.80.11 • 39 Error Messages on S.80.14 • 41 Exclusive Object Locks • 34 Extracting the Data from the 3rd Party or

Legacy System • 23

F Features and Functionality • 11 File Format • 16 File Format Example • 20 File Placement • 23, 36

File Transfer into the Interface Table • 25

G General Messages • 43 Geometrics • 15

I IDENT • 17, 19 Ident Attributes • 12 Ident Descriptions • 12 Ident Structures • 12 IDENT_ATTR • 18, 20 IDENT_NLS • 18, 19 IDENT_STRUC • 18, 20 Idents • 11 Idents and Ident Values • 27 Implementation • 33 Import Main Program • 25 Import Protocol • 13 Imported Data • 11 Instance Configuration Tasks • 35 Introduction • 9

J Job Execution • 12

L Log File Creation • 25

M Messages Related to IDENT Records • 44 Messages Related to IDENT_ATTR

Records • 45 Messages Related to IDENT_NLS records •

45 Messages Related to IDENT_STRUC

Records • 45 Messages Related to Missing or Invalid

Data • 44 Messages Related to SQL*Loader Import •

46

N NLS • 15

Index


Index O OII Export • 36 OII Import • 37

P Preface • 7 Prerequisites • 15

R Record Structure • 19 Reference Data • 11 Required Data in the SmartPlant Materials

Database • 15 Reviewing the Export File • 32 Reviewing the Logfile • 26

S Setting Up Where Conditions • 31 SmartPlant Materials Tables • 33 SQL*Loader Parameter File oii500.par • 48 Starting Job Execution • 25, 32 Stored PL/SQL Program Units • 33 Supported Record Types and Their

Processing Rules • 17

T Transaction Control • 33

U Unit Conversion Rules • 16 Units • 16

V Viewing and Modifying Imported Data • 27


SmartPlant Materials Open Ident Interface (OII)

Documents

Transcript of SmartPlant Materials Open Ident Interface (OII)