Database design guide - Siemens

� �Database design guide

___________________

___________________

___________________

___________________

___________________

___________________

___________________

___________________

___________________

___________________

___________________

___________________

___________________

COMOS

Platform Database design guide

Operating Manual

04/2012 A5E03777241-01

Trademarks

1

Introduction

2

Rules and recommendations

3

Attributes and tabs

4

Standard tables

5

Base objects

6

User-specific classification key

7

External files

8

Documents

9

Symbols

10

Icons

11

Scripts and source code generation

12

Project-wide and database-wide options

13

Legal information

Legal information Warning notice system

This manual contains notices you have to observe in order to ensure your personal safety, as well as to prevent damage to property. The notices referring to your personal safety are highlighted in the manual by a safety alert symbol, notices referring only to property damage have no safety alert symbol. These notices shown below are graded according to the degree of danger.

DANGER indicates that death or severe personal injury will result if proper precautions are not taken.

WARNING indicates that death or severe personal injury may result if proper precautions are not taken.

CAUTION with a safety alert symbol, indicates that minor personal injury can result if proper precautions are not taken.

CAUTION without a safety alert symbol, indicates that property damage can result if proper precautions are not taken.

NOTICE indicates that an unintended result or situation can occur if the relevant information is not taken into account.

If more than one degree of danger is present, the warning notice representing the highest degree of danger will be used. A notice warning of injury to persons with a safety alert symbol may also include a warning relating to property damage.

Qualified Personnel The product/system described in this documentation may be operated only by personnel qualified for the specific task in accordance with the relevant documentation, in particular its warning notices and safety instructions. Qualified personnel are those who, based on their training and experience, are capable of identifying risks and avoiding potential hazards when working with these products/systems.

Proper use of Siemens products Note the following:

WARNING Siemens products may only be used for the applications described in the catalog and in the relevant technical documentation. If products and components from other manufacturers are used, these must be recommended or approved by Siemens. Proper transport, storage, installation, assembly, commissioning, operation and maintenance are required to ensure that the products operate safely and without any problems. The permissible ambient conditions must be complied with. The information in the relevant documentation must be observed.

Trademarks All names identified by ® are registered trademarks of Siemens AG. The remaining trademarks in this publication may be trademarks whose use by third parties for their own purposes could violate the rights of the owner.

Disclaimer of Liability We have reviewed the contents of this publication to ensure consistency with the hardware and software described. Since variance cannot be precluded entirely, we cannot guarantee full consistency. However, the information in this publication is reviewed regularly and any necessary corrections are included in subsequent editions.

Siemens AG Industry Sector Postfach 48 48 90026 NÜRNBERG GERMANY

A5E03777241-01 Ⓟ 05/2012 Technical data subject to change

Copyright © Siemens AG 2012. All rights reserved

Database design guide Operating Manual, 04/2012, A5E03777241-01 3

Table of contents

1 Trademarks ............................................................................................................................................... 7

2 Introduction................................................................................................................................................ 9

3 Rules and recommendations ................................................................................................................... 11

3.1 Working layers .............................................................................................................................11

3.2 Designation and language ...........................................................................................................11 3.2.1 Texts in several languages ..........................................................................................................11 3.2.2 Object names...............................................................................................................................12 3.2.3 Capitalization................................................................................................................................12 3.2.4 Texts with hyphens and other special characters........................................................................12

4 Attributes and tabs................................................................................................................................... 13

4.1 Attributes catalog .........................................................................................................................13

4.2 Attribute library.............................................................................................................................14 4.2.1 Naming conventions ....................................................................................................................14 4.2.2 Design ..........................................................................................................................................15

4.3 Tabs .............................................................................................................................................16 4.3.1 Tab library ....................................................................................................................................16 4.3.2 Name convention .........................................................................................................................16 4.3.3 Specific tabs.................................................................................................................................16 4.3.3.1 Setting up a tab............................................................................................................................17 4.3.3.2 Placing attributes .........................................................................................................................18 4.3.3.3 Frames and labels .......................................................................................................................18 4.3.3.4 Attributes and tab variants ...........................................................................................................18 4.3.3.5 Changing the attributes on tabs...................................................................................................19 4.3.3.6 Design ..........................................................................................................................................19

5 Standard tables ....................................................................................................................................... 23

5.1 Creation structure ........................................................................................................................23

5.2 Standard tables for specific attributes..........................................................................................23

5.3 Several standard table variants for one attribute .........................................................................24

5.4 General standard tables...............................................................................................................24

5.5 Standard tables design ................................................................................................................25

Table of contents

Database design guide 4 Operating Manual, 04/2012, A5E03777241-01

6 Base objects ............................................................................................................................................ 27

6.1 Design and structure ................................................................................................................... 27 6.1.1 "@01 Material" node ................................................................................................................... 27 6.1.2 "@02 General objects" node....................................................................................................... 29 6.1.3 "@03 Structures" node................................................................................................................ 29

