Subdatei-APIs

Subdatei-APIs in Ihrem Serviceprogramm bearbeiten die Sätze aus einer Subdatei, die in der IBM i-Webkomponente "Tabelle" auf einer JSP-Seite angezeigt werden.

Die Subdatei ist ein Objekttyp *USRSPC in der Bibliothek QTEMP des IBM i-Jobs in der aktuellen Sitzung. Dieser Bereich muss denselben Namen wie die Webkomponente "Tabelle" auf der JSP haben. Bevor Sie Operationen für die Subdatei ausführen können, z. B. Sätze hinzufügen, müssen Sie die API QdtsInitSF im Serviceprogramm QDTSSFL aufrufen, um die Subdatei zu initialisieren. Diese API erstellt den Bereich mit dem angegebenen Namen in der Bibliothek QTEMP des Jobs. Beim ersten Laden der JSP-Seite mit der Webkomponente "Tabelle" und vor dem Anzeigen ruft sie die Prozedur INIT des Serviceprogramms auf, das auf der Registerkarte "Parameter" der Attributsicht der Tabelle definiert ist. Sie verwenden diese Prozedur, einen Aufruf der API QdtsInitSF zum Erstellen und Initialisieren des Subdateibereichs, gefolgt von einem Aufruf der API QdtsAppendSF zum Hinzufügen von Sätzen zur Subdatei.

Die Prozedur INIT wird nur beim ersten Anzeigen der JSP-Seite aufgerufen. Beim erneuten Anzeigen der JSP-Seite wird sie nicht aufgerufen.

Wenn Sie den Inhalt der Subdatei ändern müssen, nehmen Sie diese Änderungen in den Webinteraktionen vor, bevor die JSP-Seite mit der Subdatei angezeigt wird. Bevor die JSP-Seite angezeigt wird, ruft sie immer die aktuellen Daten aus dem Benutzeradressbereich ab.

Anmerkung: Da die Subdatei ein Objekt in QTEMP ist, dürfen Sie keine zwei Subdateikomponenten mit demselben Namen in Ihrer Anwendung haben.

Die Namen der Subdatei-APIs und die Operation, die jede API ausführt, werden unten beschrieben.

Tabelle 1. Subdatei-APIs - Namen und Operationen
API-Name API-Operation
QdtsAppendSF Satz hinzufügen
QdtsChainSF Verkettung zu einem Satz
QdtsClearSF Inhalt der Subdatei löschen
QdtsCountSF Die Anzahl der Subdateisätze ausgeben
QdtsDeleteSF Subdateisatz löschen
QdtsInitSF Subdatei initialisieren
QdtsReadcSF Ausgewählten Satz lesen
QdtsSetDspAtrSF Anzeigeattribute für jede Subdateizelle definieren
QdtsSetNxtChgSF Nächsten geänderten Satz definieren
QdtsSetRcdNbrSF Aktuelle Satznummer definieren
QdtsUpdateSF Satz aktualisieren

Subdateiserviceprogramm QDTSSFL

Für die Verwendung der APIs müssen Sie sicherstellen, dass Ihr Serviceprogramm mit dem Subdateiserviceprogramm QDTSSFL in Bibliothek QSYS auf Ihrem IBM i-Host verknüpft wurde. Ab Version 5 Release 3 befindet sich dieses Serviceprogramm in Bibliothek QSYS. Bei Version 5 Release 2 und Version 5 Release 1 befindet sich QDTSSFL in PTF SI09790 bzw. PTF SI09791. Sie müssen den PTF anlegen, der für Ihr Release des Betriebssystems gültig ist, um Serviceprogramm QDTSSFL zu erhalten.

Führen Sie in der Entwicklungsumgebung folgende Schritte aus:

  1. Binden Sie das Benutzerprogramm, das den API-Aufruf der Webkomponente "Tabelle" ausführt, an Bibliotheksname/QDTSSFL.SRVPGM.
