Le service web RecordSql est une fonctionnalité native du runtime, disponible en mode REST uniquement.

La demande d'action RecordSql au service web REST se fait au format JSON dans le corps du message.

Il permet a un appelant, après avoir passé les informations d'authentification, d'interroger un RecordSql directement afin d'obtenir des données de la base de données, sans entrer dans la gestion de l'ERP et donc sans invoquer de programme Diva car cette API s'en charge directement.

L'appelant et le paramétrage du service web détermine dans quel contexte (environnement, utilisateur, implicite)  les données vont être lues.

Format de la demande

Paramètre	Balise	Description
Nom dictionnaire RecordSql	"dhoq" (obligatoire)	Nom du dictionnaire record sql : c’est le fichier .dhoq. Par exemple GTRSART.dhoq contient plusieurs RecordSql liés aux articles
Nom RecordSql	"recordsql" (obligatoire)	Nom du record sql unitaire : correspond a la balise <RecordSql du dictionnaire. Par exemple Article est la requête SQL principal de la base articles
Token	"access_token" (obligatoire)	Valeur du TOKEN obtenu durant la phase d'authentification
Paramètres	"parameters"	Liste des champs et leurs valeurs (en majuscules et en précisant le nom de table) au format table.champ=valeur séparés par le point-virgule. Ce champs servent de référence en tant que clé pour exécuter la requête. Par défaut ce champ reste vide car le moteur REST cherche s’il peut remplir tout seul les paramètres variables pour traiter la requête, en se basant sur la table des utilisateurs  et les tables communes de l’ERP. En principe ce champ devrait être toujours vide, à part quelques exceptions, sinon il doit contenir une suite de champs . Exemple : MZ.DOS=998 ; etc
Champs à récupérer	"fields"	Liste des champs à récupérer, en majuscules et sans préciser la table, séparés par un point virgule. Par défaut * indique qu’on veut récupérer tous les champs de la table. Exemple  CPOSTAL;VIL Note : pour les champs provenant d'une jointure soit on utilise l'alias (si existant dans le recordSql), soit on utilise le nom de la table jointée avec le nom du champ séparés par un '_'. Exemple : jointure sur ART, la récupération du champ ART.REF s'obtient avec l''écriture du champ ART_REF Attention, ce sont les champs renvoyés par le service web, et pas ceux retournés par la requêre SQL. Pour optimiser la requête, il convient d'utiliser les options
Condition where	"where”	Nom de la condition where existante dans le RecordSql Le programme XRecordSQLCheck.exe vous permet de connaitre le contenu des fichier .dhog avec la liste des recordSQL qu’ il contient et pour chacun la liste des clauses where, des tris et des clauses having ainsi que les paramètres à transmettre.
Paramètres where	"where_parameters"	Liste des paramètres de la condition where selon le RecordSql au format nomDuParametre1=valeur1;nomDuParametre2=valeur2 ou directement les valeurs au format valeur1;valeur2 dans ce cas les conditions sont appliquées dans l’ordre d’apparition Pour les champs valeur de type ‘chaîne de caractères’, ne pas mettre de cote ou double cote pour les chaines
Pagination offset	"offset"	Mettre une valeur > 0 pour récupérer un nombre important d'enregistrements. Voir plus loin au sujet des lectures en mode pagination pour renvoyer les enregistrements en plusieurs fois, sachant que le serveur est configuré pour une valeur maximale du nombre d'enregistrements La valeur 0 équivaut a la valeur 1, c'est à dire que seul le premier enregistrement sera retourné.
Pagination count	"count"
Tri	"orderby"	Nom du tri orderby du RecordSql : nom tel qu'il apparaît par exemple Par_Ref
Condition having	"having"	Nom de la condition having
Paramètres having	"having_parameters"	Paramètres de la condition having
Filtres SQL	"filter"	Filtres avancés concernant les clauses WHERE et la gestion des jointures (voir plus bas)
Informations	"infos"	Informations complémentaires, notamment sur la performances ou versions (voir plus bas)

L'URL a utilisé pour les demandes d'action RecordSql est sous la forme : base commune de l'URL + '/api/v1/RecordSql/Execute'

Exemple d'URL sur un poste local:

http://localhost:8080/DhsDivaltoServiceDivaApiRest/api/v1/RecordSql/Execute

Exemple d'URL en Divalto cloud:

URL : http://api.divaltocloud.com/123456/testing1/api/v1/RecordSql/Execute