6.2 Creation option............................................................................................................................ 31

6.3 Name convention ........................................................................................................................ 31

6.4 Adding tabs to objects................................................................................................................. 31

6.5 Adding elements ......................................................................................................................... 32

6.6 Norm-specific text masks............................................................................................................ 32 6.6.1 Input in norm-specific text masks................................................................................................ 33 6.6.2 The correct default value............................................................................................................. 34

7 User-specific classification key ................................................................................................................ 35

8 External files ............................................................................................................................................ 37

9 Documents .............................................................................................................................................. 39

9.1 General........................................................................................................................................ 39

9.2 Setting the external file name during runtime ............................................................................. 39

9.3 Setting the file name "@NO@"................................................................................................... 39

9.4 Referencing report files ............................................................................................................... 40

9.5 Object path for report templates ................................................................................................. 40

9.6 File names and paths.................................................................................................................. 41

9.7 Company logos ........................................................................................................................... 41

9.8 Design ......................................................................................................................................... 42 9.8.1 Sub reports.................................................................................................................................. 42 9.8.2 Text fields.................................................................................................................................... 42 9.8.3 Queries belonging to reports....................................................................................................... 43

10 Symbols................................................................................................................................................... 45

11 Icons........................................................................................................................................................ 47

11.1 Icon size ...................................................................................................................................... 47

11.2 Transparency .............................................................................................................................. 47

Table of contents


12 Scripts and source code generation ........................................................................................................ 49

12.1 Storing location ............................................................................................................................49 12.1.1 Calling central scripts...................................................................................................................49 12.1.2 Central scripts and parameters....................................................................................................50

12.2 Structure and conventions ...........................................................................................................50 12.2.1 Function and procedure designations..........................................................................................51 12.2.2 Layout and style...........................................................................................................................51 12.2.2.1 Row length and breaks ................................................................................................................51 12.2.2.2 Indenting codes............................................................................................................................52 12.2.2.3 Space ...........................................................................................................................................53 12.2.3 Variable names ............................................................................................................................53 12.2.3.1 Variable types ..............................................................................................................................54 12.2.3.2 Other properties ...........................................................................................................................54 12.2.3.3 Object types .................................................................................................................................55 12.2.4 Comments....................................................................................................................................55 12.2.4.1 Procedures and function headers................................................................................................55 12.2.4.2 Scripts ..........................................................................................................................................56

12.3 Avoiding runtime errors................................................................................................................56

12.4 Texts in scripts .............................................................................................................................56 12.4.1 Source code.................................................................................................................................57 12.4.2 Creating the texts.........................................................................................................................57 12.4.3 Examples .....................................................................................................................................58 12.4.3.1 Creating a standard table.............................................................................................................58 12.4.3.2 Translating entries .......................................................................................................................58 12.4.3.3 Scripts ..........................................................................................................................................59

13 Project-wide and database-wide options ................................................................................................. 61

13.1 Creating project-wide and database-wide options.......................................................................61

13.2 Setting the scope .........................................................................................................................61

13.3 Setting options .............................................................................................................................62

Table of contents



Trademarks 1Trademarks

Registered trademark: COMOS®

Trademarks



Introduction 2About this document

This document contains guidelines and recommendations for creating COMOS objects for the purpose of updating and adapting your database.

So that users can easily use, change, and add to the database, please follow the guidelines as closely as possible.

See also Rules and recommendations (Page 11)

Introduction



Rules and recommendations 33.1 Working layers

Guideline Do not work in the released area. Depending on the project and database, the released area may be blocked.

Work in working layers which are released, imported, exported, and deleted in accordance with the guidelines of the relevant database or project.

Recommendation Back up and archive your own working layer.

3.2 Designation and language

Recommendation for texts Ensure that all objects, attributes, reports and other COMOS-related elements feature texts in the languages used. One example of such a text is the description.

Ensure that you enter the texts in the correct positions. For example, there should be no German text in an English-language field.

3.2.1 Texts in several languages

Single and bulk translation To enter texts in several languages, use single or bulk translation. You can find the single and bulk translation function in the "Extra > Translation" menu.

Note Changing texts

To change a text, always use the translation tools. Do this even if you only change the text in one language. Otherwise, COMOS adds "?0?" to the start of the text in other languages to mark a possible inconsistency.

Rules and recommendations 3.2 Designation and language


3.2.2 Object names

Language-neutral names Object names may not contain any language-dependent information since they cannot be translated. Always choose a language-neutral name for objects. Write relevant information in the descriptions. Language-neutral names generally consist of sequential alphanumeric characters.

This also applies to attributes, documents, etc.

3.2.3 Capitalization

Spelling recommendation For all texts, including object and attribute descriptions, use capitalization in accordance with the spelling rules for the relevant language. Capitalize proper nouns.

3.2.4 Texts with hyphens and other special characters

Recommendation If a text contains a hyphen "-" or another special character, separate this special character from the rest of the text using blanks.

