Inhaltsübersicht

Bitte beachten Sie die folgenden Hinweise, damit Ihre WOPiXX-Programme sauber umgewandelt werden können:

Einzubindende Copystrecken

In den Bibliotheken WOPIX und DIRWEB befinden sich Copystrecken, die eingebunden werden müssen, bzw. können:

• WOPIX/QCPYLESRC
  • WX_HSPECS
  • WX_FLDREF
  • WX_HCOPYR
• WOPIX/QPROLESRC
  • WX_PROTO

Die Copystrecken sind zum Teil noch in Fixed-Form RPG geschrieben. Sie können aber problemlos mit Free Format RPG-Quellen (auch in Full-Free) eingebunden werden.

Die von Toolmaker zur Verfügung gestellten Copy-Strecken können wahlweise mit /COPY oder /INCLUDE in die individuellen Quellen eingebunden werden.

Der Unterschied zwischen beiden Angaben liegt darin wie der SQL Precompiler die Copy-Strecken behandelt. Bei Verwendung von /COPY wird die Copy-Strecke vom SQL Precompiler aufgelöst, während sie bei Einbindung mit /INCLUDE übergangen wird. Dies hat besonders bei verschachtelten Copy-Strecken Konsequenzen, da er SQL Precompiler verschachtelte Copy-Strecken nicht unbedingt verarbeiten kann.

Anmerkung: Copy-Strecken mit Informationen, die von SQL nicht verwendet werden, sollten mit /INCLUDE eingebunden werden.

Diese Copystrecken werden im Folgenden beschrieben.

Copy-Strecken zur Referenzierung von Variablen

Die Copy-Strecken, die zur Definition von Parameter-Feldern verwendet werden, sind jeweils direkt in den Copy-Strecken für die Prototypen integriert. Da die Prototypen in die individuellen WOPiXX-Programme eingebunden werden müssen, werden die Referenz-Felder und Datenstrukturen ebenfalls eingebunden. Eine separate Einbindung der Copy-Strecken mit den Referenz-Informationen ist somit in den individuellen WOPiXX-Programmen nicht erforderlich.

Da alle Referenz-Datenstrukturen durch Compiler-Direktiven bedingt sind, treten bei mehrfacher Einbindung der gleichen Copy-Strecke bzw. bei mehrfacher Definition der gleichen Datenstruktur keine Probleme auf. Die erste Definition wird verwendet, die folgenden Definitionen werden ignoriert.

Bei WOPiXX-Programmen mit embedded SQL muss ggf. die Copy-Strecke D_FLDREF angegeben werden, da der SQL Precompiler verschachtelte Copy-Strecken abhängig vom Release u.U. nicht auflösen kann.

Referenzierung und Prototypen

Alle in den Prototypen hinterlegten Parameter-Felder wurden basierend auf den Feldern in der Feld-Referenz-Datei oder anderen in den Copy-Strecken WX_FLDREF und D_FLDREF definiert.

Variablen oder Datenstruktur-Unterfelder, über die Daten mit den WOPiXX-Funktionen ausgetauscht werden, können genau wie die Parameter-Felder in den Prototypen definiert werden.

Anmerkung:Um Probleme mit unterschiedlichen Definitionen zu vermeiden, und um Änderungen (z.B. Feldlänge oder Anzahl Elemente einer Feldgruppe) ohne Anpassungen zu ermöglichen, wird empfohlen alle individuellen Variablen, über die Informationen mit den WOPiXX-Funktionen ausgetauscht werden, über die Referenzen zu definieren.

H-Bestimmungen in HX_HSPECS

