Objectifs du describe()

Describe permet de connaître la valeur des attributs d'un DataWindow et les objets à l'intérieur de l'objet DataWindow.
Chaque colonne a un ensemble d'attributs.
Les objets graphiques dans la DataWindow ont un ensemble d'attributs.

On spécifie un ou plusieurs attributs sous forme de chaîne et Describe renvoie la valeur de l'attribut.
Describe permet aussi d'évaluer des expressions impliquant une valeur particulière d'une ligne et colonne.

Lorsqu'on inclut une fonction d'évaluation dans la liste des attributs du Describe, la valeur de l'évaluation de l'expression est incluse dans l'expression renvoyée.

Appliqué au contrôle DataWindow et à la DataWindow fille.

Syntaxe:

datawindowname.Describe(attributelist)

Paramètre  Description
DataWindowName  Le nom du contrôle DataWindow ou celui de la DataWindow fille pour laquelle on désire des informations.
Attributelist  Une chaîne de caractère, liste d'attributs ou de fonctions d'évaluations séparées par des espaces.

Valeur de Retour

String.

Renvoie une chaîne qui inclut une valeur pour chaque attribut ou fonction à évaluer.

Un caractère nouvelle ligne (~n) sépare la valeur de chaque élément dans la liste des attributs.

Si la liste des attributs contient un élément invalide, Describe renvoie un point d'exclamation (!) pour cet attribut et ignore le reste de la liste des attributs.

Describe renvoie un point d'interrogation (?) si il n'y a pas de valeur pour l'attribut.


Utilisation du describe

Utiliser Describe pour comprendre la structure d'une DataWindow.

Describe permet de chercher l'intervalle de valeurs d'une colonne d'une DataWindow.
Describe permet de connaître la valeur courante d'un attribut et utiliser cette valeur pour faire certaines modifications.
Describe est généralement utilisée pour connaître l'instruction SELECT dans le but de la modifier.

Par exemple, pour ajouter une clause WHERE à une DataWindow.

Lorsque l'on construit l'instruction SQL, PowerBuilder sauvegarde la clause dans un format particulier PBSELECT dans la DataWindow, avec la définition de la DataWindow, mais pas sous forme d'une instruction SQL.

Lorsque l'on appelle Describe avec l'attribut Table.Select, il renvoie une instruction SQL SELECT seulement si l'on est connecté à la base. Sinon Describe renvoie une instruction PBSELECT.

Syntaxe des Attributs:

La syntaxe d'un attribut dans la liste des attributs est:

objectname.attribut

Attribut dont la valeur est une liste

Lorsqu'un attribut renvoie une liste, le caractère de tabulation(~t) sépare les valeurs de la liste.

L'attribut Bands (Bands attribute) renvoie toutes les bandes utilisées dans la DataWindow:

header~tdetail~tsummary~tfooter~theader.1~ttrailer.1

Si le premier caractère de la liste renvoyé est un guillemet, cela signifie que la liste entière se trouve être encadrée par des guillemets.

Et toute quotation apparaissant est une quote simple.

Par exemple, la liste suivante est la valeur d'attribut

"Student~T'Andrew'or'~NAndy'"

Attributs dont la valeur est entre quotes

Describe renvoie les valeurs d'attributs entre quotes si le texte peut paraître ambigu.

Si l'attribut contient un point d'interrogation, alors le texte renvoyé sera entre quotes.

Une question sans quotes signifie que l'attribut n'a pas de valeur.

Identification de Colonne

Lorsque l'objet est une colonne, on peut identifier une colonne en spécifiant son nom ou par un signe dièse (#) suivi du numéro de la colonne.

Si le salaire est la cinquième colonne, alors "salary.coltype" est équivalent à "#5.coltype".


Nom d'Objet

Le painter de DataWindow donne automatiquement des noms aux colonnes et aux labels de colonne.

Les autres objets ajoutés à la DataWindow sont nommés avec des chaînes de nombres cryptés, sauf si on leur assigne un nom.

Describe se reporte au nom crypté mais ce nom ne peut être visualiser dans le painter .

Pour facilement décrire et modifier les attributs d'un objet donner aux objets des noms.


Évaluation d'une expression

Les Fonctions d'évaluation de Describe permettent d'évaluer des expressions du painter de DataWindow dans un script en utilisant les données de la DataWindow.

La fonction d'évaluation possède la syntaxe suivante, que l'on spécifie pour une liste d'attributs.

Evaluate('expression', NumeroLigne)

Expression est l'expression à évaluer.

NumeroLigne est le numéro de la ligne pour laquelle on veut évaluer l'expression.

Les expressions incluent usuellement des fonctions du painter de DataWindow.

Dans l'instruction suivante, Describe renvoi 255 ou 0, dépendant de la valeur de la colonne salaire en ligne 3.

ls_ret = dw_1.Describe( "Evaluate('If(salary > 100000, 255, 0)', 3)")

On peut appeler les fonctions de contrôle de la DataWindow dans un script pour obtenir une donnée de la DataWindow.

Mais certaines fonctions de painter telle que LookUpDisplay ne peuvent être appelées à partir d'un script.

L'utilisation d'Evaluate est le seul moyen de les appeler.

Évaluation de la valeur d'affichage d'une DropDownDataWindow

Cet exemple utilise la fonction d'évaluation du Describe pour rechercher la valeur d'affichage d'une colonne DropDownDataWindow appelée state_code.

Noter que l'on doit exécuter le code après l'événement ItemChanged de telle sorte que la valeur que l'utilisateur a sélectionnée est devenue la valeur de l'item dans le buffer.