Exception: A standardized term, which must not include a blank.

Example 1 "EN 1092-1" must not contain a blank because the standard is called EN 1092-1.

Example 2 "T1 - flange" must contain blanks.


Attributes and tabs 4

General To avoid clashes between names in the case of attributes and tabs, do not save newly created attributes and tabs in the relevant working layer. Create these in a separate working layer and release this working layer immediately.

You can treat attribute changes like other objects.

4.1 Attributes catalog

Overview You can find the attributes catalog for all COMOS objects in the "@10 @Y Attributes catalog" node. The secondary nodes are for the various projects.

You can create further layers for logical groups. Create the nodes as a "structure". In the COMOSDB, the name for these groups consists of a three-letter abbreviation. The description shows you the entire project names and group names.

Structure of projects or groups Underneath the projects or groups in the COMOSDB, you will find three or more base objects:

● "0 @Y Attribute collection"

● "1 @Y Tab collection"

● "2 <...> <specific tabs>"

Example

Attributes and tabs 4.2 Attribute library


4.2 Attribute library

Attributes All names used in the project or logical group are created in the attribute library. Each physical characteristic has its own attribute. Examples of physical characteristics are temperature and outer diameter.

In the COMOSDB, the attributes are not located directly under the attribute library, but are instead placed in groups of 50 attributes on tabs. The names of the tabs consist of the project abbreviation followed by "C" and a two-digit consecutive number.

Example MTOC01

Description In the COMOSDB, you see the description "Attribute 1 - 50".

See also Naming conventions (Page 14)

4.2.1 Naming conventions

COMOSDB In the COMOSDB, attributes are named according to the following rules:

● Project name/group name (three-letter abbreviation)

● Four-digit consecutive number

Example: MTO0001, MTO0002

The attribute description contains a text with a suitable characterization. In this example, the following general attribute settings are defined:

● Type of display

● Standard table

● Unit

● Type of edit field

Attributes and tabs 4.2 Attribute library


Example

4.2.2 Design

Recommendation for arranging the attributes Although the attribute library is not to be regarded in the same way as tabs, an arrangement of the attributes in blocks of five, with five blocks on the left and five blocks on the right in each case, is recommended.

Example

Attributes and tabs 4.3 Tabs


4.3 Tabs

4.3.1 Tab library In the tab library, you create all of the required tabs with names and descriptions. First of all, create the tabs empty and without attributes.

See also Name convention (Page 16)

4.3.2 Name convention

COMOSDB In the COMOSDB, tabs are named according to the following rules:

● Project name/group name (three-letter abbreviation)

● Three-digit number, usually in units of ten

Example: MTO010, MTO020

The description of the tabs contains a text with a suitable characterization.

Example

4.3.3 Specific tabs

General You can place attributes on specific tabs as required. You can create several nodes for the purpose of grouping the tabs. However, you can also set up a single "2 tabs" node. If you use several groups, you can name them with a consecutive number or use descriptive letters.

Example D for device



Several versions of a tab Each tab is created in its own object, whose name and description are identical to those of the tab. If you require more than one version of the tab, you can create a secondary object for each variant.

Example

4.3.3.1 Setting up a tab You set up the tab below the general object for this tab.

Procedure To set up the tab, proceed as follows:

1. Open the properties of the object.

2. Click the "Attributes" tab.

3. Right-click in the working area.

4. Select the "Design mode" command from the context menu.

5. Drag&drop the tab from the tab library into the design area.

This ensures that objects are inherited correctly.

Important: Do not change the name of the tab.

See also Tab library (Page 16)



4.3.3.2 Placing attributes

Procedure To place attributes, proceed as follows:

1. Open the tab object properties.


3. Optional: If necessary, select the required tab.

4. Change to design mode.

5. Drag&drop all of the required attributes from the attribute library into the design area.

This ensures that objects are inherited correctly.

Do not change the names of the attributes. The only exception concerns the usage of a suffix, for example, "MTO0051a", if you use the attribute more than once on the same tab.

See also Attribute library (Page 14)

4.3.3.3 Frames and labels Unlike attributes containing real data, you can place frames and labels directly on the tab. Such attributes do not have to be set up in the attribute library and inherited on the tabs.

COMOSDB In the COMOSDB, the names of frames and labels consist of "FRM" or "DES" and a four-digit consecutive number.

Example FRM001, DES002

4.3.3.4 Attributes and tab variants

Applications Place attributes which are required in all variants of this tab directly in the main object for this tab. The main object for the tab has the same name and description as the tab.

Place attributes which are only supposed to appear in certain variants in the object of the relevant variant.

To change the design of attributes which have been inherited from a primary object, right-click in the design area in design mode and select the "All attributes > In design mode" command from the context menu.



4.3.3.5 Changing the attributes on tabs

Recommendation You can change the following attribute properties on a tab:

● Description

● Reference

● Scripts

● Design

● Specific unit, for example, °C or °F for temperature

Do not define scripts and references before this point since the attribute context has only now been established.