Optional. Es wird empfohlen, die Copy-Strecke WX_HSPECS kann in den H-Bestimmungen hinterlegt werden.

    ‚ **********************************************************************************************                    
    ˆ * H - S P E C I F I C A T I O N S                                                                                 
    ‚ **********************************************************************************************                    
    ‚ * Binding Directory                                                                                               
     H/IF NOT DEFINED(HBndDir)                                                                                          
     H BndDir('WXBNDDIR': 'DWBNDDIR': 'QC2LE')                                                                          
     H/ENDIF                                                                                                            
    ‚ *                                                                                                                 
     H/If Not Defined(HCopyRight)                                                                                       
     H/Include QCPYLESRC,WX_HCOPYR                                                                                      
     H/EndIf                                                                                                            
    ‚ *                                                                                                                 
    ‚ * H-Specs DirectWeb                                                                                               
     H/Include QCPYLESRC,DW_HSpecs                                                                                                        

Wird die Copy-Strecke nicht verwendet, muss sichergestellt werden, dass das WOPiXX-Programm mit Aktivierungsgruppe *CALLER erstellt wird und das Binderverzeichnis WXBNDDIR im Binderschritt verwendet wird.

Individuelle Anpassung der H-Bestimmungen

Alle Schlüssel-Worte in der Copy-Strecke WX_HSPECS sind durch Compiler-Direktiven bedingt und können beliebig aktiviert oder deaktiviert werden.

Im folgenden Beispiel wird die Option BNDDIR um das individuelle Binderverzeichnis MYBNDDIR erweitert. Anschließend wird die Copy-Strecke WX_HSPECS eingebunden. Durch das Setzen der Compiler-Direktive /Define HBNDDIR werden die in der Copy-Strecke WX_HSPECS angegebenen Binder-Verzeichnis-Einträge übergangen.

/Define HBndDir
H BndDir('WXBNDDIR': 'DWBNDDIR': 'QC2LE', 'MYBNDDIR')
/INCLUDE WX_HSPECS

Deaktivieren / Ändern Aktivierungsgruppe in Copy-Strecke

Wird die Copy-Strecke WX_HSPECS verwendet, können die individuellen WOPiXX-Programme direkt mit CRTBNDRPG (Auswahl 14 in PDM) kompiliert werden.
Bei der Verwendung von individuellen H-Bestimmungen muss folgendes beachtet werden:

Umwandlung mit CRTBNDRPG (RPG-Binderprogramm erstellen)

• Da aus WOPiXX-Programmen ILE-Prozeduren aufgerufen werden, dürfen die Programme nicht in der Default-Aktivierungsgruppe ausgeführt werden. → Aus diesem Grund muss die Option DFTACTGRP (Standardaktivierungsgruppe) in dem Compile-Befehl CRTBNDRPG auf *NO gestellt werden.
• Individuelle WOPiXX-Programme müssen in der gleichen Aktivierungsgruppe wie das steuernde Dirweb-Programm laufen. → Deshalb muss die Option ACTGRP (Aktivierungsgruppe) im Compile-Befehl mit *CALLER angegeben werden.
• Die Service-Programme, in denen die WOPiXX-Funktionen hinterlegt sind, sind in Binderverzeichnis WXBNDDIR hinterlegt. → Aus diesem Grund muss bei Kompilierung mit CRTBNDRPG zumindest das Binderverzeichnis WXBNDDIR in der Option BNDDIR (Binderverzeichnis) angegeben werden.
  Falls zusätzlich auch Directweb-Prozeduren in den individuellen CGI-Programmen verwendet werden sollen, muss auch das Binderverzeichnis DWBNDDIR in der Option BNDDIR angegeben werden.

Anstatt den Compile-Befehl anzupassen, können die notwendigen Informationen auch in den H-Bestimmungen hinterlegt werden. Die Kompilierung kann anschließend über CRTBNDRPG ohne Anpassung erfolgen.

Bei Programmen, die embedded SQL beinhalten erfolgt die Kompilierung über den Befehl CRTSQLRPGI (SQL ILE RPG-Objekt erstellen). Dieser Befehl hat keine Optionen um die Aktivierungsgruppe oder Binderverzeichnisse vorzugeben. Deshalb müssen bei Programmen mit embedded SQL die benötigten Informationen in den H-Bestimmungen hinterlegt werden.

H-Bestimmungen

