coding guide - seeburgermappingmanagement.seeburger.de/seexml/wiki/media/wiki... · 2019-04-17 ·...

© SEEBURGER AG 2017 169© SEEBURGER AG 2018 169

Coding Guide


1 Introduction

© SEEBURGER AG 2018 171

Coding GuideIntroduction

Goal of this coding guide is to unify the creation of mappings. Especially for SEEXML partner mappings it isnecessary to have such a guide. We want to provide this guideline to everyone who is creating mappings forSEEBURGER (also external partners).

The following rules are valid from now on for all new BIC-mappings (direct mappings and SEEXML-mappings) created with BIC version 5.5.2 and higher!


2 Naming conventions


Coding GuideNaming conventions

Message structures

Following rules are valid for all message strucures where it is allowed to set the name yourself (non EDIFACT,non ODETTE, non ANSI X.12, non VDA (+ERG), non SEEXML).

• Use English as language

• Use the underscore to separate between special parameters (e.g. DELFOR_XYZ)

• If a message has the suffix “STD” you must not change this structure! (use a copy with new name instead)



INHOUSE

If the name of the INHOUSE-message is not predefined by the customer, choose the following namingconvention:

Syntax BusinessCase_Customer

Example DELFOR_XYZ



SAP

We use the name generated by SAP. The German or English variant must be marked by D or E. Furthermore itmust be marked if it is a SAP-XML-IDoc. In all cases where the structure was adapted to the customerrequirements (so called Z-Idoc), it must be marked in the name.

Syntax BusinessCase_(D or E)Release_(Customer)

Example INVOIC02_D46C or ZORDERS05_E45B_XYZ or X_DELFOR02_D640



VDA

We use the predefined names of the VDA plus version. Additionally, we put „STD“ at the end to show thatthe structure is conform to the VDA-guideline and the structure is provided by SEEBURGER. If changes of theSTD-structure will take place the structure must be renamed (i.e. VDA4905_V04_VW)!

Syntax VDAName_Version_(ERG)_(Addition)_STD

Example VDA4905_V04_STD or VDA4913_ERG_STD



CSV

We use the same naming convention as for the general INHOUSE-messages

Syntax Business case_Customer

Example ARTICLEDATA_XYZ



SQL / DATABASE

We use the same naming convention as for the general INHOUSE-messages.

Syntax BusinessCase_Customer

Example ARTICLEDATA_XYZ



XML

The naming convention for XML structures is dependant on the publisher.

Syntax BusinessCase/Name_Version_(Customer)

Example BMECAT_10



EDIFACT/ODETTE

The name of EDIFACT structures is predefined by the UN. We only put “STD” at the end of the name to verifythat the structure is EDIFACT/ODETTE conform and that it is provided by SEEBURGER. If changes of the STD-structure will take place the structure must be renamed (i.e. DELFOR_UN_D96A_PSA)!

We use the same naming convention for ODETTE structures.

Syntax MessageType_Organisation_Version/Release_STD

Example INVOIC_UN_D93A_STD or DELINS_OD3_STD



SEEXML

Following naming conventions are valid for SEEXML:

Independent (CPG and Automotive):

Syntax Name_Version

Example SEEDELFOR_V3_0, SEEDESADV_V3_0, SEEINVOIC_V3_0



Automotive:

CPG/Retail:

Syntax SEE_MessageTypeVersion

Example SEE_ORDERS_V01

Syntax Name_Version

Example SEEDELFOR_V2_0, SEEDESADV_V2_0, SEEINVOIC_V2_0



TRADACOM

Tradacom-structures are predifend by the Article Number Association (UK) Ltd (ANA).

Syntax BusinessCase_Version

Example INVOIC_123



ANSI X.12

The name of ANSI structures contain the message type, version and „STD“. The STD is used to verify that thestructure is ANSI conform and that it is provided by SEEBURGER. If changes of the STD-structure will takeplace the structure must be renamed (i.e. 830_3030_FORD)!

Syntax MessageType_Version_STD

Example 830_002040_STD



SWIFT

We used the predefined names of the SWIFT Standard Organisation.

Syntax SwiftName_(Bank)

Example MT940, MT940_Commerzbank


Coding GuideMappings

The following rules are valid for all mappings:

• Use the underscore to separate between special parameters

• There are no further separators

Partner mapping:

Syntax Partner_EDI-Message-Partner_Direction