You must not change the following properties on a tab:

● Standard table

Do not change the following properties on a tab:

● Name

You can change the suffix of a name.

● Unit system

Examples: Do not change temperature into length or one system of length units into another.

4.3.3.6 Design

Configuration recommendations When creating tabs, ensure that the configuration used throughout the entire database or project is uniform and correct:

● Combine attributes that belong together to form blocks. Separate the blocks using frames.

● Ensure that all attributes, or at least all attributes in a column, have the same description length. The description length should be long enough to accommodate all languages used.

● Ensure that all units on a tab have the same length and that all usable units fit in it.

● Allow sufficient space for attribute values.

● Ensure that the size and horizontal position of the attributes in a column are identical.

● Ensure that the gap between the attributes and frames is the same.



● Ensure that tabs are not too large to fit on the screen properly. For the purpose of carrying out the check, ensure that COMOS is running in full-screen mode with a resolution of 1280 x 1024 and that the Navigator is large enough for the "Units", "Locations", "Documents", and "Base objects" tab labels to be accommodated on the tabs.

● If an attribute is tasked with special script actions, change the description text of the attribute to blue and add help and tooltip texts to it. Example of such an attribute: The attribute changes other attribute values, the name of the attribute owner, the description, the label, etc.

● Ensure that all attributes have a description. This also applies to control elements such as options or buttons. You can use a single description attribute to describe several grouped attributes. Example: A single description "Diameter inner/outer" for the "Inner diameter" and "Outer diameter" attributes.



Example You can find the following example in the COMOSDB in the base project under the "@10 > BAS > 2 @Y General tabs" node.

① Uniform alignment of the attributes ② Attribute that performs a special action ③ Uniform description length ④ Uniform length of the units with sufficient space for the usable units ⑤ Uniform length of the attributes ⑥ Frame for attributes that belong together ⑦ Group with options and an individual description ⑧ Tab fits on the screen in full-screen mode



Example of gaps


Standard tables 5

Access To access the standard tables, click the "Administrator > Base data > Standard tables" menu.

5.1 Creation structure The structure for creating standard tables depends on the location and the way in which they are used.

See also Standard tables for specific attributes (Page 23)

Several standard table variants for one attribute (Page 24)

General standard tables (Page 24)

5.2 Standard tables for specific attributes

COMOSDB You can find standard tables for specific attributes in the standard table node "@10 Attributes catalog". Under this node, you can set up a node for your own particular project and maybe your own logical group. Below it, you create standard tables for each attribute requiring a standard table.

Recommendation Ensure that the standard tables have the same name and the same description as the attributes.

Standard tables 5.3 Several standard table variants for one attribute


5.3 Several standard table variants for one attribute If several versions are required for the standard tables of an attribute, set these up underneath the attribute node.

Recommendation Choose suitable names and descriptions for these tables by basing them on the corresponding tabs on which they appear, for example.

Only create variants of standard tables in exceptional cases.

5.4 General standard tables Set up specific nodes for all other standard tables, such as the frequently used general "Yes/no" tables, under the standard tables root node.

Example The following example shows a general standard table in the COMOSDB:

Standard tables 5.5 Standard tables design


5.5 Standard tables design

Configuration recommendations Column Description "Name" Assign a combination of one or more letters and a consecutive number in

units of ten. This enables you to add standard tables later without having to rename all the others. When naming the entries, ensure that the table is sorted by name.

"Description" The description contains the text which appears in the selection. Consider all languages required.

"Value 1" The value in this column corresponds to the Value of the attribute as opposed to its DisplayValue. The value must be unique and contain the correct numerical value when used in calculations.

Standard tables 5.5 Standard tables design



Base objects 66.1 Design and structure

Library In the COMOSDB, there is a library of general base objects, which are not dependent on norms.

Recommendation Rather than creating project-specific base objects from scratch, derive them from the general base objects.

In the COMOSDB, not all existing structures follow these guidelines.

See also "@01 Material" node (Page 27)

"@02 General objects" node (Page 29)

"@03 Structures" node (Page 29)

6.1.1 "@01 Material" node

Components that can be ordered The "@01 Material" node contains objects for actual components that can be ordered, such as devices and accessories. In addition, the node contains logical objects assigned to the relevant device, for example, pipe branches assigned to pipes.



The node is not dependent on norms. This means that no norm-specific structures exist. Objects are sorted by module and object type and not linked with other objects.



6.1.2 "@02 General objects" node

Logical objects The "@02 General objects" node contains base objects for logical objects such as units, functions, queries, etc. This node does not contain a norm-specific structure. Each general object type has its own node under the "@02 General objects" node. In turn, these secondary nodes also have nodes that are subordinate to them.

6.1.3 "@03 Structures" node

Norm-specific structures The "@03 Structures" node contains the norm-specific structures, if they are used in engineering objects. While the "@01 Material" and "@02 General objects" nodes contain the definitions of the base objects themselves, the "@03 Structures" node defines the relations between these objects as specified in the various norms.