Informations complémentaires : gestion des dossiers et utilisateur

L'authentification permet d'identifier, via les utilisateurs Harmony, un utilisateur Divalto. Cet utilisateur doit bénéficier dans le paramétrage Divalto d'un dossier par défaut

C'est ce dossier qui est appliqué par défaut lors d'une appel API RecordSql.

Pour modifier le dossier, il faut indiquer le nom du dossier dans la zone 'parameters' sous la forme suivant

"parameters" :  "MZ.DOS=MONDOSSIER"

Informations complémentaires : gestion des jointures

Le champ 'filter' peut contenir les commandes suivantes:

Utilisation de ces options: 

• Le fonctionnement de ces options est strictement le même que pour l'écriture en langage Diva (voir l'aide en ligne pour plus de détails)

• Permet donc d'activer ou desactiver des jointures ou des colonnes, afin d'optimiser la lecture, ou de lire des champs de jointures optionnelles

• L'utilité de ces options dépend de la manière dont le RecordSql a été écrit. Un RecordSql qui n'a pas de jointure activée par défaut sera optimisé sans cette option

• Les noms de jointure ou $all sont toujours convertis en majuscules avant leur utilisation.

• On peut combiner les options. Elle seront exécutées dans l'ordre d'apparition

Exemples 'infos':

filter= "<joindeactivate>$all"  ;permet de lire uniquement la table du FROM sans aucune jointure, donc de manière beaucoup rapide  

filter= "<joindeactivate>$all<joinactivate>majointure"   ;permet de désactiver toutes les jointures, puis de ne réactiver que la jointure 'majointure' 

Informations complémentaires : filtres SQL

Le champ "filter" permet l'utilisation de filtres SQL avancés pour la gestion des clauses WHERE 

Les mécanismes appliqués sont ceux des RecordSql Diva.

Conditions where simple

Pour positionner une condition where simple il n’est pas utile de passer par la balise “filter”

"where":"Equal_Vil",
"where_parameters":"ENTZHEIM",
// Utilisation des basises WHERE et WHERE_PARAMETERS pour un cas de clause unique

Conditions where multiple en combinaison simple ET

Pour positionner de multiples conditions where avec un ET logique, il s’agit d’indiquer les noms des clauses WHERE et leurs paramètres, mais le record SQL faisant par défaut un ET logique, il n’est pas utile de donner plus d’information

"filter": {  
        "where": [
            {"name":"LIKE_VIL", "parameters":"EN%" },           
            {"name":"LIKE_CPOSTAL", "parameters":"67%" }        
            ] 
          }
// Première clause WHERE 'Equal_vil' et la valeur demandée 'ALBI'
// Seconde  clause WHERE 'Like_CPostal' et la valeur demandée '67%' pour obtenir les 67****
// Par défaut, un ET logique est appliqué

Conditions where multiple en combinaison simple OU

Pour positionner de multiples conditions where avec un OU logique, il s’agit d’indiquer les noms des clauses WHERE et leurs paramètres, et d’indiquer le type d’opérateur OU

"filter": {  
        "where": [
            {"name":"EQUAL_VIL", "parameters":"ALBI" }, 
            {"name":"EQUAL_VIL", "parameters":"TOULOUSE" }
            ], 
        "operator_where":"OR"
          } 
// Première clause WHERE 'Equal_vil' et la valeur demandée 'ALBI'
// Seconde  clause WHERE 'Equal_vil' et la valeur demandée 'TOULOUSE'
// Deux clauses WHERE avec un OU logique

Conditions where multiple en combinaison complexe

Pour positionner de multiples conditions where en combinaisons complexe avec parenthésage, ET logique, OU logique, il s’agit d’indiquer les noms des clauses WHERE et leurs paramètres, et d’indiquer la condition complète

"filter": {  
        "where": [   
            {"name":"EQUAL_VIL", "parameters":"ENTZHEIM" },               
            {"name":"LIKE_VIL", "parameters":"%OBER%" },                  
            {"name":"LIKE_CPOSTAL", "parameters":"67%" }                  
            ], 
        "whereaddcondition":                                              
            { "name":"cond1", "condition":"(Like_Cpostal and Equal_Vil) or Like_Vil" }            
          } 
          