• Das Schlüssel-Wort DFTACTGRP in den H-Bestimmungen überschreibt zur Compile-Zeit den Eintrag in Option DFTACTGRP im Compile-Befehl CRTBNDRPG.
  Werden H-Bestimmungen verwendet, sollte DFTACTGRP(*NO) angegeben werden.

• Das Schlüssel-Wort ACTGRP in den H-Bestimmungen überschreibt zur Compile-Zeit den Eintrag in Option ACTGRP im Compile-Befehl CRTBNDRPG.
  Werden H-Bestimmungen verwendet sollte ACTGRP(*CALLER) angegeben werden.

• Werden im Schlüssel-Wort BNDDIR in den H-Bestimmungen Binderverzeichnisse angegeben, wird die Option im BNDDIR im Compile-Command nicht überschrieben, sondern die in den H-Bestimmungen hinterlegten Binderverzeichnisse werden zusätzlich zu den im Compile-Befehl hinterlegten Binderverzeichnisse verwendet.
  Werden H-Bestimmungen verwendet, dann sollte zumindest das Binderverzeichnis WXBNDDIR angegeben werden. Sofern auch Directweb-Prozeduren aufgerufen werden sollten, sollte zusätzlich das Binderverzeichnis DWBNDDIR angegeben werden.
  Die Binderverzeichnisse müssen im Schlüssel-Wort BNDDIR in Hochkommata und in Großbuchstaben und durch Kommata getrennt angegeben werden.

D-Bestimmungen: Copystrecke WX_PROTO

Alle Prototypen (incl. Referenz-Datenstrukturen) für die WOPiXX-Prozeduren sind in der Copy-Strecke WOPIX/QPROLESRC(WX_PROTO) zusammengefasst.

Damit stehen alle Prozeduren zur Verfügung, unabhängig davon, ob sie originär WOPiXX- oder directweb- Prozeduren sind. Im Detail sähe das so aus:

• Die Prototypen für die WOPiXX-Prozeduren sind in Teildateien mit dem gleichen Namen wie die Quelle, in der die Prozedur codiert wurde, in der Datei QPROLESRC in der Bibliothek WOPIX hinterlegt.
• Die Prototypen für Directweb-Prozeduren sind in Teildateien mit dem gleichen Namen wie die Quelle, in der die Prozedur codiert wurde, in der Datei QPROLESRC in der Bibliothek DIRWEB hinterlegt.

In allen Teildateien, in denen Prototypen definiert werden, werden die Copy-Strecken mit den Feld-Referenzen, die zur Definition der Parameter-Felder verwendet wurden, integriert. Damit ist eine zusätzliche Einbindung der Feld-Referenzen im WOPiXX-Programm nicht erforderlich.

Alle Prototypen und Referenz-Datenstrukturen sind durch Compiler-Direktiven bedingt, so dass eine (versehentliche) Mehrfacheinbindung der gleichen Copy-Strecke bzw. Datenstruktur nicht zu Problemen führtInhaltsübersicht

Bitte beachten Sie die folgenden Hinweise, damit Ihre RPGWX-Programme sauber umgewandelt werden können:

Einzubindende Copystrecken

Es gibt zwei Copystrecken, die in jedes Anwendungsprogramme eingebunden werden müssen:

  /INCLUDE QCPYLESRC,RX_HSPECS  
  /INCLUDE QPROLESRC,WX_PROTO   

Die Copystrecken sind zum Teil noch in Fixed-Form RPG geschrieben. Sie können aber problemlos mit Free Format RPG-Quellen (auch in Full-Free) eingebunden werden.

Die von Toolmaker zur Verfügung gestellten Copy-Strecken können wahlweise mit /COPY oder /INCLUDE in die individuellen Quellen eingebunden werden.

Der Unterschied zwischen beiden Angaben liegt darin wie der SQL-Precompiler die Copy-Strecken behandelt.