To create these structures, specify the required secondary objects as elements of the main object so that the user can create the secondary objects via the context menu.

Ensure that the connections in the "@03 Structures" node are defined. This is why it is necessary for objects from the "@01 Material" and "@02 General objects" nodes to be inherited in the "@03 Structures" node and to create the structures with these inherited objects.



Example The following example from the COMOSDB illustrates the connections.

Base objects 6.2 Creation option


6.2 Creation option You can find the creation option in the object properties in the "Creation option" control group of the "System" tab.

"Structure" option Enable the "Structure" creation option for hierarchical objects. Hierarchical objects are used as folders for secondary objects.

"Normal" option Enable the "Normal" creation option for base objects that are used as a base for engineering objects.

6.3 Name convention

Recommendation Name objects of the same type uniformly, for example, using a consecutive number (01, 02, 03, etc.) or capital letters (A, B, C, etc.). To get a feel for suitable designations, use the COMOSDB as a guide.

6.4 Adding tabs to objects

Procedure To add tabs to a base object, proceed as follows:

1. Open the properties of a base object.


3. Right-click in the working area of the "Attributes" tab.

4. Select the "Design mode" command from the context menu.

5. Drag&drop the tab from the specific tab library in the "@10" node into the design area.

Do not change the tab on the object. Instead, define and configure the tab in the tab library in the "@10" node.

See also Tab library (Page 16)

Base objects 6.5 Adding elements


6.5 Adding elements

Procedure To adapt the context menu of an engineering object, proceed as follows:

1. Open the properties of the required base object.

2. Click on the "Elements" tab.

3. Drag&drop the desired object from the Navigator into the "Elements" tab.

Result The object is created as an element of the other object.

Recommendation Set the entry in the "Dereference" column to "Yes".

Do not modify the element. Instead, specify the desired settings on the original object.

Exception: You can change the name of the element in the list of elements.

6.6 Norm-specific text masks This function enables you to use different text masks for object names and object labels according to the norm.

See also Input in norm-specific text masks (Page 33)

Base objects 6.6 Norm-specific text masks


6.6.1 Input in norm-specific text masks

Default values In the properties of an object, you can find the "..." button behind the fields. When you click on this button, the "Norm-dependent text masks" window opens. In this window, you can enter text masks and standard values for the following information:

● Default values

● Several default norms

● Company-specific entries

● User-defined entries

If no entry is available for the norm that is currently being used, the default value is used.

In the "Norm-dependent text masks" window, you can see the "i" button next to the individual fields. The rules for making entries in these text masks are specified here.

Example

See also The correct default value (Page 34)

Base objects 6.6 Norm-specific text masks


6.6.2 The correct default value

Neutral entry If the norm-specific entry for the currently selected norm is empty, the default value is used. For this reason, ensure that the entry for the default value is neutral and can be used universally.


User-specific classification key 7General

Classification keys are used to classify objects for a fast search. You can find the classification keys in the base project under the following path:

"@System > @D > @ClassificationKeys classification keys"

The "ZZ" classification key under the "@KeyCode1 classification key 1, structural" node is reserved for user-specific classifications.

User-specific classification key



External files 8Definition

Some types of files used in COMOS are known as external files. Like other files, they are saved in the document directory of the database, but all relevant information remains in the file. The most important difference compared with other files is that these files are not considered by working layers. This means that if you change such a file, you implement the change immediately in the file itself. This also applies if you make the change via COMOS. The changes apply to the entire database, even if you have opened the file from within a working layer. In addition, these files are not included in the export when a working layer is exported.

You edit external files using separate programs. Report templates, which are external files and yet are changed via COMOS, are an exception to this rule.

The most frequently used types of external files are:

● COMOS report templates (.CRp)

Note

Reports also save data in CRp files. These are managed by COMOS and are relevant to the working layers.

● Image files (.BMP .JPG, etc.)

● Icons (.ICO)

● Microsoft Office files (.DOC, .XLS, etc.)

External files



Documents 99.1 General

Reports Reports consist of a report object in COMOS and an external CRp file.

See also External files (Page 37)

9.2 Setting the external file name during runtime

File name "@NO@" In some cases, the external file for a report is only introduced during runtime and only comes into existence when a user opens the report for the first time. In such cases, set the file name to "@NO@". If the name is not "@NO@", an error message occurs during the object test.

See also Setting the file name "@NO@" (Page 39)

9.3 Setting the file name "@NO@"

Procedure To set the file name "@NO@", proceed as follows:

1. Open the object debugger.

2. Drag&drop the report from the Navigator into the "Object A" field.

3. Execute the following script:

a.FileName = "@NO@"

Documents 9.4 Referencing report files


9.4 Referencing report files

Rule Each CRp file used must be referenced with a document object. This rule is valid for:

● Main documents

● Master reports

● Sub reports

● Header and row reports in the case of lists