// Première  clause WHERE 'Equal_vil' et la valeur demandée 'ENTZHEIM'
// Seconde   clause WHERE 'Like_vil' et la valeur demandée '%OBER%' pour obtenir les *OBER*
// Troisième clause WHERE 'Like_CPostal' et la valeur demandée '67%' pour obtenir les 67****
// Définition de la condition complexe : (Like_Cpostal and Equal_Vil) or Like_Vil

Conditions where spécifique en combinaison complexe

Pour positionner de multiples conditions where spécifiques (non prévue dans le recordSql) en combinaisons complexe avec parenthésage, ET logique, OU logique, il s’agit d’indiquer les noms des clauses WHERE et leurs paramètres, et d’indiquer la condition complète

"filter": {  
       "whereremovecondition" :                                               // Toujours demander a effacer les conditions que l'on veut créer
        { "name":"", "parameters": "CONDVILLE1;CONDVILLE2;CONDVILLE3" }, 
       "createwhere":                                                         // Création temporaire de conditions spécifiques (inexistant dans le recordSql)
         [ 
            { "name":"CONDVILLE1", "condition": "T057.VIL='STRASBOURG'" },    // Première  clause WHERE avec le nom attribué, et sa valeur construite directement à partir du nom de champ
            { "name":"CONDVILLE2", "condition": "T057.VIL='TOULOUSE'" },      // Seconde   clause WHERE avec le nom attribué, et sa valeur construite directement à partir du nom de champ
            { "name":"CONDVILLE3", "condition" : "T057.VIL='ALBI'"}           // Troisième clause WHERE avec le nom attribué, et sa valeur construite directement à partir du nom de champ
         ], 
       "whereaddcondition":                                                   // Définition de la condition complexe en utilisant les conditions créés
            { "name" : "CONDTEST", "condition": "CONDVILLE2 OR CONDVILLE3" }  // CONDVILLE1 n'est pas utilisé, d'où sa suppression préalable
          } 

Informations complémentaires : performances et compteurs

Le champ 'infos' peut contenir les commandes suivantes:

Balise perf

La balise xperf à 1 indique que le demandeur souhaite obtenir des informations générales et de performances sur l'exécution de la demande.

Si la balise est donnée lors de l’authentification, toutes les demandes utilisant le token correspondant se feront avec réponse de performances.

Sinon le demandeur peut demander les performances demande par demande.

La réponse est obtenue dans la balise "infos" de la réponse. Voir plus bas pour le format de la réponse.

Exemple de demande : "infos" : "<perf>1"

Balise version

La balise version à 1 indique que le demandeur souhaite obtenir la version du module REST.

La réponse comporte la balise VersionRest indiquant cette version, et le cas échéant la balise DebugRest à 1 si le mode debug est activé

Exemple de demande : "infos" : "<version>1"

Exemple de réponse

"infos": "{
"VersionRest":"3.05",
"DebugRest":"1"
}"

Balise perfmem

La balise perfmem à 1 indique que le demandeur souhaite, en plus des performances de base, obtenir aussi des détails sur la consommation mémoire en cours du processus REST

La réponse comporte plusieurs balises, celles de <perf> et aussi de nouvelles balises sur la mémoire

Exemple de demande : "infos" : "<perfmem>1"

Interprétation des informations mémoire :

• La taille de la mémoire virtuelle « PeakVirtualMemorySize » : taille de mémoire adressable par un processus, rien ne peut dépasser ces valeurs.

• Il faut donc surveiller WorkingSetMemorySize et PeakWorkingSetMemorySize, et aussi PagedMemorySize, PeakPagedMemorySize.

• Car cela indique la charge de mémoire en cours (et le pic attient) et voir si on se rapproche plus ou moins vite de VirtualMemorySize.

• Il faut donc faire plusieurs requêtes et suivre l'évolution de la mémoire, en sachant que la première requête va allouér la mémoire pour stocker les informations de la requêtes, et donc il faut surveiller la mémoire à partir de la deuxième requête.

Exemple de réponse a une demande de lecture de 10 codes postaux