• Bei Verwendung von /COPY wird die Copy-Strecke vom SQL-Precompiler aufgelöst,
• Bei Einbindung mit /INCLUDE wird sie vom SQL-Precompiler übergangen.

Dies hat besonders bei verschachtelten Copy-Strecken Konsequenzen, da er SQL Precompiler verschachtelte Copy-Strecken nicht unbedingt verarbeiten kann.

Kompatibilität mit WOPiXX (Vorgängersystem von RPGWX)

In Anwendungsprogrammen, die unter WOPiXX ausgeführt werden waren diese Copystrecken erforderlich:

• RPGWX/QCPYLESRC
  • WX_HSPECS
  • WX_FLDREF
  • WX_HCOPYR
• WOPIX/QPROLESRC
  • WX_PROTO

Die Copystrecken existieren für die Kompatiblität weiterhin und können weiterhin verwendet werden.

Es ist empfohlen, neue Quellen an RPGWX anzpassen und bestehende Quellen bei einer Überarbeitung anzupassen.

Referenzierung und Prototypen

Um Probleme mit unterschiedlichen Definitionen zu vermeiden, und um Änderungen (z.B. Feldlänge oder Anzahl Elemente einer Feldgruppe) ohne Anpassungen zu ermöglichen, wird empfohlen alle individuellen Variablen, über die Informationen mit den RPGWX-Funktionen ausgetauscht werden, über die Referenzen zu definieren.

H-Bestimmungen in HX_HSPECS

Optional. Es wird empfohlen, die Copy-Strecke WX_HSPECS zu verwenden.

• Wird die Copy-Strecke WX_HSPECS verwendet, können die individuellen RPGWX-Programme direkt mit CRTBNDRPG (Auswahl 14 in PDM) kompiliert werden.
• Wird die Copy-Strecke nicht verwendet, muss sichergestellt werden, dass das RPGWX-Programm mit Aktivierungsgruppe *CALLER erstellt wird und das Binderverzeichnis WXBNDDIR im Binderschritt verwendet wird.

Wenn individuelle Anforderungen an H-Bestimmungen bestehen, dann beachten Sie bitte den Abschnitt Individuelle Anpassung der H-Bestimmungen.

D-Bestimmungen: Copystrecke WX_PROTO

Alle Prototypen (incl. Referenz-Datenstrukturen) für die RPGWX-Prozeduren sind in der Copy-Strecke WOPIX/QPROLESRC(WX_PROTO) zusammengefasst. Um sinnvoll RPGWX-Funktionen nutzen zu können muss diese Copy-Strecke verwendet werden.

Weitere Informationen zu dieser Copystrecke finden Sie im Abschnitt Deklarationen in der Copystrecke WX_PROTO.

D-Bestimmungen: Copystrecke WX_FLDREF

In dieser Copystrecke sind alle Datenstrukturen und Felder hinterlegt.Hierzu gehören die im Abschnitt Referenz-Datenstrukturen für lange Text-Felder beschriebenen Referenz-Variablen.

Die Referenz-Felder und –Datenstrukturen sind bis einschließlich Release V5R4 mit dem Schlüsselwort BASED definiert, ab Release 6.1 mit Schlüssel-Wort TEMPLATE, d.h. die Felder- und Datenstrukturen dürfen/können nur zur Referenzierung verwendet werden und dürfen nicht direkt angesprochen werden.

Copyright: Copystrecke WX_HCOPYR

In der Copy-Strecke WX_HCOPYR in Datei QCPYLESRC in Bibliothek WOPIX ist das Copyright hinterlegt.

Diese Copy-Strecke ist in der Copy-Strecke WX_HSPECS integriert.

In der ausgelieferten Copy-Strecke sind aktuell die Toolmaker-Daten hinterlegt. Für die eigenen Programme können die Daten vom Programmierer überschieben werden. Dabei sollte jedoch berücksichtigt werden, dass bei einem Upgrade die Copy-Strecke ausgetauscht wird und damit die individuell geänderten Daten verloren gehen.