Need for referencing Although the secondary elements of the project structure are visible, they must be referenced for the following reasons:

● Database synchronization only detects referenced objects

● The translation tools only detect referenced objects

● The Synchronize project folder function otherwise displays the data as not referenced. This results in the data being deleted

Reports are only translated by the translation tools if they are referenced.

Referencing To reference report files, create the references in a node under the main file node. Ensure that the fact it is a sub report of the superior node can be identified from the name and description of the sub node.

Example Sub reports for the "Reports > DAT data sheets" node are created in the secondary node "Reports > DAT > Sub reports data sheets".

9.5 Object path for report templates

"Documents" tab In the COMOSDB, you can find all report templates in the base project on the "Documents" tab under the "CRp report templates > @0" node. This is located under a secondary path corresponding to the document name.

Example You can find the data sheet with the name "PDA.007" under the following path:

"CRp > @0 > PD > PDA > PDA.007"

Documents 9.6 File names and paths


9.6 File names and paths

Rule The CRp files for report templates must have the same name as the report templates. In addition, the folders in the path must correspond to the object structure in COMOS.

Example The "CRp > @0 > PD > PDA > PDA.007 data sheet" report template must be saved under the following path in the document directory:

"SO1\CRp\PD\PDA\PDA.007.CRp"

9.7 Company logos

"Project data" tab All company logos used in a report must contain a reference to the logo settings in the projects settings. You can find the "Company logo" and "Customer logo" fields on the "Project data" tab in the project properties. Here you can specify paths to logo image files.

● "Company logo" field: Enter the company logo of the company implementing the project here.

● "Customer logo" field: Enter the company logo of the company for which the project is being implemented here.

If you do not need to make a distinction between the company logo and customer logo, specify the same logo for both fields.

Referencing logos in scripts You can obtain the file names for these logo files via Project.GetDocumentDirectory + "\" + Project.Spec(ATT_NAME).DisplayValue.

Here, ATT_Name is "COM01.COM0004" for the company logo and "COM01.COM0010" for the customer logo.

Documents 9.8 Design


9.8 Design

9.8.1 Sub reports

Common elements If several reports have an element in common, create sub reports for these elements. This offers the advantage of not having to create and maintain these report sections separately for each report; instead, you only have to do this once.

Example: Reports with a common element Technical attributes contain various device information according to the device type. However, some device information, position data, and function data can be the same for all device types.

9.8.2 Text fields

Recommendation Ensure that the text fields are large enough to accommodate the values and texts entered in each language used. Similarly, the fields for the descriptions should offer sufficient space for the descriptions. In the case of very long attribute descriptions, you can use a short text. A short text is a fixed text which does not use an attribute description.

Ensure that all fields have a uniform font, font size, and style. For the sake of uniformity, it is also beneficial if the fields all have the same text alignment and an identical display mode.



9.8.3 Queries belonging to reports

Query inheritance If a report is to contain a list, for example, you must create the query under a report. Pay attention to the following when creating the query:

● Create the query at the correct location for queries on the "Base objects" tab.

● Then create another query that inherits from the one you have just created under the report.

Recommendation Name the queries under the reports "Q1", "Q2", etc.

When making a change to the query, be aware that you must first change the base object from which the inheritance is derived. To apply the changes, you then open the query under the report once and save the report.




Symbols 10White areas and AutoCAD export

If a symbol in the COMOSDB contains white areas or filled hatching, pure white is not used. Pure white has red, green, and blue values, each of which are equal to 255. Pure white is not used because AutoCad interprets it as being transparent.

Recommendation Use a somewhat tinted white, for example, with a red, green, and blue value of 250.

Symbols



Icons 1111.1 Icon size

Supported size COMOS only supports icons with a size of 16x16 pixels. Icons in any other size are not displayed correctly.

11.2 Transparency

Transparent color COMOS automatically uses the color of the pixel in the bottom left corner as a transparent color. The pixel is only ever not used as a transparent color if it is black. Even if you have created the icon with an image editing program that supports transparency, the color of the pixel in the bottom left corner is still used. Therefore, ensure that the pixel is in the color that is to be used as the transparent color.

All pixels which have the same color as that in the bottom left corner are displayed as transparent in COMOS.

Icons 11.2 Transparency



Scripts and source code generation 1212.1 Storing location

Saving scripts Save the scripts that are being used in several positions in a central location. COMOS then simply calls the scripts again in the relevant positions.

Scripts are located under the following node in the COMOSDB:

"@02 > 200 Queries, scripts, imports, decision tables, eBlocks"

Under this node, you will find various nodes for the areas, for example, "PID pipe and instrumentation". Under the areas node, you will find the "S script library" node for each area. For further subdivisions, consult the existing structures.

Each script that is to be called from another position has its own object and is located in "UserScriptBlock1". In the COMOSDB, the object name is a two-digit consecutive number. The description corresponds to the name of the script.

Example

12.1.1 Calling central scripts