infos: "{"xperf" : {	
"CountNumberExecuteRequeteSQL" : "1"	il y a 1 appel a l'api execute record sql
,"TimeExecuteRequestSQL" : "187"	il a mis 187 mili
,"TimeReadDatas" : "1"	on a mis 1 mili pour traiter les datas enntrées
,"TimeImpersonation" : "1"	impersonation
,"TimeReadResult" : "10"	lecture du résultat et des champs et traitement des confidentialités
,"CountLoadDHXISAM" : "1"	un appel pour voir si dhxisam est déjà chargée
,"TimeLoadDHXISAM" : "1"	le temps du test
,"CountSQL" : "1"	une requête effectuée
,"TimeSQL" : "1"	temps pour la requête
,"TimeGlobalLoadInfosUser" : "15"	test pour vérifier si les infos de l'utilisateur sont présentes
,"TimeReadLocales" : "1"	idem
,"CountNumberRecordAuth" : "13"	idem pour les autorisations
,"CountNumberRecordCommun" : "4"	idem pour les flags communs erp et les flag type de l'erp
,"CountNumberRecordType" : "1"	
,"TimeGtrstabCodepostal" : "172"	
,"NonpagedSystemMemorySize" : "79"
,"PagedMemorySize" : "158108"
,"PagedSystemMemorySize" : "606"
,"WorkingSetMemorySize" : "62484"
,"PeakPagedMemorySize" : "187976"
,"PeakVirtualMemorySize" : "1067052"
,"PeakWorkingSetMemorySize" : "212992"
,"VirtualMemorySize" : "822476
}}"
}

Balise debugctx

La balise debugctx à 1 indique que le demandeur souhaite obtenir, uniquement lors d’une DEMANDE AVEC CHANGEMENT DE DOSSIER, des détails sur le changement de contexte (=dossier courant).

La réponse comporte plusieurs balises.

Exemple de demande : "infos" : "<debugctx>1" précédé par "parameters" : "DOS=997"

{"debugctx" : {"debugctx_action":"dos= dos voulu=997 recordsql=TABLECOMMUNE,dos= dos voulu=997 recordsql=TCOMMUN,
dos= dos voulu=997 recordsql=UTILISATEUR,dos=997 dos voulu=997 recordsql=DOSSIERCRM,dos=997 dos voulu=997 recordsql=APPLIAUTORIS,
dos=997 dos voulu=997 recordsql=DOSSIER,dos=997 dos voulu=997 recordsql=PDOSSIER,dos=997 dos voulu=997 recordsql=DOSEXP,
dos=997 dos voulu=997 recordsql=EXPERT_GRM,dos=997 dos voulu=997 recordsql=EXPERT_QUAL,dos=997 dos voulu=997 recordsql=EXPERT_CONT,
dos=997 dos voulu=997 recordsql=EXPERT_DDOC,Création contexte sur dossier 997," }}

Lors d’un second appel, si le contexte mis en cache n’est pas modifié, la réponse l'indique

{"debugctx" : {"debugctx_action":"Contexte déjà existant sur dossier 997" }}

Balise infostoken (et pas infotoken)

La balise infostoken à 1 permet d’avoir des informations sur le token , notamment sur sa durée et la date/heure d’expiration.

La réponse comporte plusieurs balises.

"infos": "{
"InfosToken{":
"ExpireLocalTime":"20221228085340",	
"ExpireUtcTime":"20221228075340",	
"ExpireMinutes":"30",	
"ExpireLocalTimeName":"Paris, Madrid",	
"Env":"ERP213",	
"User":"jpt3",	
"Domain":"psxbdjpt01"	
}}"

Informations complémentaires : debug et fonctions spéciales

Demande <debug>1 et <sizedebug>10000

Demande Debug

La balise <debug>1 positionnée dans la zone infos permet de mettre le module REST en mode debug.

Cela a pour effet d'écrire des lignes de debug dans le fichier \divaltolog\feventREST.log

En complément:

• <sizedebug>xxxxxx Permet d’indiquer une limite de taille du debug

• <debugloaddico>1 Permet de limiter le le fichier debug au chargement des dictionnaires

• <dicojson>0 Permet d’indiquer de ne plus charger les dictionnaires pour optimisation (qui sont décrits dans les fichiers XML)

Demande DebugEnv

La balise <debugenv>1 peut être positionnée dans la zone infos lors du PREMIER appel de la demande de jeton. En effet elle ne fonctionne que pour une nouvelle connexion avec un nouveau compte, lors du chargement des informations de l’environnement. Par la suite un cache stocke ces informations et l’appel avec cette balise n’a plus aucun effet

Exemple d’appel

{
    "domain":"{{DOMAIN}}",
    "user": "{{LOGIN}}",
    "password": "{{PASSWORD}}",
    "env": "{{ENV}}",
    "infos": "<debugenv>1"
}

La réponse donne des détails sur tout le cheminement du chargement d’un environnement (implicites, dhoq, fichiers,…)

Exemple de réponse