Anmerkung: Für Benutzer, die Ihre Serviceprogramme mit einer früheren Version gebunden haben:
  1. Alle vorhandenen, an QSYS/QDTSSFL gebundenen Programme müssen erneut an das neue Serviceprogramm Bibliotheksname/QDTSSFL gebunden werden.

Operationen und Namen der Subdatei-APIs

In den folgenden Abschnitten wird jede Subdatei-API beschrieben. Außerdem sind Syntax, Parameter, Programmprototyp und jeweils ein Beispiel aufgeführt. (In COBOL-Programmbeispiel unter Verwendung von Subdatei-APIs finden Sie ein Beispiel, wie die Subdatei-APIs in einem ILE COBOL-Programm codiert werden.)

Anmerkung: Für alle Subdatei-APIs wird der Rückkehrcode -2 zurückgegeben, wenn der Benutzeradressbereich nicht erstellt wurde. Dieser Rückkehrcode wird z. B. zurückgegeben, wenn Sie einen Satz an die Subdatei anfügen wollen, aber die API QdtsInitSF noch nicht aufgerufen haben.

Der Subdatei einen Satz hinzufügen - QdtsAppendSF

Verwenden Sie diese API, um der Subdatei einen Satz hinzuzufügen. Sätze weden am Ende der Subdatei hinzugefügt.

Da Subdateisätze in ein Objekt *USRSPC eingefügt werden, ist die Anzahl der Sätze durch die maximale Größe eines Objekts *USRSPC und durch die Länge der hinzugefügten Sätze begrenzt. Wird der maximale Wert erreicht, wird der Wert -1 zurückgegeben, wenn Sie versuchen, einen Satz anzufügen.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsAppendSF(SFLName: pRcd: length)