Function To call the function within a function located at any given position in COMOS, insert another function for calling up the central function in the function script block: Function/Sub <FunctionName>(<(ParamList)>) <(Set)> <FunctionName> = Project.Workset.Lib.CallScriptLib ("<FunctionPath>", "<FunctionName>", <(ParamList)>) End Function/Sub

Scripts and source code generation 12.2 Structure and conventions


Parameters The following table describes the individual parameters:

Parameters Description Function/Sub This parameter depends on whether it is a case of Function or Sub:

• Function: Function which returns a value • Sub: Function which does not return a value

<FunctionName> Function name <(ParamList)> Optional: Parameter list. Individual parameters are separated by

commas. <(Set)> Set is only required when the function returns an object. <FunctionPath> Object path in which the function is saved.

Example Calling the NLS text, see also section titled Source code (Page 57).

12.1.2 Central scripts and parameters In the declaration, all central scripts must feature exactly one parameter, known as Param. This is a field which contains all parameters transferred in the call.

Assign local variables to these parameters before using them.

Example Function PathAbs2Rel (Param) 'Turns absolute path into path relative to DocumentPath strAbsolutePath = Param(1) strReferencePath = Param(2) .... End Function

12.2 Structure and conventions To improve the ease with which the text can be read and hence understood, ensure that you structure source codes effectively.



12.2.1 Function and procedure designations Ensure that the names of procedures and functions are meaningful. This offers the advantage of enabling the user to deduce the purpose from the name.

COMOSDB In the COMOSDB, the names of procedures do not have blanks or special characters such as "_". Names of procedures begin with a verb written entirely in lower case. Other words in the name can begin with a capital letter.

Example "closeDialog", "searchPositionsBelowUnit"

12.2.2 Layout and style

12.2.2.1 Row length and breaks Ensure that rows are not so long that they require a horizontal scroll bar. Up to 80 characters are therefore possible.

Recommendation for breaks If a row is too long, insert breaks in accordance with the following recommendations:

● Break after a comma

For example, in the case of parameter lists

● Break after operator

● Position the text in the new row in such a way that similar code positions in both rows are at the same height.

Separate commands that are stretched out over several rows by using a blank and an underscore so that the command continues in the next row. With VBScript, commands are separated using blanks and not using a special character such as ";".



Example

① Alignment ② Break after parameters ③ Alignment ④ Break after operators

12.2.2.2 Indenting codes

Recommendation Indent code blocks:

● Contents of functions

● Loops

● if.then.else operations

● etc.

This enables the reader to see which sections of the code belong to which control structures. Position the comments according to the code being commented upon.

Example



12.2.2.3 Space Blanks enable you to enhance readability. Structure the source code in a meaningful way. Accommodate the individual conditions that form part of complex conditions in individual rows.

Recommendation Use blanks in the following cases:

● Between a key word and the left bracket associated with it

– if

– select

– while

– etc.

● Between the right bracket and the subsequent key word

● Before and after a binary operator

Do not use blanks in the following cases:

● Between a procedure name and the subsequent left bracket for the arguments

● After a left bracket and before a right bracket

Examples a = b + c if (a < 10) then exit sub Function getObject(strParam1, strParam2, strParam3)

12.2.3 Variable names

Recommendation Use meaningful variable names so that the reader can recognize the purpose for which the variable is being used. Enter the names in English. Ensure that all abbreviations used remain uniform throughout the entire script, as is the case with procedures.

Use prefixes to designate the variable type and other variable properties. For single counter variables, such as a For loop, a single intI will also suffice.



12.2.3.1 Variable types

Prefixes The following prefixes designate the variable types:

Type Prefix Example Boolean bln blnFound Byte byt bytRasterData Date (Time) dtm dtmStart Double dbl dblTolerance Error err errOrderNum Integer int intQuantity Long lng lngDistance Single sng sngAverage String str strFirstName Object obj objCurrent

12.2.3.2 Other properties

Prefixes The following prefixes are used for other variable properties. Use them in addition to the prefixes, if possible.

Type Prefix Example Array arr arrStrNames

Collection col colObjCars

Constant const constIntDefaultValue

Script-wide scope s sStrFileName

Variables with script-wide scope are declared outside a procedure/function and available throughout the entire script block.



12.2.3.3 Object types

Prefixes The following prefixes designate object types. You can also use them in the context of obj.

Object type Description Prefix Example CDevice Base object cDev objCDevPump

CDocument Document template cDoc objCDocPID

Connector Connection con objConSLI

Device Device dev objDevCurrent

Document Document doc objDocPID

Attribute Attribute Att objAttTemperature

12.2.4 Comments

Recommendation Use comments to document scripts effectively. Make sure that the comments are informative.

12.2.4.1 Procedures and function headers

Recommendation Begin all procedures and functions with a short header block. The header block contains the purpose of the procedure as well as input and output parameters. A change history is also helpful for documenting the development of the procedure. Insert the header block directly below the first row of the function.