"infos": "{
"debugenv" : {
"cheminxlogfenv":"//PSXBDJPT01/Divalto/ERP213/fichiers",
"cheminxlogf":"//psxbdjpt01/divalto/erp213/fichiers",
"CheminDivalto":"c:\Divalto",
"CheminEtFichierImplicites":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesOpen":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesAuformatWindows":"c:\divalto\erp213\fichiers\implicitesdemo.txt",
"LectureFichier":"GTRSTAB.DHOQ",
"LectureFichier":"GTRSTAB.DHOQ",
"objetdhoq":"GTRSTAB.DHOQ",
"addon ErreurLectureFichier": \divalto\erp213\setup\specifs\objets\GTRSTABU.DHOQ (erreur 20),
"addon ErreurLectureFichier": \divalto\erp213\setup\specifs2\objets\GTRSTABU.DHOQ (erreur 20),
"LectureFichier":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.xml",
"ImplicitesLocales":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"LectureFichier":"c:\divalto\erp213\fichiers\connexions.xml",
"ConnexionsLocales":"c:\divalto\erp213\fichiers\connexions.xml",
"cheminxlogfenv":"//PSXBDJPT01/Divalto/ERP213/fichiers",
"cheminxlogf":"//psxbdjpt01/divalto/erp213/fichiers",
"CheminDivalto":"c:\Divalto",
"CheminEtFichierImplicites":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesOpen":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesAuformatWindows":"c:\divalto\erp213\fichiers\implicitesdemo.txt",
"LectureFichier":"WMRSTAB.DHOQ",
"LectureFichier":"WMRSTAB.DHOQ",
"objetdhoq":"WMRSTAB.DHOQ",
"addon ErreurLectureFichier": \divalto\erp213\setup\specifs\objets\WMRSTABU.DHOQ (erreur 20),
"addon ErreurLectureFichier": \divalto\\erp213\\setup\\specifs2\\objets/WMRSTABU.DHOQ (erreur 20),
"LectureFichier":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.xml",
"ImplicitesLocales":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"LectureFichier":"c:\divalto\erp213\fichiers\connexions.xml",
"ConnexionsLocales":"c:\divalto\erp213\fichiers\connexions.xml",
"cheminxlogfenv":"//PSXBDJPT01/Divalto/ERP213/fichiers",
"cheminxlogf":"//psxbdjpt01/divalto/erp213/fichiers",
"CheminDivalto":"c:\Divalto",
"CheminEtFichierImplicites":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesOpen":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesAuformatWindows":"c:\divalto\erp213\fichiers\implicitesdemo.txt",
"LectureFichier":"A5RSDOS.DHOQ",
"LectureFichier":"A5RSDOS.DHOQ",
"objetdhoq":"A5RSDOS.DHOQ",
"LectureFichier":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.xml",
"ImplicitesLocales":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"LectureFichier":"c:\divalto\erp213\fichiers\connexions.xml",
"ConnexionsLocales":"c:\divalto\erp213\fichiers\connexions.xml",
"cheminxlogfenv":"//PSXBDJPT01/Divalto/ERP213/fichiers",
"cheminxlogf":"//psxbdjpt01/divalto/erp213/fichiers","CheminDivalto":"c:\Divalto",
"CheminEtFichierImplicites":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesOpen":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesAuformatWindows":"c:\divalto\erp213\fichiers\implicitesdemo.txt",
….
"cheminxlogfenv":"//PSXBDJPT01/Divalto/ERP213/fichiers",
"cheminxlogf":"//psxbdjpt01/divalto/erp213/fichiers",
"CheminDivalto":"c:\Divalto",
"CheminEtFichierImplicites":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesOpen":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"CheminEtFichierImplicitesAuformatWindows":"c:\divalto\erp213\fichiers\implicitesdemo.txt",
"CheminEtFichierImplicitesAuformatWindows":"c:\divalto\erp213\fichiers\implicitesdemo.txt","LectureFichier":"GTRSDOS.DHOQ",
"LectureFichier":"GTRSDOS.DHOQ",
"objetdhoq":"GTRSDOS.DHOQ",
"addon ErreurLectureFichier":\divalto\erp213\setup\specifs\objets\GTRSDOSU.DHOQ (erreur 20),
"addon ErreurLectureFichier": \divalto\erp213\setup\specifs2\objets\GTRSDOSU.DHOQ (erreur 20),
"LectureFichier":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.xml",
"ImplicitesLocales":"//psxbdjpt01/divalto/erp213/fichiers/implicitesdemo.txt",
"LectureFichier":"c:\divalto\erp213\fichiers\connexions.xml",
"ConnexionsLocales":"c:\divalto\erp213\fichiers\connexions.xml"}}"

