API de sous-fichier

Les API de sous-fichier de votre programme de service manipulent les enregistrements d'un sous-fichier qui apparaissent dans le composant Web Table IBM® i d'une page JSP.

Le sous-fichier est un type d'objet *USRSPC appartenant à la bibliothèque QTEMP du travail IBM i dans la session en cours. Cet espace doit avoir le même nom que le composant Web Table de la page JSP. Avant d'appliquer une quelconque opération au sous-fichier, telle que l'ajout d'un enregistrement, vous devez d'abord appeler l'API QdtsInitSF pour initialiser le sous-fichier dans le programme de service QDTSSFL. Cette API crée l'espace avec le nom donné dans la bibliothèque QTEMP du travail. Lorsque la page JSP avec le composant Web Table vient d'être chargée, elle appelle, avant de s'afficher, la procédure INIT du programme de service qui est définie dans l'onglet Paramètres de la vue Attributs de la table. Vous devez donc insérer cette procédure, un appel à l'API QdtsInitSF pour créer et initialiser l'espace de sous-fichier, suivi d'un appel à l'API QdtsAppendSF pour ajouter des enregistrements au sous-fichier.

Notez que la procédure INIT est appelée uniquement la première fois que la page JSP doit s'afficher, et non, en cas de réaffichage.

Si vous devez modifier le contenu du sous-fichier, vous devez effectuer ces modifications dans les interactions Web, avant que la page JSP associée à ce sous-fichier ne soit affichée. Avant que la page JSP ne s'affiche, elle extrait toujours les données en cours de l'espace utilisateur.

Remarque : Etant donné que le sous-fichier est un objet de QTEMP, vous ne devriez pas avoir deux composants Sous-fichier de même nom dans votre application.

Les noms de ces API et les opérations effectuées par chacune d'entre elles sont présentés ci-dessous.

Tableau 1. API de sous-fichier : noms et opérations
Nom Opération
QdtsAppendSF Ajout d'un enregistrement
QdtsChainSF Chaînage à un enregistrement
QdtsClearSF Effacement d'un sous-fichier
QdtsCountSF Décompte des enregistrements de sous-fichier
QdtsDeleteSF Suppression d'un enregistrement de sous-fichier
QdtsInitSF Initialisation du sous-fichier
QdtsReadcSF Lecture d'un enregistrement sélectionné
QdtsSetDspAtrSF Définition des attributs d'affichage pour chaque cellule de sous-fichier
QdtsSetNxtChgSF Définition du prochain enregistrement modifié
QdtsSetRcdNbrSF Définition du numéro d'enregistrement en cours
QdtsUpdateSF Mise à jour d'un enregistrement

Programme de service de sous-fichier QDTSSFL

Avant d'utiliser les API, assurez-vous que votre programme de service a été lié au programme de service de sous-fichier QDTSSFL dans la bibliothèque QSYS sur l'hôte IBM i. Proposé dans la version 5.3, ce programme de service est inclus dans la bibliothèque QSYS. Pour les versions 5.2 et 5.1, QDTSSFL est fourni respectivement avec la PTF SI09790 et la PTF SI09791. Vous devez appliquer la PTF spécifique à la version de votre système d'exploitation pour utiliser le programme de service QDTSSFL.

Pour l'environnement de développement :

  1. Associez le programme utilisateur qui génère l'appel d'API du composant Web Table à nom_bibliothèque/QDTSSFL.SRVPGM.
Remarque : Pour les utilisateurs qui ont associé leurs programmes de service à une version précédente :
  1. Tous les programmes existants associés à QSYS/QDTSSFL doivent être de nouveau liés au nouveau programme de service nom_bibliothèque/QDTSSFL.

Opérations et noms d'API de sous-fichier

Les sections suivantes décrivent toutes les API de sous-fichier et incluent la syntaxe, les paramètres, le prototype de programme et un exemple pour chaque API. (Pour avoir un exemple du code utilisé pour les API de sous-fichier dans un programme ILE COBOL, voir Exemple de programme COBOL utilisant des API de sous-fichier.)

Remarque : Pour toutes les API de sous-fichier, le code retour -2 est renvoyé si l'espace utilisateur n'a pas été créé. Par exemple, ce code retour est renvoyé si vous tentez d'ajouter un enregistrement au sous-fichier, mais n'avez pas encore appelé l'API QdtsInitSF.

Ajout d'un enregistrement dans le sous-fichier - QdtsAppendSF

Cette API ajoute un enregistrement dans le sous-fichier. Les enregistrements sont ajoutés à la fin du sous-fichier.

Etant donné que les enregistrements de sous-fichier sont insérés dans un objet *USRSPC, le nombre limite d'enregistrements est déterminé par la taille maximale de l'objet *USRSPC et la longueur des enregistrements à ajouter. Si la taille maximale est atteinte, la valeur -1 est renvoyée en cas de tentative d'ajout d'un enregistrement.

Syntaxe :

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

                    Eval   RC=QdtsAppendSF(SFLName: pRcd: length)

Paramètres :

Prototype :

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

Exemple :

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='Jacky'
                    Eval   City='Quimperlé'
                    Eval   rc=append(SFLName: %Addr(Record): %Size(Record))

Chaînage à un enregistrement de sous-fichier spécifique - QdtsChainSF

