Konventionen

Konventionen für die Namensgebung von F-Scripts

Um Typ, Inhalt und Kontext der F-Script Dateien bereits am Namen der Datei erkennen zu können, wird bei der Namengebung die Einhaltung der nachfolgenden Konventionen empfohlen.

Aufbau von Scriptnamen

Kürzel	Strich	Bezeichner/Modul	Laufnummer	Punkt	Datei-Endung	Zusatz
ST	-	VE	100	.	FF
XX	-	VE	100	.	FF
XX	-	Pdf2Email		.	FF

Kürzel

Das Kürzel sollte aus zwei Zeichen bestehen und hat folgende Bedeutung:

Wert	Beschreibung
ST	Standard
KD	Kundenspezifische Scripts, welche von Standard-Scripts aufgerufen werden.
XX	Kundenindividuelle Scripts, (XX=Kundenkürzel).
MU	Muster-Script im WAS-Bereich

Bezeichner/Modul

Bei Output-Scripts (Drucken von Dokumenten, Auswertungen, etc.) sollte das Modul angegeben werden.

Wert	Beschreibung
AL	Allgemein
AD	Adressen
AR	Artikel
LA	Lager
SE	Servicewesen
VE	Verkauf
EI	Einkauf
MI	MIS

Bei Logik-Scripts (Verarbeitungen ohne Output) sollte ein möglichst sprechender Bezeichner vergeben werden. Ausnahmen sind hier z.B. VERPSAVE.FF (fixer Name) oder Scripts vor dem Verbuchen von Dokumenten z.B. XX-VEVV.FF

Nachfolgend ein paar Beispiele:

Wert	Beschreibung
OP-CatProcess.FF	Katalogverarbeitung gem. Service Cat_Process.
OP-PrintDMSDoc.FF	F-Script für das Ausdrucken von DMAS Dokumenten.
OP-CustomerMail.FF	F-Script für das Versenden von E-Mails an Kunden.

Die weiter oben erwähnten Ausnahmen betreffen vor allem Layout-Scripts, Scripts vor dem Verbuchen von Dokumenten und Scripts mit fixen Namen.

Nachfolgend ein paar Beispiele:

Wert	Beschreibung
OP-VEVV.FF	F-Script vor dem Verbuchen bzw. vor UNDO von Verkaufsdokumenten.
VERPSAVE.FF	F-Script welches beim Speichern von Verkaufspositionan abläuft. Dieses Script muss fix diesen Namen tragen.
OP-VE100.FF	F-Script für das Layout von Verkaufsdokumenten. (Laufnummer 100 gem. Kundenanforderung)

Laufnummer

Werden Laufnummern verwendet, sollten diese jeweils bei 100 beginnen und drei Stellen nicht überschreiten.

Wert	Beschreibung
100 - 999	Die Laufnummer beginnt pro Modul bei 100 und wird fortlaufend belegt.

Datei-Endung

Über die Datei-Endung (file extension) können die F-Scripts in verschiedene Kategorien unterteilt werden.

Wert	Beschreibung
FF	Hauptscript
FS	Subscript. Dieses wird von FF/FX aufgerufen.
FX	Funktions-Script
FSS	Applikations-Server-Script (Auswertungen > Ausgabe-Attribute)
SF	Softform (Rastergrafik)
MF	Masterform
LB	Sprach-Library
LIB	Library
PR	Druckersteuerung
CONFIG	Konfigurations-File im WAS-Bereich

Zusatz

Über den Zusatz der Datei-Endung können beispielsweise Sprachen oder Formate angegeben werden.

Ein Zusatz ist in jedem Fall optional. Ist ein F-Script beispielsweise sprachunabhängig, dann wird der Zusatz komplett weggelassen.