Demandes spéciales (cache, dhoq)

La balise dhoq accepte des mot clés pour demandes spéciales

Informations complémentaires : gestion de la pagination

Le service web est configuré pour renvoyer un nombre maximal d'enregistrements (par défaut 1000, mais peut être inférieur).

Il est donc conseillé, lorsqu'une requête de lecture est susceptible de renvoyer beaucoup d'enregistrements, d'utiliser la pagination pour récupérer les enregistrements par lots.

Deux paramètres d'appels vont servir :

• count

• offset

et une donnée de retour va servir :

• nbrecord

Le premier appel devra se fait avec un offset à 0 et un count dimensionné selon le nombre d'enregistrements d'un lot, par exemple 10.

La réponse au premier appel donne les 'nbrecord' premier enregistrements.

Si 'nbrecord' est égal a count, alors il y a une suite. L'appel suivant devra reprendre les 'nbrecord' en plus dans l'offset pour interroger les suivants. Le count conserve sa valeur du premier appel.

Sinon (donc 'nbrecord' est inférieur a count), alors tout a été lu

Exemple en 2 pages de 10 pour un total de 18 enregistrements

Premier appel : OFFSET=0                   COUNT=10
Réponse : 10 enregistrements et NBRECORD=10
NBRECORD est égal à COUNT donc il y a une suite

Second appel : OFFSET=OFFSET+NBRECORD=10   COUNT=10
Réponse : 8 enregistrements et NBRECORD=8
NBRECORD est inférieur à COUNT c'est terminé

Exemple en 3 pages de 5 pour un total de 15 enregistrements

Premier appel : OFFSET=0                      COUNT=5
Réponse : 5 enregistrements et NBRECORD=5
NBRECORD est égal à COUNT donc il y a une suite

Second appel : OFFSET=OFFSET+NBRECORD=5       COUNT=5
Réponse : 5 enregistrements et NBRECORD=5
NBRECORD est égal à COUNT donc il y a une suite

Troisième appel : OFFSET=OFFSET+NBRECORD=10   COUNT=5
Réponse : 5 enregistrements et NBRECORD=5
NBRECORD est égal à COUNT donc il y a une suite

Quatrième appel : OFFSET=OFFSET+NBRECORD=15   COUNT=5
Réponse : 0 enregistrements et NBRECORD=0
NBRECORD est inférieur à COUNT c'est terminé

Exemple de programmation

int woffset = 0
int mycount = 10
int fini = 0

while ( fini = 0 )
{
	;requete rest rsql avec  {offset=woffset    count= mycount }
	;traiter le resultat, dont en retour le nbrecord

	if ( nbrecord < mycount )
		fini = 1					;plus de suite
	else
		woffset = woffset + mycount	;on lit la suite
}

Format de la réponse

Le service web RecordSql REST répond a une demande de lecture de données sous une forme JSON avec les résultats suivants:

Le champs 'infos', dans le cas d'une demande d'information de performance, peut contenir plusieurs informations indiquant des temps d'exécution.

Exemples : "{\"xperf\" : {\"ExecuteRequestSQL\" : \"0\",\"LoadUser\" : \"1\",\"LoadDHXISAM\" : \"15\",\"LoadRecordForSQL\" : \"1\",\"LoadDataForSQL\" : \"1\",\"ImpersonationSQL\" : \"1\",\"ExecuteSQL\" : \"1\",\"ResultSQL\" : \"3\" }}"

Dans les exemples suivants, xxxxxx pour 'access_token' est a remplacer par la valeur du token obtenue lors de l'authentification.

Comment trouver le recordSql a utiliser

Infinity se repose sur les recordSql pour l'accès aux données de la base de données.

Quelques définitions d'un recordSql:

• porte un nom (en clair, en français), par exemple Article

• fait partie d'un ensemble (codifié) : le dictionnaire de recordSql, par exemple gtrsart.dhoq

  • xxRSyyyy.DHOQ : xx correspond au module (par exemple GT pour la gestion commerciale) et yyyy a une famille (par exemple art pour la famille articles)

• assemble tous les composants d'une requête SQL

  • la table principale (celle du FROM)

  • les champs (du FROM, champs calculés et champs des jointures)

  • les conditions (WHERE, HAVING, COUNT)

  • les tris