Utilisez cette API pour extraire un enregistrement donné du sous-fichier en transmettant le numéro relatif de l'enregistrement de votre choix.

Syntaxe :

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

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

Paramètres :

Prototype :

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

Exemple :

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 (possible)
 * City = Guelph (possible)

Effacement du sous-fichier - QdtsClearSF

Cette API permet de supprimer tous les enregistrements du sous-fichier. Vous pouvez appeler cette API si vous remplissez le sous-fichier page par page.

Syntaxe :

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

                    Eval   RC=QdtsClearSF(SFLName)

Paramètres :

Prototype :

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

Exemple :

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)

Code retour correspondant au nombre d'enregistrements de sous-fichier - QdtsCountSF

Syntaxe :

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

                    Eval   count = QdtsCountSF(SFLName)

Paramètres :

Prototype :

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

Exemple :

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)

Suppression d'un enregistrement de sous-fichier - QdtsDeleteSF

Syntaxe :

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

                    Eval   RC = QdtsDeleteSF(SFLName:RRN)

Paramètres :

Prototype :

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

D rrn                          10I 0

Exemple :

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)

Initialisation du sous-fichier - QdtsInitSF

Cette API permet d'initialiser le sous-fichier pour la première utilisation. L'appel de cette API est généralement placé dans la procédure INIT appelée la première fois où le JSP contenant le sous-fichier doit être affiché.

Syntaxe :

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

                    Eval   RC=QdtsInitSF(SFLName: pReserved: length)

Paramètres :

Prototype :

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

Exemple :

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))

Lecture d'un enregistrement sélectionné - QdtsReadcSF

Cette API permet de lire un enregistrement sélectionné dans le sous-fichier. La sélection des enregistrements dans un sous-fichier s'effectue à l'aide du bouton d'option ou de la case à cocher associée à chaque enregistrement de sous-fichier. De plus, si l'enregistrement de sous-fichier contient des zones d'entrée, des cases à cocher, des boîtes de dialogue ou des composants Web avec des zones de texte, et si les valeurs de ces composants Web IBM i changent, cette API renvoie également ces enregistrements.

Syntaxe :

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

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

Paramètres :

Prototype :

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

Exemple :

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 (possible)
 * City = Guelph (possible)
 * RRN = 3 (possible)

Définition des attributs de cellule - QdtsSetDspAtrSF

Cette API permet de définir les attributs d'affichage pour chaque cellule du sous-fichier.

Syntaxe :

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

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

Paramètres

Prototype :

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

Exemple :

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+++++++++++++++++++++++++++++ 
 * Si le solde est supérieur à la limite de crédit de l'enregistrement qui vient
 * d'être lu dans le sous-fichier (le n° d'enregistrement est dans 'curRec'),
 * attribuez la valeur limitwarn à la classe de style de la colonne Balance (colonne 3)
 * pour mettre en évidence cette colonne.      
 * Dans la feuille de style, le style 'limitwarn' sera défini comme suit :
 *
 *    .limitwarn {color: red; background-color: yellow;}
 *             
C	      	  If     balance > creditLimit
C                   Eval   rc = setAtr(ordersSFL: curRec: 3: limitWarn:
C                                 %Size(limitWarn)
C                   EndIf

Définition du prochain enregistrement modifié - QdtsSetNxtChgSF

Cette API permet de définir le prochain enregistrement modifié dans le sous-fichier.

Syntaxe :

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

                    Eval   RC=QdtsSetNxtChgSF(SFLName, RRN)

Paramètres

Prototype :

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

Exemple :

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+++++++++++++++++++++++++++++ 
 * Si l'option n'est pas '1', définissez l'indicateur de changement suivant, afin que
 * l'enregistrement soit lu dans un READC ultérieur.
 * Attribuez la valeur limitwarn à la classe de style de la colonne Balance (colonne 3)
 * pour mettre en évidence cette colonne 3.      
 * Dans la feuille de style, le style 'limitwarn' sera défini comme suit :
 *
C                   Eval   rrn = readC(ordersSFL: sflRcd: %Size(sflRcd))
 *
C                   If     opt <> '1'
C                   Eval   rc = setNxtChg(orderSFL: rrn)
C                   EndIf

Définition du numéro d'enregistrement en cours - QdtsSetRcdNbrSF

Cette API permet de définir le numéro d'enregistrement en cours dans le sous-fichier. Le sous-fichier se positionnera à la page qui contient l'enregistrement identifié par le paramètre RRN.

Syntaxe :

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

                    Eval   RC=QdtsSetRcdNbrSF(SFLName, RRN)

Paramètres

Prototype :

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

Exemple :

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+++++++++++++++++++++++++++++ 
 * Positionnez le sous-fichier à la première page.
 *
C                   Eval   rc = setRcdNbr(orderSFL: 1)

Mise à jour d'un enregistrement - QdtsUpdateSF

Cette API permet de mettre à jour un enregistrement existant du sous-fichier. Il n'est pas nécessaire de lire l'enregistrement avant de le mettre à jour.

Syntaxe :

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

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

Paramètres

Prototype :

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

Exemple :

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 = 'Laura'
                    Eval   City = 'Rennes'
                    Eval   RC = update(SFLName: %Addr(Record): %Size(Record): 3)

Commentaires en retour