Parameter:

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D append          PR            10I 0 Extproc('QdtsAppendSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D append          PR            10I 0 Extproc('QdtsAppendSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value
D SFLName      S                    Inz('SFL1')
D Record          DS
D  Name                         20A
D  City                         30A
D RC              S             10I 0
 *

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
                    Eval   Name='Larry'
                    Eval   City='Pickering'
                    Eval   rc=append(SFLName: %Addr(Record): %Size(Record))

Verkettung zu einem spezifischen Subdateisatz - QdtsChainSF

Mit dieser API rufen Sie einen bestimmten Satz aus der Subdatei ab, indem Sie die relative Satznummer des gewünschten Satzes übergeben.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsChainSF(SFLName: pRcd: length: RRN)

Parameter:

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D chain           PR            10I 0 Extproc('QdtsChainSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value
D   rrn                         10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 

D chain           PR            10I 0 Extproc('QdtsChainSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value
D   rrn                         10I 0 Value
D SFLName      S                    Inz('SFL1')
D Record          DS
D  Name                         20A
D  City                         30A
D RC              S             10I 0
D RRN             S             10I 0
 *

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
                    Eval   RRN = 3
                    Eval   RC=chain(SFLName: %Addr(Record): %Size(Record): RRN)
 * Name = Donna (possibly)
 * City = Guelph (possibly)

Inhalt der Subdatei löschen - QdtsClearSF

Verwenden Sie diese API, um alle Sätze aus der Subdatei zu löschen. Sie können diese API aufrufen, wenn Sie die Subdatei jeweils seitenweise füllen.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsClearSF(SFLName)

Parameter:

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D clear           PR            10I 0 Extproc('QdtsClearSF')
D SFLName                       10A   Const

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D clear           PR            10I 0 Extproc('QdtsClearSF')
D   SFLName                     10A Const
D RC              S             10I 0
D SFLName           S             10A   Inz('SFL1')
 *

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
                    Eval   RC=clear(SFLName)

Anzahl der Subdateisätze zurückgeben - QdtsCountSF

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   count = QdtsCountSF(SFLName)

Parameter:

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D getCount          PR            10I 0 Extproc('QdtsCountSF')
D SFLName                      10A   Const
D count                           10I 0

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D getCount          PR            10I 0 Extproc('QdtsCountSF')
D SFLName                      10A   Const
D count             S             10I 0
D SFLName           S             10A   Inz('SFL1')
 *

CL0N01Factor1+++++++Opcode&Extended-factor2+++++++++++++++++++++++++++++
                    Eval   count =getCount(SFLName)

Subdateisatz löschen - QdtsDeleteSF

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC = QdtsDeleteSF(SFLName:RRN)

Parameter:

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D delrec           PR           10I 0 Extproc('QdtsDeleteSF')
D SFLName                      10A   Const

D rrn                          10I 0

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D delrec           PR           10I 0 Extproc('QdtsDeleteSF')
D SFLName                      10A   Const
D RRN                           10I 0
D RC              S             10I 0
D SFLName           S             10A   Inz('SFL1')
 *

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
                    Eval   RC=delrec(SFLName: 3)

Subdatei initialisieren - QdtsInitSF

Verwenden Sie diese API, um die Subdatei für die erste Verwendung zu initialisieren. Der Aufruf dieser API wird typischerweise in die Prozedur INIT gestellt, die aufgerufen wird, wenn die JSP, die die Subdatei enthält, zum ersten Mal angezeigt werden soll.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsInitSF(SFLName: pReserved: length)

Parameter:

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D initSF          PR            10I 0 Extproc('QdtsInitSF')
D   SFLName                     10A Const
D   pReserved                     *   Value
D   len                         10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D initSF          PR            10I 0 Extproc('QdtsInitSF')
D   SFLName                     10A Const
D   pReserved                     *   Value
D   len                         10I 0 Value
D SFLName      S                    Inz('SFL1')
D rsvd            S             10A
D RC              S             10I 0
 *

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
                    Eval   RC=initSF(SFLName: %Addr(rsvd): %Size(Record))

Ausgewählten Satz lesen - QdtsReadcSF

Verwenden Sie diese API, um einen Satz zu lesen, der in der Subdatei ausgewählt wurde. Sätze in einer Subdatei werden ausgewählt, indem der Radioknopf oder das Markierungsfeld, der bzw. das dem jeweiligen Subdateisatz zugeordnet ist, ausgewählt wird. Wenn der Subdateisatz über Webkomponenten "Eintragsfeld", "Markierungsfeld", "Kombiniertes Feld" oder "Textbereich" verfügt und wenn sich die Werte dieser IBM i-Webkomponenten ändern, gibt diese API außerdem diese Sätze zurück.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RRN=QdtsReadcSF(SFLName: pRcd: length: startRRN)

Parameter:

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D readc           PR            10I 0 Extproc('QdtsReadcSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D readc           PR            10I 0 Extproc('QdtsReadcSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value
D SFLName      S                    Inz('SFL1')
D Record          DS
D  Name                         20A
D  City                         30A
D RRN             S             10I 0
 *

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
                    Eval   RRN=readc(SFLName: %Addr(Record): %Size(Record))
 * Name = Donna (possibly)
 * City = Guelph (possibly)
 * RRN = 3 (possibly)

Zellenattribute definieren - QdtsSetDspAtrSF

Verwenden Sie diese API, um Anzeigeattribute für jede Zelle der Subdatei zu definieren.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsSetDspAtrSF(SFLName, RRN, ColNbr, Attribute, Length)

Parameter

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D setAtr          PR            10I 0 Extproc('QdtsSetDspAtrSF')
D SFLName                      10A   Const
D   recordRRN                   10I 0 Value
D   colNbr                      10I 0 Value
D   style                         *   Value
D   styleLen                    10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D setAtr          PR            10I 0 Extproc('QdtsSetDspAtrSF')
D SFLName                      10A   Const
D   recordRRN                   10I 0 Value
D   colNbr                      10I 0 Value
D   style                         *   Value
D   styleLen                    10I 0 Value 
D*
D limitWarn       S             10A   Inz('limitwarn')
D ordersSFL       S             10A   Inz('ORDERSSFL')

 
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
 * If the balance is greater than the credit limit for
 * the record just read from the subfile (record number is in 'curRec')
 * set the style class for the balance column (column 3) to the limitwarn
 * class to hilite that column      
 * In the style sheet style 'limitwarn' would be defined as follows:
 *
 *    .limitwarn {color: red; background-color: yellow;}
 *             
C	      	  If     balance > creditLimit
C                   Eval   rc = setAtr(ordersSFL: curRec: 3: limitWarn:
C                                 %Size(limitWarn)
C                   EndIf

Nächsten geänderten Satz definieren - QdtsSetNxtChgSF

Verwenden Sie diese API, um den nächsten geänderten Satz in der Subdatei zu definieren.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsSetNxtChgSF(SFLName, RRN)

Parameter

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D setNxtChg       PR            10I 0 Extproc('QdtsSetNxtChgSF')
D SFLName                      10A   Const
D   recordRRN                   10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D setNxtChg       PR            10I 0 Extproc('QdtsSetNxtChgSF')
D SFLName                      10A   Const
D   recordRRN                   10I 0 Value
D*
D limitWarn       S             10A   Inz('limitwarn')
D ordersSFL       S             10A   Inz('ORDERSSFL')

 
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
 * If the option is not a '1', set the next change indicator so this 
 * record will be read on a subsequent READC
 * set the style class for the balance column (column 3) to the limitwarn
 * class to hilite that column      
 * In the style sheet style 'limitwarn' would be defined as follows:
 *
C                   Eval   rrn = readC(ordersSFL: sflRcd: %Size(sflRcd))
 *
C                   If     opt <> '1'
C                   Eval   rc = setNxtChg(orderSFL: rrn)
C                   EndIf

Aktuelle Satznummer definieren - QdtsSetRcdNbrSF

Verwenden Sie diese API, um die aktuelle Satznummer in der Subdatei zu definieren. Die Subdatei wird auf die Seite positioniert, die den durch RRN angegebenen Satz enthält.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsSetRcdNbrSF(SFLName, RRN)

Parameter

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D setRcdNbr       PR            10I 0 Extproc('QdtsSetRcdNbrSF')
D SFLName                      10A   Const
D   recordRRN                   10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D setRcdNbr       PR            10I 0 Extproc('QdtsSetRcdNbrSF')
D SFLName                      10A   Const
D   recordRRN                   10I 0 Value
 *
D ordersSFL       S             10A   Inz('ORDERSSFL')
 
CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
 * Position the subfile to the first page
 *
C                   Eval   rc = setRcdNbr(orderSFL: 1)

Satz aktualisieren - QdtsUpdateSF

Verwenden Sie diese API, um einen bestehenden Satz in der Subdatei zu aktualisieren. Es ist nicht erforderlich, den Satz vor dem Aktualisieren zu lesen.

Syntax:

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++

                    Eval   RC=QdtsUpdateSF(SFLName: pRcd: length, RRN)

Parameter

Prototyp:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D update          PR            10I 0 Extproc('QdtsUpdateSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value
D   rrn                         10I 0 Value

Beispiel:

DName+++++++++++ETDsFrom+++To/L+++IDc.Keywords+++++++++++++++++++++++++++++ 
D update          PR            10I 0 Extproc('QdtsUpdateSF')
D   SFLName                     10A Const
D   pRcd                          *   Value
D   len                         10I 0 Value
D   rrn                         10I 0 Value
D SFLName      S                    Inz('SFL1')
D Record          DS
D  Name                         20A
D  City                         30A
D RC              S             10I 0
D RRN             S             10I 0
 *

CL0N01Factor1+++++++Opcode&ExtExtended-factor2+++++++++++++++++++++++++++++
                                        Eval   Name = 'Donna'
                                        Eval   City = 'Guelph'
                    Eval   RC = update(SFLName: %Addr(Record): %Size(Record): 3)

Feedback