Example Sub searchStringInScripts(objStartItem, strSearchStrings(), intErrorCode) ‘Searches for the provided search strings in all objects below the start item ‘Input: objStartItem: The item where the search is initiated ‘ strSearchStrings(): Array of all search strings ‘ intErrorCode: The error code to be used for the output ‘Output: Finds are output to Comos object test. [code block] End Sub

Scripts and source code generation 12.3 Avoiding runtime errors


12.2.4.2 Scripts

Sequence and sub steps Comment on the general sequence of the procedure. Also comment on larger sub steps of the function just as with particularly complex sections.

12.3 Avoiding runtime errors

Procedure If you wish to access the properties of an object, check beforehand whether the object exists.

Example Set objAttTemperature = objDevThermometer.spec("BAS01.BAS0014") If objAttTemperature Is Nothing Then Exit Sub intTemperature = objAttTemperature.value

12.4 Texts in scripts If messages generated from scripts are to be multilingual, use the NLS system to make this effective.

See also Source code (Page 57)

Creating the texts (Page 57)

Scripts and source code generation 12.4 Texts in scripts


12.4.1 Source code

Call An NLS text is called with the NLS_Text function. The call can be seen in the following: NLS_Text("<ERROR_NAME>")

For example, use the following code for a message box: msgbox NLS_Text("<ERROR_NAME>"),, NLS_Text("<ERROR_HEADER_NAME>")

To make the function generally known, use the following further functions under the current function: Function NLS_Text(strNLSText) NLS_Text = Project.Workset.Lib.CallScriptLib ("@02|200|EIC|S|COM|01", "NLSText", "<PATH>" & strNLSText) End Function

Parameters Parameters Description <ERROR_Name> Name of the message text to be addressed <ERROR_HEADER_NAME> Special case for message boxes: The text of the message box

header is called here. <PATH> Path under which the list of NLS texts to be used is located.

This path is underneath the "@10" node in the standard tables. If you specify "TST|COM_NLS" as a path, the texts in the "@10 > TST > COM_NLS" standard table are searched for. Note: Close the path by selecting the "|" symbol.

12.4.2 Creating the texts

Standard table You manage the texts in a standard table. This standard table is always located under "@10". Create the individual texts here as standard table entries.

The "Name" and "Value 1" columns contain the name which you use to call the text in the script. Enter the text to be displayed into the description.

Recommendation Ensure that you create the texts in all languages used. Translate the texts using the bulk translation function.

See also Examples (Page 58)



12.4.3 Examples

12.4.3.1 Creating a standard table

Procedure To create a standard table with text entries, proceed as follows:

1. Click the "Administrator > Base data > Standard tables" menu.

2. Create a new standard table under the "@10 Attributes catalog" node under the required folder.

3. Recommendation: Enter "COM_NLS" as the name of the standard table.

4. Open the new standard table.

5. Right-click on the empty area to create a new text entry.

6. Select the "New > Standard table value" command from the context menu.

7. Enter the required data in the "New" window.

Recommendation: Enter additional text for the header in message boxes. Ensure that the entry is given the name of the message pertaining to it.

8. Save your entries.

See also Translating entries (Page 58)

12.4.3.2 Translating entries

Procedure To translate the entries of a standard table, proceed as follows:

1. Open the bulk translation function.

2. Drag&drop the standard table from the Navigator into the "Start object(s)" field.

3. Populate the various language columns with the translations.




12.4.3.3 Scripts

Example of a call from the object debugger Call TestMessagebox() Sub TestMessageBox() msgbox NLS_Text("ErrThisIsATest"),, NLS_Text("ErrThisIsATest_Header") End Sub Function NLS_Text(strNLSText) NLS_Text = Project.Workset.Lib.CallScriptLib ("@02|200|EIC|S|COM|01", "NLSText", "TST|COM_NLS|" & strNLSText) End Function

Example German

Example English




Project-wide and database-wide options 13

Project-wide options concern the entire project. Database-wide options are similar to project-wide options but the setting is the same for all database projects.

13.1 Creating project-wide and database-wide options

System project You create new options as attributes in the "@PROPAR project parameters" object on the "COM000 COMOS" tab in the "@COMOSSYSTEM" system project.

You can create the attributes directly here and do not have to inherit from an attribute from the attributes catalog.

Recommendation Group the attributes which belong together in a frame.

13.2 Setting the scope

Procedure To set the scope of an option, proceed as follows:

1. Right-click on the attribute.

2. Select the "Properties > Attribute" command from the context menu.

3. To give the option database-wide validity rather than project-wide validity, select the "Editable - in base object tree in base project only" entry from the "Edit mode" list.


Result You can only set this option in the project properties of the system project.

Project-wide and database-wide options 13.3 Setting options


13.3 Setting options

Procedure To set the project-wide or database-wide options, proceed as follows:

1. Call the project properties or system project properties.

2. Click the "Options > COMOS" tab.

Although you can only change the database-wide options in the system project, these are visible in every project.