Example SCANIA_DELFOR_D96A_IN (SEEXML-Partner-Mapping)



Process mapping:

Syntax Branch_CustomerOrSupplier(C or

S)_SourceMessage_TO_DestinationMessage_Customer

Example AUTO_C_SEEDELFOR_V3_0_TO_DELFOR02_[Customer] (SEEXML-Prozess-

Mapping)



Direct mapping:

If a message type can be used for several business cases, the business case must be put directly after thepartner.

I.e. OPEL_PUS_DELJIT_UN_D97A_STD_TO_DELFOR02_D640

Syntax Partner_SourceMessage_TO_TargetMessage

Example TOYOTA_830_4010_STD_TO_DELFOR02_D640 (BIC Direct Mapping)


3 Coding


Coding GuideCoding

We refer to the notion concerning mappings in the Mapping Management Guide!

All mappings, comments, variable names and so on must be written in English. You have to use BIC featureswhen possible. Try to write one line instead of five lines.


Coding GuideRules for any kind of mapping

Header

Following information must be mentioned in the header of each mapping.

1. @Customer Either the name of the customer for which the mapping is created or the key

word Standard-Mapping

2. @Author Name of the creator of the mapping

3. @SourceMessage Source Message of the mapping

4. @ReleaseSource Release of the source message (e.g. 4.6C)

5. @DestinationMessage Destination Message of the mapping

6. @ReleaseDestination Release of the destination message