/IF NOT DEFINED(HCopyRight)
/DEFINE HCopyRight
H COPYRIGHT('(C) Toolmaker Advanced Efficiency (www.toolmaker.de)')
/ENDIF

Source Code 5: Copy-Strecke WX_HCOPYR

...

Im folgenden Beispiel werden die Copyright-Informationen im individuellen WOPiXXRPGWX-Programm deaktiviert und durch die eigenen Daten ersetzt.

...

Source Code 6: Austausch von Copyright Informationen

Beispiele für das Einbinden der relevanten Copystrecken

FixedForm RPG

************************************************************************
* H - H E A D E R S P E C I F I C A T I O N S
************************************************************************
* Copy-Strecke - Optional
H/INCLUDE QCPYLESRC,WX_HSPECS
***********************************************************************
* F - F I L E S P E C I F I C A T I O N S
************************************************************************
F**** Globale Datei-Definitionen für Native I/O
************************************************************************
* D – D E F I N I T I O N S P E C I F I C A T I O N S
************************************************************************
* PROTOTYPING
*---------------------------
* Folgende Copy-Strecke abh. vom Release für embedded SQL erforderlich
D/COPY QCPYLESRC,D_FLDREF
* Copy-Strecke - Erforderlich
D/INCLUDE QPROLESRC,WX_PROTO
*
* PROCEDURE INTERFACE
*---------------------------
**** Keine Parameter für WOPiXXRPGWX-Programme
* GOBALE FELD-DEFINITONEN
*---------------------------
D**** Globale Variablen und Datenstruktur-Definitionen
************************************************************************
* M A I N P R O C E D U R E
************************************************************************
C**** Globale C-Bestimmungen – Hauptprogramm
C**** inklusive Subroutines (sofern erforderlich)
************************************************************************
* I N T E R N A L P R O C E D U R E S
************************************************************************
**** Interne Prozeduren

Copy-Strecken und Grob-Aufbau von WOPiXXRPGWX-Programmen

FreeForm RPG

**FREE

/COPY QCPYLESRC,WX_HSPECS
/COPY QCPYLESRC,WX_FLDREF

...

Referenz-Datenstrukturen für lange Text-Felder

Da physische (Feld-Referenz-)Dateien nur bis zu einer maximalen Satz-Länge von 32740 Byte definiert werden können, wurden für längere Text-Felder separate Referenz-Datenstrukturen angelegt.
Die folgenden Referenz-Datenstrukturen wurden definiert. Diese Definitionen sind in der Copystrecke WOPIX/QCPYLESRC(WX_FLDREF) hinterlegt.

Referenz-Datenstruktur FLDREFLA – Lange alphanumerische Referenz-Text-Felder

In der Referenz-Datenstruktur wurden alphanumerische Referenz-Text-Felder mit fixer und variabler Länge hinterlegt.

Die Feldlänge wurde auf 16350 Bytes/Zeichen beschränkt, da bei Verarbeitung mit (embedded) SQL die maximale Länge eines Double-Byte-Strings auf 16383 Zeichen beschränkt ist und ein problemloser Austausch (ohne Abschneiden) zwischen Single- und Double-Byte-Texten erfolgen soll.

/IF NOT DEFINED(FldRefLA)
/DEFINE FldRefLA
D FldRefLA DS Qualified based(DummyPtr)
D FixLen 16350A
D VarLen 16350A Varying
/ENDIF

Referenz-Datenstruktur FldRefLA

Im folgenden Beispiel wird ein Text-Feld basierend auf dem Datenstruktur-Unterfeld VARLEN in der Datenstruktur FLDREFLA definiert

D MyText S Like(FldRefLA.VarLen)
/Free
MyText = 'Dies ist eine Nachricht';
/End-Free

Definition und Verwendung von langen alphanumerischen Texten

Referenz-Datenstruktur FLDREFMA – mittlere alphanumerische Referenz-Text-Felder

In der Referenz-Datenstruktur wurden alphanumerische Referenz-Text-Felder mit fixer und variabler Länge hinterlegt.