Wert	Beschreibung
D, E, F, I	Sprachkürzel bei Scripts und Übersetzungs-Libraries.
1 - 5	Benutzersprache (Nummer) bei Libraries.
H, Q	Ausrichtung bei Druckersteuerungen, Soft- und Masterforms (H = Hoch, Q = Quer).

Konventionen für den Aufbau und Inhalt eines F-Script Header

Damit für jede Person welche ein Script editiert bzw. in einem Editor betrachtet schnell und einfach ersichtlich ist über welche Funktionen etc. das F-Script verfügt, sollte der F-Script Header in kompakter Form die wichtigsten Informationen enthalten. Zudem dient der Header auch dazu, Änderungen welche am F-Script vorgenommen wurden zu protokollieren.

Wir empfehlen folgenden Aufbau des Headers:

Wert	Beschreibung
Titel	Name des F-Scripts inkl. einer kurzen Beschreibung der Funktionalität.
Kunde	Name des Kunden für welchen das F-Script erstellt wurde.
Kontext	Wie und/oder wo wird das F-Script gestartet/verwendet und was muss beachtet werden.
Autor	Programmierer/Scripter welcher das F-Script erstellt hat.
Erstellt	Erstelldatum des F-Scripts.
Geändert	Änderungen am F-Script. Diese sollten jeweils auf einer Zeile das Datum und eine kurze Beschreibung der Änderung enthalten. Zudem sollte das Kürzel des Programmierers/Scripters angegeben werden.

Beispiel eines Headers (kann als Vorlage verwendet werden).

# *****************************************************************************
# Dateiname: KD-MAIL.FF
#            Emailversand OpaccCampus Kurs F-Script III
# 
# Kunde:     STANDARD-TEMPLATE
#
# Kontext:   Subdokument von aktivem Verkaufsdokument
# 
# Autor:     OPACC Software AG, Luzern - Roman Vonwil
# 
# Erstellt:  <Datum> / <Kürzel>
# 
# Geändert:  <Datum> / <Kürzel> - <Kurzbeschreibung>
#            <Datum> / <Kürzel> - <Kurzbeschreibung>
# *******************************************************************************

Konventionen für die Namensgebung von Subroutinen

Eigene Subroutinen (also nicht die Standard-Subroutinen wie /headerreport, /body, etc.) sollten mit klaren und sprechenden Namen versehen werden.

Notiz

Beachten Sie, dass die maximale Länge eines Subroutinen-Namens (inkl. dem führenden Slash) 50 Zeichen betragen darf.

Beispiele für korrekte Namen von Subroutinen.

Name

/Detail.Positionen

/Print-Positionen

/LSPositionen

Namen welche sehr ähnlich lauten wie die Standard-Subroutinen oder nicht sprechend sind, sollten vermieden werden.

Name	Fehler
/BODY	Konflikt mit Standard-Subroutine.
/body1	Grosse Verwechslungsgefahr mit Standard-Subroutine.
/totalreport\|	Grosse Verwechslungsgefahr mit Standard-Subroutine.
/Sub1	Unklare Bezeichnung. Fehlende Übersicht beim Aufruf.
/A.1	Unklare Bezeichnung. Fehlende Übersicht beim Aufruf.

Konventionen für Kommentare in F-Scripts

