Le guide Oracle Forms 9i/10g
Date de publication : Juin 2005
Les groupes d'enregistrements
Définition
Concept
Mise en oeuvre
Techniques avancées
Les groupes d'enregistrements
Définition
Un groupe d'enregistrements est un tableau PL/SQL d'enregistrements chargé en mémoire.
Il est utilisé le plus souvent pour alimenter un item de type liste ou une LOV mais peut être mis en oeuvre également pour manipuler en mémoire des jeux d'enregistrements.
Concept
Deux types de groupes d'enregistrements sont utilisables
Le groupe statique est configuré manuellement. Il faut déclarer les colonnes constituant un enregistrement ainsi que le type des colonnes.
Ce type de groupe n'est pas modifiable dans sa structure à l'exécution, mais il peut être alimenté à partir d'une requête SQL.
Le groupe dynamique prend sa structure d'une requête SQL. Sa structure peut donc être modifiée dynamiquement puisqu'elle dépend alors de la requête associée.
Un groupe d'enregistrements peut être créé dès la conception dans Forms Builder, mais également à l'exécution.
Un groupe d'enregistrements peut être partagé entre plusieurs formes dans la même session.
Mise en oeuvre
Ajouter un groupe d'enregistrements dès la conception
Dans le navigateur d'objets, cliquer le noeud Groupes d'enregistrements puis l'icône 
Un boite de dialogue permet d'indiquer si le groupe est statique ou dynamique.
Lorsque l'option dynamique est choisie, entrez le code de la requête SQL qui alimentera le groupe.
Si vous avez sélectionné l'option statique, une boite de dialogue apparaît afin de définir les colonnes ainsi que les valeurs associées
Affichez la fenêtre de propriétés du groupe (F4)
Général
Nom permet de nommer le groupe
Fonctionnel
Type de groupe d'enregistrements prend l'une des deux valeurs suivantes
Interrogation associée au groupe permet de saisir/modifier la requête SQL de création et d'alimentation du groupe
Taille d'extraction du groupe permet de définir le nombre d'enregistrements qui seront ramenés de la base à chaque fetch
Spécifications de colonnes permet de nommer et typer chaque colonne du groupe
Ce groupe d'enregistrements sera alors disponible pour alimenter un item de type liste ou une liste de valeurs (LOV)
Gestion d'un groupe d'enregistrements à l'exécution
Création d'un groupe sans requête
Pour créer dynamiquement un groupe sans requête associée, utiliser l'instruction:
Create_Group( 'nom_groupe', scope, nb_rec_ramenes ) ;
nom_groupe est le nom donné au groupe d'enregistrements (il doit être unique dans une même forme)
scope désigne le domaine de visibilité du groupe
- FORM_SCOPE (défaut) le groupe n'est visible que dans la forme en cours
- GLOBAL_SCOPE le groupe est visible par toutes les formes de l'application
nb_rec_ramenes permet d'indiquer combien d'enregistrements seront ramenés depuis la base à chaque fetch. La valeur par défaut est : 20.
Si vous constituez des groupes ramenant un nombre important d'enregistrements, adaptez cette valeur en conséquence afin de réduire le trafic réseau.
Si vous positionnez cette valeur à 0 (zéro) Forms décidera de la meilleur valeur possible pour cette option.
Définitions des colonnes du groupe
Après cette instruction, le groupe est créé, mais il ne possède encore aucune structure car les colonnes qui doivent le particulariser ne sont pas encore définies.
Pour définir les colonnes qui constitueront le groupe, utilisez l'instruction:
GROUP_COLUMN := Add_Group_Column( 'nom_groupe' | id_groupe, 'nom_colonne', type_colonne [, largeur_colonne] ) ;
La fonction retourne une variable de type GROUP_COLUMN
nom_groupe désigne le nom du groupe
id_groupe désigne l'identifiant interne pouvant être retrouvé avec la fonction Find_Group().
nom_colonne représente le nom de la colonne du groupe
type_colonne désigne le type de la colonne
- CHAR_COLUMN
- DATE_COLUMN
- LONG_COLUMN
- NUMBER_COLUMN
largeur_colonne doit être spécifié lorsque le type de la colonne est CHAR et représente la longueur maximum de la chaîne (2000 maxi)
Restrictions:
Le groupe doit exister pour pouvoir lui ajouter des colonnes
Le groupe doit être vide pour pouvoir lui ajouter des colonnes
Vous ne pouvez pas ajouter de colonne à un groupe créé avec l'instruction Create_Groupe_Form_Query()
Si la colonne CHAR représente une colonne d'une table, sa taille doit être identique à celle de la table
Il ne peut y avoir qu'une colonne de type LONG dans un groupe
Exemple:
Add_Group_Column() Declare
rg_nom VARCHAR2(15) := 'RG_EMP';
rg_id RecordGroup;
gc_id GroupColumn;
Begin
rg_id := Find_Group( rg_nom );
If Id_Null(rg_id) THEN
rg_id := Create_Group( rg_nom );
gc_id := Add_Group_Column(rg_id, 'Empno',NUMBER_COLUMN);
gc_id := Add_Group_Column(rg_id, 'Ename',CHAR_COLUMN,15);
End if ;
End ;
Ajout d'enregistrements au groupe
Le groupe étant maintenant constitué, nous pouvons lui ajouter des enregistrements.
Deux méthodes sont possible
- Ajout manuel des enregistrements
- Ajout depuis une requête
- ajout manuel d'enregistrements
Pour ajouter manuellement un enregistrement au groupe, utilisez l'instruction:
Add_Group_Raw( 'nom_groupe' | id_groupe, nbre_lignes ) ;
nbre_ligne représente le nombre d'enregistrements que vous souhaitez ajouter.
Pour ajouter une ligne en fin de groupe, utilisez la variable END_OF_GROUP
L'enregistrement ajouté est vide. Il faut encore l'alimenter en données avec l'instruction
Set_Group_xx_Cell()
Set_Group_Char_Cell( 'nom_groupe" | id_groupe, index, valeur ) ;
Set_Group_Date_Cell( 'nom_groupe" | id_groupe, index, valeur ) ;
Set_Group_Number_Cell( 'nom_groupe" | id_groupe, index, valeur ) ;
index représente l'index du tableau (début = 1)
- ajout dynamique d'enregistrements
Pour ajouter dynamiquement des enregistrements au groupe, utilisez l'instruction:
Populate_Groupe_With_Query( 'nom_groupe' | id_groupe, requete ) ;
requete représente le texte de la requête SQL. Le nombre et le type de chaque colonne de la requête doit être en adéquation avec les colonnes définies dans le groupe d'enregistrements.
Création d'un groupe avec requête
La création d'un groupe d'enregistrements avec requête est beaucoup plus rapide à mettre en oeuvre puisque c'est la requête SQL fournie qui détermine le nombre et le type des colonnes.
La syntaxe est la suivante:
RECORDGROUP := Create_Group_Form_Query( 'nom_groupe', requete [,scope ] [, nbre_rec_ramenés] ) ;
Le groupe ainsi créé est alimenté en enregistrements avec l'instruction:
NUMBER := Populate_Group( 'nom_groupe' | id_groupe ) ;
Exemple:
Populate_Group() Declare
LC$Req Varchar2(512) ;
RG_NAME Varchar2(15) := 'RG_GROUP' ;
rg_id RecordGroup ;
errcode NUMBER ;
Begin
LC$Req := 'Select EMPNO, ENAME From EMP Order by ENAME' ;
rg_id := Find_Group( rg_name );
IF Id_Null(rg_id) THEN
rg_id := Create_Group_From_Query( rg_name, LC$Req ) ;
End if ;
errcode := Populate_Group( rg_id );
End;
Autres fonctions liées aux groupes d'enregistrements
Suppression d'un groupe
Delete_Group( 'nom_groupe' | id_groupe ) ;
Remarque:
Cette instruction ne peut pas être utilisée sur un groupe créé dès la conception dans Forms Builder
Suppression d'un enregistrement dans le groupe
Delete_Group_Raw( 'nom_groupe' | id_groupe, index ) ;
Supprime du groupe l'enregistrement n° index
Affichage du nombre d'enregistrements
NUMBER := Get_Group_Raw_Count( 'nom_group' | id_groupe ) ;
Récupération de la valeur d'une colonne
NUMBER := Get_Group_Number_Cell( 'nom_colonne' | id_colonne, index ) ;
DATE := Get_Group_Date_Cell( 'nom_colonne' | id_colonne, index ) ;
VARCHAR2 := Get_Group_Char_Cell( 'nom_colonne' | id_colonne, index ) ;
nom_colonne représente le nom de la colonne dans le groupe sous la forme : nom_groupe.nom_colonne
index désigne le numéro de l'enregistrement
récupération du premier n° d'enregistrement correspondant à la recherche
Get_Group_Record_Number('nom_colonne' | id_colonne, valeur ) ;
Get_Group_Record_Number() Declare
rg_id RecordGroup;
match NUMBER := 2212;
status NUMBER;
num_record NUMBER;
Begin
rg_id := Create_Group_From_Query('QGROUP', 'SELECT ENAME,EMPNO FROM EMP ORDER BY SAL DESC');
status := Populate_Group( rg_id );
IF status = 0 THEN
num_record :=Get_Group_Record_Number('QGROUP.ENAME',match);
Message( 'Premier enregistrement trouvé : ' || to_CHAR(num_record) );
Else
Message( 'Erreur de création du groupe d''enregistrements' );
RAISE Form_Trigger_Failure;
End if ;
End;
Marquage d'un enregistrement
Set_Group_Selection( 'nom_groupe' | id_groupe, num_rec ) ;
Cette instruction permet de "marquer" un enregistrement particulier dans un groupe
Récupération du nombre d'enregistrements "marqués"
NUMBER := Get_Group_Selection_Count( 'nom_groupe' | id_group ) ;
Récupération du numéro de séquence d'un enregistrement marqué
NUMBER := Get_Group_Selection( 'nom_groupe' | id_group, num_selection ) ;
Lorsque plusieurs enregistrements sont marqués dans un groupe, cette fonction permet de récupérer l'index des enregistrements marqués.
Exemple
Get_Group_Selection() Declare
Num_rec NUMBER ;
Begin
Num_rec := Get_Group_Selection_Count( 'RG_EMP' ) ;
For i in 1..Numrec Loop
Message( 'enregistrement marqué : ' || to_char( Get_Group_Selection ( 'RG_EMP', i ) ) ;
End loop ;
End ;
Techniques avancées
Les groupes d'enregistrements dynamiques sont pratiques lorsque vous souhaitez alimenter un item liste ou une LOV dont les enregistrements (et donc la requête) changent en fonction du contexte.
Comme il est possible d'assigner un groupe d'enregistrements à une LOV à l'exécution, il est facile de modifier dynamiquement le contenu de la LOV.
Declare
LC$Req Varchar2(512) ;
RG_NAME Varchar2(15) := 'RG_GROUP' ;
rg_id RecordGroup ;
errcode NUMBER ;
BEGIN
If :Bloc.item = 1 Then
LC$Req := 'Select col1, col2 From table_1' ;
ElsIf :Bloc.item = 2 Then
LC$Req := 'Select col1, col2 From table_2' ;
Else
LC$Req := 'Select col1, col4 From table_3' ;
End if ;
rg_id := Find_Group( rg_name );
IF Id_Null(rg_id) Then
rg_id := Create_Group_From_Query( rg_name, LC$Req ) ;
End if ;
errcode := Populate_Group( rg_id );
Set_Lov_Property( 'LOV_1', RECORD_GROUP, rg_name ) ;
End;
|