Die Feldlänge wurde auf 4096 Zeichen festgelegt, um eine Zwischenstufe zwischen den langen (Referenz-)Texten (16350 Zeichen) und den kurzen (Referenz-)Texten (256 Zeichen) zu schaffen.

/IF NOT DEFINED(FldRefMA)
/DEFINE FldRefMA
D FldRefMA DS Qualified based(DummyPtr)
D FixLen 4096A
D VarLen 4096A Varying
/ENDIF

Referenz-Datenstruktur FLDREFMA

Im folgenden Beispiel wird ein Text-Feld basierend auf dem Datenstruktur-Unterfeld VARLEN in der Datenstruktur FLDREFMA definiert

D MyText S Like(FldRefMA.VarLen)
/Free
MyText = 'Dies ist eine Nachricht';
/End-Free

Definition und Verwendung von mittleren alphanumerischen Texten

Referenz-Datenstruktur FLDREFLU – lange Unicode Referenz-Text-Felder

In der Datenstruktur FLDREFLU werden Unicode-Referenz-Textfelder mit fixer und variabler Länge hinterlegt.

Die Länge der Datenstruktur-Unterfelder entspricht der Länge der Datenstruktur-Unterfelder in der Referenz-Datenstruktur FLDREFLA.

/IF NOT DEFINED(FldRefLU)
/DEFINE FldRefLU
D FldRefLU DS Qualified based(DummyPtr)
D FixLen 16350C
D VarLen 16350C Varying
/ENDIF

Referenz-Datenstruktur FLDREFLU

Im folgenden Beispiel wird ein Text-Feld basierend auf dem Datenstruktur-Unterfeld VARLEN in der Datenstruktur FLDREFLU definiert und verwendet.

D MyText S Like(FldRefLU.VarLen)
/Free
MyText = %UCS2('Dies ist eine Nachricht');
/End-Free

Definition und Verwendung von langen Unicode-Texten

Referenz-Datenstruktur FLDREFMU – mittlere Unicode Referenz-Text-Felder

In der Datenstruktur FLDREFMU werden Unicode-Referenz-Textfelder mit fixer und variabler Länge hinterlegt.

Die Länge der Datenstruktur-Unterfelder entspricht der Länge der Datenstruktur-Unterfelder in der Referenz-Datenstruktur FLDREFMA.

/IF NOT DEFINED(FldRefMU)
/DEFINE FldRefMU
D FldRefMU DS Qualified based(DummyPtr)
D FixLen 4096C
D VarLen 4096C Varying
/ENDIF

Referenz-Datenstruktur FLDREFMU

Im folgenden Beispiel wird ein Text-Feld basierend auf dem Datenstruktur-Unterfeld VARLEN in der Datenstruktur FLDREFMU definiert und verwendet.

D MyText S Like(FldRefMU.VarLen)
/Free
MyText = %UCS2('Dies ist eine Nachricht');
/End-Free

Definition und Verwendung von mittleren Unicode-Texten

Bibliotheksliste

Zur Umwandlung müssen die Bibliotheken WOPIX und DIRWEB in der Bibliotheksliste vorhanden sein. Wir empfehlen die folgende Reihenfolge:

1. QTEMP
2. <ihre bibliothek1 - n>
3. WOPIX
4. DIRWEB
5. QGPL

Umwandlung

WOPiXXRPGWX-Programme können direkt mit dem Befehl CRTBNDRPG (bzw. CRTSQLPGMI) umgewandelt werden, sofern nur ILE-Prozeduren von WOPiXX RPGWX oder Directweb aufgerufen werden.

Sofern aufgrund der individuellen Programmierung eine zweistufige Kompilierung erforderlich sein sollte (z.B. wenn mehrere Module gebunden werden sollen), so muss der Programmierer dafür sorgen, dass im Binderschritt (CRTPGM) die Aktivierungsgruppe *CALLER und das Binderverzeichnis WXBNDDIR angegeben werden.