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.
Les noms de ces API et les opérations effectuées par chacune d'entre elles sont présentés ci-dessous.
| 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 |
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 :
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.)
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))
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)
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)
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)
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)
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))
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)
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
Si vous spécifiez plusieurs attributs pour une cellule, veillez à ce que ceux-ci soient séparés par un espace. Par exemple, "*PC *RI" indique que le curseur sera positionné dans la cellule et qu'elle sera en surbrillance. Si *NONE est spécifié, en plus d'autres attributs, aucun effet ne sera constaté.
Vous pouvez également définir votre propre attribut d'affichage. Les attributs définis par l'utilisateur sont soumis aux règles suivantes :
| Attribut | Composants Web concernés |
|---|---|
| *PC | Entrée de données, zone de saisie |
| *PR | Tous les composants, sauf Image et Libellé, et la colonne de sélection |
| *RI | Tous |
| *HI | Tous les composants, sauf Image et la colonne de sélection |
| *ND | Tous les composants, sauf la colonne de sélection |
| *UL | Tous les composants, sauf Image et la colonne de sélection |
| *NONE | Tous |
| Défini par l'utilisateur | Tous |
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
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
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)
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)