La moyen le plus simple de trouver une table courante est d'utiliser le zoom correspondant.

Avec le menu Aide / A propos, la fenêtre indique des informations

Exemple : zoom article

On y trouve le nom du recordSql et on peut y trouver une indication sur le module.

Exemple : recordSql Article   module GT

=>notre recordSql se trouve dans GTRSART.DHSP et s'appelle Article

et on y trouvera plus bas les jointures, clauses where et tris.

Une fois identifié, l'utilitaire Harmony XRecordSQLCheck.exe (a lancer depuis /divalto/sys) permet de manipuler le recordSql et de le tester avant de l'utiliser dans un service web

Le bas de l'écran contient la requête SQL générée, qui peut être copiée dans un éditeur de requêtes SQL, par exemple Sql Management Studio

Exemples

Lecture en échec

Exemple de demande de lecture de la table de codes postaux, alors que le paramétrage des RecordSql n'est pas fait :

{
"dhoq" : "xxrstab.dhoq",
"recordsql" : "",
"access_token" : "xxxxxx",
"parameters" : " ",
"fields" : "*",         
"where" : " ",
"where_parameters" : " ",
"offset" : 0,
"count" : 0,
"orderby" :  " ",
"havingc" : " ",
"having_parameters" : " ",
"infos" : " " 
}

Réponse :

{
    "error": 54,
    "txterr": "erreur : dhoq '' non autorisé",
    "tablename": "",
    "nbrecord": 0,
    "records": null,
    "infos": ""
}

Lecture simple

Exemple de demande de lecture de la table de catégories fournisseur, sans conditions ni champs précisés :

{
"dhoq" : "gtrstab.dhoq",
"recordsql" : "CATFOU",
"access_token" : "xxxxxx",
"parameters" : " ",
"fields" : "",          
"where" : " ",
"where_parameters" : " ",
"offset" : 0,
"count" : 0,
"orderby" :  " ",
"havingc" : " ",
"having_parameters" : " ",
"infos" : " " 
}