Le code suivant est le script d'un user event (événement utilisateur) appelé getdisplayvalue.

string rownumber, displayvalue
rownumber = String(dw_1.GetRow())
displayvalue = dw_1.Describe("Evaluate('LookUpDisplay(state_code) ', " + rownumber + ")")

Le code suivant fait partie du script de l'événement ItemChanged, activant le message getdisplayvalue.

dw_1.PostEvent("getdisplayvalue")

Illustration de la fonction Describe

Pour illustrer le types de valeur que renvoie Describe considérons une DataWindow appelée dw_emp, avec un niveau de groupe. Ses colonnes sont désignées par emp et empname et ses entêtes par emp_h et empname_h

Le tableau suivant montre plusieurs attributs et la valeur renvoyée.

Dans le premier exemple, des commande montrent ce que l'on doit spécifier dans la fonction Describe et quelle valeur est renvoyée.

Attribut  Valeur Renvoyée
datawindow.Bands  header~tdetail~tsummary~tfooter~theader.1~ttrailer.1
datawindow.Objects  emp~tempname~temp_h~tempname_h~t Si l'objet n'a pas de nom, PowerBuilder lui assigne un nom numérique tel que obj_1234567.
emp.Type  column
empname.Type  column
empname_h.Type  text
emp.Coltype  char(20)
state  !(! Indique un item(élément) invalide. aucune colonne n'est désignée sous le nom state.
empname_h.Visible  ?

L'exemple suivant appelle Describe avec une liste d'attributs vue dans le tableau précèdent.

La valeur renvoyée formatée avec les caractères de tabulation et de nouvelle ligne suivent.
Noter que parce que state n'est pas un objet de la DataWindow, le type sur state renvoie un point d'exclamation(!).

string ls_request, ls_report

ls_request = "DataWindow.Bands DataWindow.Objects " &
  + "empname_h.Text "  &
  + "empname_h.Type emp.Type emp.Coltype "  &
  + "state.Type empname.Type empname_h.Visible"

ls_report = dw_1.Describe(ls_request)

Describe défini la valeur de ls_report à la chaîne suivante

header~tdetail~tsummary~tfooter~theader.1~ttrailer.1~N
emp~tempname~temp_h~tempname_h~N "Employee~R~NName"cd~N text~N
column~Nchar(20)~N!

Les instructions suivantes vérifient le type de la donnée de la colonne nommée salaire avant d'utiliser GetItemNumber pour obtenir la valeur du salaire.

string ls_data_type
integer li_rate
ls_data_type = dw_1.Describe("salary.ColType")
IF ls_data_type = "number" THEN
   li_rate = dw_1.GetItemNumber(5, "salary")
ELSE
   ... // Faire traitement
END IF

Nom de Colonne et Nombre

Les instructions suivantes recherchent le type de la colonne courante en utilisant le nom de la colonne.

s = This.Describe(This.GetColumnName()+ ".ColType")

Pour comparaison, Les instructions suivantes recherchent le même type d'information, en utilisant le numéro de colonne courante.

s = This.Describe("#" + String(This.GetColumn()) + ".ColType")

Ascenseur(Scrolling) et numéro de colonne courante

L'exemple suivant, est une partie du script sur événement ScrollVertical du contrôle DataWindow.

Il fait de la première ligne visible(premier enregistrement visible) le numéro de ligne courante lorsque l'utilisateur fait défiler les données à travers les ascenseurs dans la DataWindow.

s = This.Describe("DataWindow.FirstRowOnPage")
IF IsNumber(s) THEN This.SetRow(Integer(s))

Evaluation de la valeur affichée par une DropDownDataWindow

L'exemple suivant utilise la fonction d'évaluation du Describe pour trouver la valeur affichée par une colonne DropDownDataWindow appelée state_code.

Noter que l'on doit exécuter le code après événement ItemChanged de telle sorte que la valeur sélectionnée par l'utilisateur est devenue valeur courante dans le buffer.

Ce script est le code d'un événement utilisateur appelé getdisplayvalue.

string rownumber, displayvalue
rownumber = String(dw_1.GetRow())

displayvalue = dw_1.Describe( &
  "Evaluate('LookUpDisplay(state_code) ', " &
  + rownumber + ")")

Ce code, qui doit être défini dans le script de l'événement ItemChanged, poste l'événement getdisplayvalue.

dw_1.PostEvent("getdisplayvalue")

Affectation de valeur Nulle aux données de colonnes

Le code suivant extrait du script de l'événement ItemError d'un contrôle DataWindow, permet à l'utilisateur d'attribuer une valeur nulle à une colonne et se positionne sur la colonne suivante.

Pour des colonnes ayant des données d'un autre type que le type string, l'utilisateur ne peut pas laisser la valeur vide(qui est une chaîne vide et n'est donc pas compatible avec la donnée) sans ce code :

string s

s = This.Describe(This.GetColumnName() + ".Coltype")
CHOOSE CASE s
   CASE "number"
      IF Trim(This.GetText()) = "" THEN
         integer  null_num
         SetNull(null_num)
         This.SetItem(This.GetRow(), This.GetColumn(), null_num)
         This.SetActionCode(3)
      END IF
   CASE "date"
      IF Trim(This.GetText()) = "" THEN
         date  null_date
         SetNull(null_date)
         This.SetItem(This.GetRow(), This.GetColumn(), null_date)
         This.SetActionCode(3)
      END IF
   ... // cas Additionnel pour des données d'autres type
END CHOOSE