Erfassen Sie aussagekräftige Kommentare! Denn was heute noch klar und verständlich ist, muss nach einiger Zeit im Code mühsam gesucht werden, falls keine Kommentare erfasst wurden. Das Erfassen von "Trennern" (horizontale Linien" erleichtert die Strukturierung, Lesbarkeit und das Auffinden von Kommentaren zusätzlich.

Einige Beispiele:

/headerreport
# ___________________________________________________________________________
# Parameter speichern.
«/Set.Parameters»
# ___________________________________________________________________________
# Parameter validieren.
«/Parameters.Validate»
# ___________________________________________________________________________
# Abbruch wenn Datei nicht vorhanden.
«nz X(FileNotFound)\I»«GOTO(/)»
/

/Set.Parameters
# ___________________________________________________________________________
# Importverzeichnis
«X(Import.Directory =«SYS(FULLPATH)»TX\IMPORT\)»
# ___________________________________________________________________________
# Import-Datei
«X(Import.FileName  =import_abc.csv)»
/

/Parameters.Validate
«nz~SYS(EXISTFILE «X(Import.Directory)»«X(Import.FileName)»)\I»«X(FileNotFound=1)»
/

Konventionen für die Verwendung von Variablen

F-Script verfügt über zahlreiche verschiedene Variablentypen. Diese unterscheiden sich teilweise grundlegend und sind dadurch für verschiedene Anwendungsfälle mehr oder weniger geeignet. Nachfolgend eine Auflistung der verschiedenen Variablentypen mit Empfehlungen zu Verwendung.

Notiz

Die Detailbeschreibungen der Variablen finden Sie unter: Sprachelemente / Variablen.

Variablentyp	Verwendung / Anwendungsfall
«MEM(<n>)»	Rückgabewerte von IBOS, Länge/Inhalt (Anzahl Zeilen) von Textblöcken, etc. Werte mit kurzer Verwendungszeit. z.B. nur innerhalb einer Subroutine. «nm1IS(ADR-NEU,,1,,0)» Neue Adresse: «MEM(1)»
«VAR(<n>)»	Rückgabewerte von IBOS, Länge/Inhalt (Anzahl Zeilen) von Textblöcken, etc. Werte mit kurzer Verwendungszeit. z.B. nur innerhalb einer Subroutine. «nv1KONDITIONSTEXT(100,W80)» «nzVAR(1)=0\N»«GOTO(/)»
«MEA(...)»	Temporär verwendete Tabellen. Dieser Variablentyp ist für Logiksteuerungen zu vermeiden! /headerreport «POSITIONEN(/Artikel.Liste)» / /Artikel.Liste «MEA(+,«AP-ART-NR»)» /
«MEX(...)»	Temporär verwendete Tabellen. Dieser Variablentyp ist für Logiksteuerungen zu vermeiden! /headerreport «POSITIONEN(/Artikel.Liste)» / /Artikel.Liste «MEX(+,«AP-ART-NR»)» /
«X(<VariablenName>)»	Sprechende, frei zu benennende Variablen mit beliebigem Inhalt. Gut geeignet für Steuerungslogiken, sowie beim Arbeiten mit F-Services. /headerreport «X(VersandArt=)» «nzAUF-FREI2\I»«X(VersandArt=«AUF-FREI2»)» /
«SUM(<n>)»	Summieren von Werten (z.B. innerhalb von Dokumenten) für die anschliessende Ausgabe von Totalen. /headerreport «POSITIONEN(/Summe.PositionsMenge)» Total Menge: «SUM(1)\N» / /Summe.PositionsMenge «n+1AP-ANZAHL\N» /
«CARRY» «SUM(0)»	Der Summenspeicher 0 (CARRY) wird speziell für Seitenüberträge verwendet. /body # Carry füllen / Wert ausgeben «+«AP-MINUS»AP-BETRAG$»)\N,000t0p» / /totalcarry Übertrag: «CARRY\N,000t0p» /
«MARK(<n>)»	Indikator für Validierungen, etc. In Logiksteuerungen sollten anstelle von MARK(<n>) besser X(Variablen) verwendet werden. /headerreport «/Check.File» «nz~MARK(1)\I»«SYS(MSG INFO ‘FILE.TXT’ nicht vorhanden!)»«SYS(STOP)» / /Check.File «nMARK(1,ON)» «nz~SYS(EXISTFILE «SYS(FULLPATH)»TX\FILE.TXT)\I» «nMARK(1,OFF)» /
«NO(<n>)»	Zähler. Kann beispielsweise für das Abbrechen von REPEAT/LOOP Schleifen verwendet werden. Zähler sollten nicht für das automatische Erstellen von Variablen ("Variablen-Nummerierung) verwendet werden! /body «nNO(1,NULL)» «REPEAT» «nNO(1)» ... «nzNO(1,0)=100\N»«LOOP» /
«ARRAY(<a>)»	Zwischensummen und Rekapitulation von numerischen Werten. /body «nzAP-MIS1=1\N»«ARRAY(Software,««AP-MINUS»AP-BETRAG$»)» «nzAP-MIS1=2\N»«ARRAY(Hardware,««AP-MINUS»AP-BETRAG$»)» / /totalreport Total Software: «ARRAY(Software)\N,000t0p» Total Hardware: «ARRAY(Hardware)\N,000t0p» /
«HARRAY(<ID>,<DATA>,<AUX>)»	Gruppieren und sortieren von Daten. z.B. für Rekapitulationen etc. /body «HARRAY(«AP-LAGER-NR\N8F0»@«AP-INR\N4F0»,«AP-LAGER-NR»,)» / /totalreport «HARRAY(DATA,/PositionenNachLagerOrt)» / /PositionenNachLagerOrt «nPOS(@,«HARRAY(ID)»)» «nzAP-ACTIVE(«AUF-DOKINR»,«POS(2)\N»)\I» ... /

Konventionen für Sprungmarken

Sprungmarken ermöglichen das gezielte "Springen" zu bestimmten Codezeilen innerhalb eines F-Scripts. Da Sprungmarken die sequentielle Abarbeitung eines F-Scripts beeinflussen, sind sie sparsam und mit Bedacht einzusetzen.

Notiz

Beachten Sie, dass die maximale Länge einer Sprungmarke (inkl. dem führenden # plus nachfolgendem Space) 80 Zeichen betragen darf.

Folgende Regeln sollten bei der Verwendung von Sprungmarken beachtet werden:

Sprungmarken werden in Grossbuchstaben (UPPERCASE) geschrieben.
Leerzeichen innerhalb einer Sprungmarke sind unbedingt zu vermeiden!
Sprungmarken welche vom Ende einer Subroutine an deren Anfang verweisen, sind zu Vermeiden. Die Gefahr von "Endlos-Loops" ist gross!
Sprungmarken dürfen nur auf "Ziele" innerhalb der jeweiligen Subroutine verweisen.
Sprungmarken sollen klar als solche gekennzeichnet sein.
Die Kennzeichnung von Sprungmarken nach Schema # JUMP-... vereinfachen die Lesbarkeit.

Beispiele von korrekten Sprungmarken bzw. GOTO-Aufrufen

Name

«GOTO(# JUMP-VORAUSZAHLUNG)»

«GOTO(# JUMP.AUSGABE.DOKTOTAL)»

«GOTO(# JUMP-ENDE-SCRIPT)»

«GOTO(/)»

Sprungmarken bzw. GOTO-Aufrufe der folgenden Art sind unbedingt zu vermeiden!

Name	Fehler
«GOTO(# BODY)»	Standard-Routine /body benötigt spezifische Aktivierung.
«GOTO(# ANDERE-SUBROUTINE)»	Sprungziel ausserhalb eigener Routine.
«GOTO(# RV: Korrektur Call 11111)»	Kommentar-Zeilen sind als Informationen gedacht.
«GOTO(# A.1.1)»	Unklare Bezeichnung.

F-Script

Standard F-Script Konventionen

Konventionen für die Namensgebung von F-Scripts

Aufbau von Scriptnamen

Kürzel

Bezeichner/Modul

Laufnummer

Datei-Endung

Zusatz

Wichtig

Konventionen für den Aufbau und Inhalt eines F-Script Header

Konventionen für die Namensgebung von Subroutinen

Notiz

Konventionen für Kommentare in F-Scripts

Konventionen für die Verwendung von Variablen

Notiz

Konventionen für Sprungmarken

Notiz