Réponse (a noter que la demande en count=0 donne un retour nbrecord=1:

{
    "error": 0,
    "txterr": "",
    "tablename": "T116",
    "nbrecord": 1,
    "records": [
        {
            "record": {
                "T116_ID": "3",
                "CEBIN": "116",
                "DOS": "998",
                "TABNO": "116",
                "CATFOUCOD": "TRANSIT",
                "LIB80": "Transitaire",
                "CATFABFL": "1",
                "USERCR": "DEMO",
                "USERMO": "DEMO",
                "USERCRDH": "20191119144005",
                "USERMODH": "20191119144026",
                "CENOTE": "1",
                "NOTE": "0"
            }
        }
    ],
    "infos": ""
}

Exemple de demande de lecture de la table de codes postaux, sans conditions mais avec liste de champs ET uniquement les 2 premiers:

{
"dhoq" : "gtrstab.dhoq",
"recordsql" : "CODEPOSTAL",
"access_token" : "xxxxxx",
"parameters" : " ",
"fields" : "CPOSTAL;VIL",           
"where" : " ",
"where_parameters" : " ",
"offset" : 0,
"count" : 100,
"orderby" :  " ",
"havingc" : " ",
"having_parameters" : " ",
"infos" : " " 
}

Réponse :

{
    "error": 0,
    "txterr": "",
    "tablename": "T057",
    "nbrecord": 2,
    "records": [
        {
            "record": {
                "CPOSTAL": "01000",
                "VIL": "BOURG EN BRESSE"
            }
        },
        {
            "record": {
                "CPOSTAL": "01000",
                "VIL": "BROU"
            }
        }
    ],
    "infos": ""
}

Lecture simple avec conditions

Exemple de demande de lecture de la table de codes postaux, avec conditions LIKE et liste de champs :

{

"dhoq":"gtrstab.dhoq",
"recordsql":"CODEPOSTAL",
"access_token":"xxxxxx",
"parameters":"",
"fields":"CPOSTAL;VIL",
"where":"like_cpostal",
"where_parameters":"cpostal=67%",
"offset":0,
"count":100,
"orderby":"",
"having":"",
"having_parameters":"",
"infos":""
}

Réponse :

{
    "error": 0,
    "txterr": "",
    "tablename": "T057",
    "nbrecord": 1,
    "records": [
        {
            "record": {
                "CPOSTAL": "67000",
                "VIL": "STRASBOURG"
            }
        }
    ],
    "infos": ""
}

Lecture avec pagination

Exemple de demande de lecture de la table des modes de règlement avec pagination par 10 : Première lecture

{
"dhoq" : "gtrstab.dhoq",
"recordsql" : "MODEREGLEMENT",
"access_token" : "xxxxxx",
"parameters" : " ",
"fields" : "*",         
"where" : " ",
"where_parameters" : " ",
"offset" : 0,
"count" : 10,
"orderby" :  " ",
"having" : " ",
"having_parameters" : " ",
"infos" : " " 
}

Réponse :

{
    "error": 0,
    "txterr": "",
    "tablename": "T006",
    "nbrecord": 10,
    "records": [
        {
            "record": {
                "DOS": "998",
                "REGL": "B30",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "B30F",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "C",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "N10",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "N30",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "P30",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "P30F",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "T30",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "T30F",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "T60",
                "LIB": ""
            }
        }
    ],
    "infos": ""
}

La réponse indique un NBRECORD qui vaut le COUNT demandé, donc il faut une seconde lecture:

{
"dhoq" : "gtrstab.dhoq",
"recordsql" : "MODEREGLEMENT",
"access_token" : "xxxxxx",
"parameters" : "",
"fields" : "DOS;REGL;LIB",          
"where" : " ",
"where_parameters" : " ",
"offset" : 10,
"count" : 10,
"orderby" :  " ",
"havingc" : " ",
"having_parameters" : " ",
"infos" : " " 
}

Réponse :

{
    "error": 0,
    "txterr": "",
    "tablename": "T006",
    "nbrecord": 9,
    "records": [
        {
            "record": {
                "DOS": "998",
                "REGL": "T60F",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "TMUL",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "V30",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "V30F",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "E",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "TMEN",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "VIR",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "VII",
                "LIB": ""
            }
        },
        {
            "record": {
                "DOS": "998",
                "REGL": "SEPA",
                "LIB": ""
            }
        }
    ],
    "infos": ""
}

La réponse indique un NBRECORD différent de COUNT, donc c'est terminé

Lecture avec champs, clause where join et orderby

Exemple de demande de lecture de la table des articles pour une plage de code ean, trié par ean, en récupérant 3 champs, sans jointures et sans autres colonnes

{
"dhoq" : "gtrsart.dhoq",
"recordsql" : "ARTICLE",
"access_token" : "xxxxxx",
"parameters" : "",
"fields" : "DOS;REF;EAN",           
"where" : "Between_Ean",
"where_parameters" : "eanD=3000000000000;eanF=4000000000000",
"offset" : 0,
"count" : 5,
"orderby" :  "Par_CodeEAN",
"having" : " ",
"having_parameters" : " ",
"infos" : "<joindeactivate>$ALL<columndeactivate>$ALL" 
}

Réponse :

{
    "error": 0,
    "txterr": "",
    "tablename": "ART",
    "nbrecord": 5,
    "records": [
        {
            "record": {
                "DOS": "998",
                "REF": "FCR0011",
                "EAN": "3210330000250"
            }
        },
        {
            "record": {
                "DOS": "998",
                "REF": "CPAQ0009",
                "EAN": "3210330003821"
            }
        },
        {
            "record": {
                "DOS": "998",
                "REF": "FPN0104",
                "EAN": "3210330017159"
            }
        },
        {
            "record": {
                "DOS": "998",
                "REF": "X0000018",
                "EAN": "3210330017585"
            }
        },
        {
            "record": {
                "DOS": "998",
                "REF": "FPT0061",
                "EAN": "3210330021356"
            }
        }
    ],
    "infos": ""
}

Interrogation token

Exemple de demande d’informations concernant le token

{
"dhoq" : "a5rsdos.dhoq",
"recordsql" : "Utilisateur",
"access_token" : "{{TOKEN}}",
"infos" : "<infostoken>1" 
}

Réponse :

{
"error": 0,
"txterr": "",
"tablename": "MUSER",
"nbrecord": 1,
"records": [
],
"infos": "{\"InfosToken\":{\"ExpireLocalTime\":\"20230314174105\",\"ExpireUtcTime\":\"20230314164105\",\"ExpireMinutes\":\"0\",\"ExpireLocalTimeName\":\"Romance Standard Time\",\"Env\":\"\",\"User\":\"\",\"Domain\":\"\"}}"
}