7. @Type „Direction“ of the mapping (e.g. IE for INHOUSE EDIFACT



8. @Partner Partner for which the mapping is valid

9. @Mapfiles Used mapfiles in this mapping

10.@Created on Date in format CCYYMMDD

11.@BIC-Version BIC version where the mapping was created

12.@Description Description of the use of the mapping

13.@ParentCopy Name of the mapping copied from

14.@SpecialInformation If there are special things (like user functions, use of additional programs…) mention here

15.@Changes Every change of the mapping must be documented in a new line and should contain the following information

- Description of the change

- Date of the change

- Name of the person who changed the mapping



Example:/*

SEEBURGER AG BIC Mapping

@Customer = STANDARD-MAPPING

@Author = Name of mapping creator

@SourceMessage = DELFOR

@ReleaseSource = UN_D96A_STD

@DestinationMessage = SEEDELFOR

@ReleaseDestination = 3_0

@Type = E2X



@Partner = DAF

@Mapfiles = Mention here used mapfiles

@Created on = 20061127

@BIC-Version = 5.4.2 Q7

@Description = Description can (and should!) be

over several lines

@ParentCopy = Name of the Mapping copied from

@SpecialInformation = STANDARD-MAPPING Based on guideline…

@Changes = 2006-11-27: First version

= 2006-11-28: Shortcut of changing person: Added RFF+DQ

*/


Coding GuideVariables

The first part of a variable name indicates the scope of usage. We use g for global, d for dim, p forparameter (at procedures) and l for local. Please note that the BIC manual recommends to use globalinstead of dim.

Concerning the name of the variables the content of the field you want to save, is important. A furtherpossibility is to use the original field name as variable name (e.g. g_P16_EDATUB$). Please avoid variablenames like temp$, y% and so on as no one, except you, know what they mean. You are only allowed touse variable names like that, if it is a local variable which is only valid for a small coding part.

Please do not use any hyphens (“-“) in variable names and delete every variable you do not need.

For every separate word in the variable name must divide with a (“_”). The first capital of any word mustbe in uppercase anything else generally in lowercase. Specific Elements such as Qualifier or own namesmust be completely written in uppercase.


Coding GuideVariables

Examples.: Customer number g_Customer_Number$

Supplier number g_Supplier_Number$

Transmission number g_Transmission_Number$

P16_EDATUB g_EDATUB$

Furthermore we describe some special conditions for variable names. Other interpretations of variablenames are not allowed.


Coding GuideConstants and System values

All constants must have uppercase letters. The values of the variables do not change in the mapping.

Examples.: DEBUG$ - for all Debug-Analysis

DEBUG_TEXT$ - for all Debug-Textes

DEFAULT_EDIFACT_ENCODING – for Edifact Encoding

MAPPING$ - for the Name of the mapping

VERSION$ - for the Version of the mapping


Coding GuideCounter

All Counters begin with “Counter_” followed by the reference of the counter. It is global defined asnumeric.

Examples: UNB Counter Counter_UNB%

Item Counter Counter_Item%


Coding GuideLoops

A specific counter for algorithmic operations is a loop. All loops begin with “Loop_” followed by thenumber of the Loop. A Loop is global defined as numeric.

Examples: Frist Loop Loop_1%

Second Loop Loop_2%

Every level within a loop (if-, for-, selectcase-loop) must be indented by four blanks (= 1 TAB) to have abetter view.

Using several nested loops you should comment the start and end commands.


Coding GuideLoops

Note: Use selectcase instead of if. This is caused in performance reasons.

If the loop appears into a procedure you have to put a ‘l_’ prefix before the variable name.

E.g. l_Loop1%, l_Loop2%, … This is necessary to avoid errors with global variables if you call the procedureinto a loop which is initiated by a Loop_*% variable.


Coding GuideBoolean Variables

All Boolean variables have their own specific prefix, e.g. you can use Found_, Created_ or Exist_. TheVariable is global defined as alphanumeric and can have the states “true” or “false”.

Examples: NAD there Created_NAD$

CPS found Found_CPS%

In BIS6 (language 2) you can use the Boolean data type with prefix ‘?’.

Examples: NAD there Created_NAD?

CPS found Found_CPS?


Coding GuideSpecific Values for getdestinationfield()

If you use getdestinationfield() in your mapping, you must defined the variable with the prefix “Current_”followed by the name of the field value.

Examples: Item.Number:value Current_Item_Number$

QTY.Qualifier:value Current_QTY_Qualifier$


Coding GuideArrays

All arrays begins with “Table_” followed by the name of the array.

Especially for array variables it is important to delete them as for every array at the beginning of themapping the respective memory is reserved.

Examples: L24 Table_L24$[10]

Item Table_Item$[10]


Coding GuideCommands

All commands and functions are written in lower case. Is there more than one line using “to”, you have toput that into the same column.

If unused Mapping Code is in the Mapping you have to delete it.

You must write mapping code in clearly arranged design.

Example:copy "380" to UNB.UNH.BGM:C002.1001;

copy K01:BELNR to UNB.UNH.BGM:1004;


Coding GuideDrag & Drop

Use the Drag&Drop option of the Mapping Designer as you can avoid unnecessary typing errors.

It is possible to setup existcopy as default command for drag and drop.


Coding GuideComments

Comments are important for everyone who uses the mapping. No-one knows what the creator of themapping thought during programming a complex loop and the creator himself doesn’t know it any morea few days later.

The more detailed the comments are, the better it is.

Comments are only allowed in English.

Usually, comments are inserted one line before the mapping code you want to comment.



Example of good comment:



Example of bad comment:



Please do not left unused code in comment. This causes huge code.

Example:


Coding GuideCode formatting

Code must be correctly formatted, because, if the code is not formatted correctly, is badly formatted,hard to read, or cannot be copied-and-pasted without unwanted junk. Code should be easy to read andcopied-and-pasted. There three important rules:

• Code examples should use good semantic mark-up

• Tabs in code should not be converted in to spaces.

• Code should have basic syntax highlighting.



Example of good formatted code:



Example of bad formatted code:


Coding GuideCode Review

Code review is important, if the code of mapping is not clear or difficult to read. Code review make theoverall quality of mapping code better and readable. Example of code review necessary:

Before code review: After code review:

This “Partner ID’s” can be replaced with parameter send from Partner_Def mapping.



Before code review:



After code review:


4 Rules for Individual Mappings and Standard Mappings


Coding GuideMapfiles

It is allowed to use mapfiles. Every used mapfile must be opened by openmapfile in the first mandatoryrecord pattern or new mapping record. Additionally, every mapfile must be documented in the mappingheader.

The columns in mapfiles must be separated by the comma. They have the file ending *.map or *.cde. Themapfile names must be written in upper case and should not contain any hyphens to avoid problems withnon-Windows-systems.


Coding GuideJava User Functions

It is allowed to use Java User Functions. Before using them please make sure that the needed functioncannot be realised using BIC commands. The usage of Java User Functions must be mentioned in theheader comment under Special Information. The used JAVA classes must be available in all common javaruntimes to avoid update errors. SEEBURGER will not support errors and issues which are caused by javaclasses.


Coding GuideArrays

In general the usage of arrays isallowed.

Using two-dimensional arrays it isdifficult to retrace which column haswhich value (the index strats with0). Due to that you should handletwo –dimensional variables asfollows.

According to the column head linesyou have to create variables. Theindex of a column is defined by thevalue you assign to the respectivevariable.


Coding GuideArrays

You can access the array by using the following command:

g_Order_Date$ = L24_Table$[0][BSTDK%];

In general you should avoid using two-dimensional arrays. Instead use the BIC sort commands (e.g.sortsegmentsbyfieldvalue()) available >= BIC 5.5.2


Coding GuideHash tables

If possible (BIC 6, language V2) you can use hash tables instead of variables.

E.g.: Table_REF${}{} to save reference values.

In this case the references are saved into an hash table which is addressed by the qualifiers name as first key and the field name as second key.


Coding GuideProcedures

Definition:

A procedure is a set of instructions that perform a specific task, similar to subroutines or functions.

Procedures are reusable.

Procedures can have one or more parameters.

Procedures can be invoked several times.

Appearance:

Local procedures can be used within one mapping only.

Global procedures can be used by all mappings belonging to one workspace.


Coding GuideProcedures

Special features of global procedures

If a global procedure is changed only the procedure has to be compiled/deployed. After thecompilation/deployment the changes will be valid for all mappings.

Procedures comply with a record program of a mapping. Same functions/commands can be used toaccess the current source segment/target structure.

Global procedures cannot use variables that are defined in the mappings!

Global procedures can have own variables, they can be used in other methods that belong to the globalprocedure. Local ones can be used in the current method of the procedure only.

Global procedures can be imported/exported from/to the file system.

Global procedures can be imported/exported from/to the repository to share them with otherdevelopers.

Global procedures need to be activated and deployed in BIC MD and BIS Front-end to use them in a BISsystem.


Coding Guide

Avantages:

Global procedures are independent objects inthe repository and may be used accordingly.

If a global procedure is changed, only this globalprocedure has to be compiled. The mapping willcontain those changes without the need to berecompiled.

Disadvantages:

Global procedures are independent objects inthe repository and may be used accordingly.

If data is read/written from source/to targetstructure the usability is limited. It can be usedfor mappings with the same input/outputstructure only.

Tip: Can be avoided by varying the address strings e.g. using getField/setField method and pass fields byparameter.

Global procedures


Coding GuideLocal procedures

The procedure editor can be used by open the “Mapping procedures” tab in the mapping.

New procedures can be created, existing ones can be edited in the “Mapping procedures” tab.


Coding GuideLocal procedures

Procedure will be called by write down the procedure name followed by brackets inside the mapping.

Example: WRITE_ADDRESSDATA()


Coding GuideHow to use global procedures

New global procedures can becreated, existing ones can be editedby using the “Global procedure”folder in the BIC MD projectexplorer.

Each global procedure can have itsown methods with several inputand/or output parameter.

To use a global procedure on a BISsystem it needs to be checked in,activated and deployed (equivalentto mappings).


Coding GuideSyntax of procedures

Global procedure call: [Global_Procedure_Name]_[Method_Name]([Parameter]…)

Local procedure call: [Local_Procedure_Name]([Parameter]…)

User functions are no longer supported. However, it is possible to use Java classes to Import a user function as a global procedure to BIC MD.

Local procedures can be converted to methods that can be used by global procedures.

This process also works in reverse:

Procedure execution (local and global ones) allows return values. The return value will be passed back to the mapping for further usage.


Coding GuideMapping Repository

Central storage for objects (mappings, messages and global procedures)

Version management for such objects



Context Menu

• Located in the Repository menu under File, Project, Message or Mapping.

• Shows all possible action at the choosed context.



Context Menu – Actions

• Import new or other mapping / procedure version from the repository

• Check-In (Read-Only) / Check-Out (Read/Write) of mappings

• Get latest version of a mapping or message from the repository

• Activate mappings

• Create repository connection

• Disconnect repository connection

• Delete repository connection

• Import Codelistpool



TreeView

• Located in the Configuration tab under converter

settings in frontend.

• Shows all mappings and messages in a tree view

(comparable to the Mapping Designer).

• Shows details of all available versions.

• Delete / purge of mappings / projects

• Unlock mappings

coding guide - seeburgermappingmanagement.seeburger.de/seexml/wiki/media/wiki... · 2019-04-17 ·...

Documents