SilImporterFichier()

Définition :
Cette fonction permet d’intégrer le contenu d’un fichier au format CSV dans une table de la base de données de l’ERP passée en paramètre.

Syntaxe :
SilImporterFichier("Nom du fichier", "Nom de la table de destination", "Paramètres d'import").
ou
SIF("Nom du fichier", "Nom de la table de destination", "Paramètres d'import").

Trois paramètres :

Le nom du fichier à lire qui contiendra les données à intégrer
Le nom du fichier doit comporter l’extension et n’est pas exclusivement réservé aux fichiers csv. Il peut contenir le chemin complet pour y accéder ou le chemin relatif à partir de celui de l’ERP.
Important : Le fichier doit être enregistré au format ANSI.
Le nom de la table de destination
Le nom de la table SQL de destination est obligatoire et doit commencer par « GPSQL. » ou « [GPSQL]. ». Cette contrainte permet de s’assurer que la fonction ne sera pas utilisée pour intégrer des données dans les tables de l’ERP.
Important : La table doit exister dans la base de données de l’ERP.

3 : Les paramètres de description du fichier source et de comportement du traitement : Ce paramètre est optionnel. S’il n’est pas renseigné, le traitement d’import fonctionnera en appliquant des paramètres par défaut.

Les valeurs par défaut :

Si aucun paramètre n’est fourni à la fonction concernant la description du fichier source, la fonction considérera le fichier source comme un fichier :

=> Au format CSV,
=> Utilisant le caractère ‘;’ comme séparateur de colonnes,
=> Ayant les entêtes de colonnes sur la première ligne du fichier,
=> Utilisant le point comme séparateur décimals,
=> Utilisant un format de date compatible avec le moteur SQL,
=> Utilisant les guillemets comme identificateur de texte,
=> Ayant ses colonnes de mêmes noms que les colonnes de la table de destination.

De plus les données présentes dans le fichier sont ajoutées dans la table de destination.

La description du fichier d'export :

Les paramètres de fonctionnement de l’import peuvent être enregistrés dans un fichier texte au format d’un fichier ini. Dans ce cas, le paramètre contiendra la chaîne de caractères ‘’FICHIER={chemin+nom du fichier}’’.

L’exemple ci-dessous présente le contenu possible d’un fichier de description d’un import d’un fichier dans une table. Ce contenu peut donc être stocké dans un fichier dont le chemin d’accès sera passé en paramètre à la fonction ou bien dans une chaîne de caractères directement passée en paramètre de la fonction.

Cette description reprend le formalisme d’un fichier ini avec des sections et des valeurs. Il est important que :

Les crochets soient présents pour définir le nom de la section.
Qu'il n'y ait pas d'espace autour du signe égal entre le nom de la propriété et sa valeur.
Que la casse soit respectée dans le nom des sections et des propriétés.

La section [FileDescription] du fichier mis en 3ème paramètre :

Un fichier de type CSV peut contenir les entêtes de colonnes et des colonnes définies de différentes manières comme avec des largeurs fixes ou non.

Il est donc possible de préciser ces informations avec les propriétés suivantes :

FixeWidth : Cette propriété permet d’indiquer que les largeurs des colonnes sont d’une largeur fixe en nombre de caractères (1=oui). Par défaut, le traitement considère que les largeurs ne sont pas fixes (0=non). Si le fichier est défini selon des colonnes fixes, la section [FileColumns] devient obligatoire.
ColumnsHeader : Valeur 1 (oui) ou 0 (non), cette propriété permet de préciser si les entêtes de colonnes sont présentes en première ligne du fichier ou non.
ColumnsSeparator : Caractère, cette propriété permet de préciser le caractère à utiliser pour indiquer le changement de colonnes, ‘ ;’ Par défaut. Il faut indiquer la chaîne ‘TAB’ à ce niveau pour indiquer que le caractère de séparation correspond à la tabulation.
TextIdentificator : Caractère, cette propriété permet de préciser le caractère utilisé pour identifier des chaînes de caractères dans les valeurs des colonnes quand elles peuvent contenir le caractère de séparation des colonnes. Guillemet (‘’) par défaut et limité à un seul caractère.
SeparatorDecimal : Caractère, indique le caractère utilisé comme séparateur décimal pour les valeurs numériques. Le traitement considère le point comme caractère par défaut.

Si aucun format de date et heure n’est mentionné dans les paramètres de fonctionnement, le traitement d’import enverra dans la colonne de date la chaîne de caractères trouvée dans le fichier source sans transformation de la date et heure contenue. Il convient donc dans ce cas de s’assurer de la compatibilité du format contenu dans le fichier avec le serveur SQL.

Dans le cas d’un format de date et heure présent dans le fichier source non reconnu par le serveur SQL (exemple : format anglais dans le fichier et base de données en français), il est alors nécessaire de fournir le format de date présent dans le fichier à l’aide des définitions suivantes :

ShortDateFormat : Cette propriété permet de préciser la position de l’année, du mois et du jour dans la chaîne de caractères qui représentera une date dans les colonnes du fichier source. Il convient d’utiliser la convention suivante : yyyy pour l’année, MM pour le mois et dd pour le jour. Si un caractère de séparation est utilisé pour distinguer les différents éléments qui constituent la date, il doit être représenté par le caractère ‘/’ dans la définition du format. Il devra être également précisé dans la définition DateSeparator.
DateSeparator : Il s’agit du caractère utilisé pour séparer les différents éléments qui constituent la date. Utiliser le code ‘EMPTY’ pour indiquer qu’aucun séparateur n’est utilisé.
ShortTimeFormat : Permet de préciser le format utilisé pour représenter une heure dans la chaîne de caractères. Si un caractère de séparation est utilisé pour distinguer les différents éléments qui constituent l’heure, il doit être représenté par le caractère ‘:’ dans la définition du format. Il devra être également précisé dans la définition TimeSeparator. Il convient d’utiliser la convention suivante pour représenter les différents éléments constitutifs d’une heure : hh pour l’heure, mm pour les minutes et ss pour les secondes.
TimeSeparator : Il s’agit du caractère de séparation utilisé pour distinguer les différents éléments qui constituent une heure : heure, minutes et secondes.

Il est important de noter que le caractère espace est utilisé pour séparer la date de l’heure dans une chaîne de caractères.

Exemples de description de formats de date et heure :

La chaîne 2013-08-29 12.10.20 de représentation d’une date et heure dans un fichier CSV doit être décrite de la manière suivante dans la section [FileDescription] :
La chaîne 20130829 121020 doit être décrite de la manière suivante :
La chaîne 29/08/2013 12:10:20 doit être décrite de la manière suivante :

La section [FileColumns] du fichier mis en 3ème paramètre :

Elle permet de préciser la largeur des colonnes présentes dans le fichier dans le cas où celui-ci est décrit comme ayant des largeurs fixes.
Si le fichier contient en première ligne les entêtes des colonnes, il convient alors de reprendre les libellés des colonnes pour indiquer la largeur de chacune d’elles.
Si le fichier ne contient pas de ligne d’entête pour les colonnes, il faut alors utiliser un indice pour indiquer le numéro de colonne concerné. Cet indice est 1 pour la première colonne, 2 pour la deuxième, etc …

Exemple de fichiers, avec une ligne d'entête :

Exemple de fichiers, sans ligne d'entête :

La section [ColumnsMapping] du fichier mis en 3ème paramètre :

La section [ColumnsMapping] permet de lier les colonnes du fichier avec celles de la table de destination.
Elle consiste à associer le nom ou l’indice de la colonne du fichier source avec le nom de la colonne de la table comme le montre l’exemple ci-dessous.

A gauche le nom de la colonne dans le fichier, à droite le nom de la colonne dans la table

Cette section est nécessaire quand les noms des colonnes du fichier ne correspondent pas à ceux de la table de destination ou quand les colonnes du fichier n’ont pas de nom et que l’ordre des colonnes du fichier ne correspond pas à celui des colonnes de la table.
Cette section n’est pas obligatoire et nécessaire si :

Les noms des colonnes du fichier correspondent au nom des colonnes de la table : Le mappage se fera automatiquement à partir du nom des colonnes
Les noms des colonnes ne sont pas présents dans le fichier et l’ordre des colonnes du fichier correspond à celui de la table de destination : Le mappage se fera en mettant dans la première colonne de la table la première colonne du fichier, dans la deuxième colonne de la table la deuxième colonne du fichier, et ainsi de suite pour toutes les colonnes du fichier et celles de la table.

La section [TableDescription] du fichier mis en 3ème paramètre :

La section [TableDescription] permet de spécifier les actions à mener sur la table de destination pour vider ou non la table avant d’insérer les données du fichier et le nombre de requêtes d’insertion par instruction envoyée au serveur SQL.
Cette section n’est pas obligatoire. Si elle n’est pas présente, le traitement d’import des données du fichier source dans la table de destination ne videra pas la table avant l’insertion et minimisera le nombre de commandes SQL envoyées au serveur.

ClearTableBeforeInsert : Permet d’indiquer si la table doit être vidée avant d’insérer les données du fichier source : 1 = oui, 0=non.
Par défaut, la table n’est pas vidée.
UseTruncateTabletoClear : Permet d’indiquer d’utiliser la commande SQL ‘TRUNCATE TABLE’ pour vider la table au lieu de la commande ‘DELETE’. La commande Truncate est plus rapide et moins consommatrice de ressources SQL dans le journal de la base de données. Utiliser 1 pour indiquer l’utilisation de la commande ‘Truncate’. Par défaut la commande ‘Delete’ est utilisée.
NbLinePerQuery : Permet d’indiquer le nombre de lignes du fichier source à envoyer par lot d’instruction SQL exécuté sur le moteur de base de données de l’ERP.
Si la valeur de la propriété est à zéro (valeur par défaut), le traitement d’import constituera une commande SQL avec autant de commandes INSERT qu’il lui est possible d’ajouter en fonction de la taille maximale autorisée qu’une commande SQL peut contenir (par défaut cette limite est fixée à 65000 caractères).
Le fonctionnement par défaut fixé permet d’optimiser les performances d’exécution de la commande d’insertion en minimisant le nombre d’échange entre le poste et le serveur SQL. En revanche, en cas d’erreur de syntaxe SQL lors de l’insertion comme par exemple un mauvais formatage de la date ou une donnée manquante obligatoire, celle-ci portera sur l’ensemble des requêtes INSERT présentes dans la commande envoyée au serveur.
Donc en cas d’erreur sur des données présentes dans le fichier source, il sera intéressant de positionner cette propriété à 1 pour limiter l’instruction SQL à une seule instruction INSERT et ainsi obtenir la ligne du fichier source qui pose problème lors de l’insertion des données dans la table.

L’exemple ci-dessous indique au traitement de vider la table avant l’insertion des données en utilisant l’instruction ‘TRUNCATE TABLE’ et d’envoyer les lignes du fichier une par une dans la table.

Les valeurs de retour :

La fonction retourne 0 quand aucune erreur n’a été détectée lors du traitement d’import des données du fichier source dans la table de destination.
Si une erreur a été détectée, la fonction retournera une valeur différente de 0 :
=> 11001 : Le fichier source est introuvable.
=> 11003 : Impossible d’ouvrir le fichier source.
=> 11004 : Le nom du fichier source est vide.
=> 11005 : Aucune colonne définie pour le fichier source.
=> 11006 : Les colonnes n’ont pas de largeur définie
=> 12001 : La table de destination ne commence pas par GPSQL. Ou [GPSQL].
=> 12002 : La table de destination n’existe pas dans la base de données de l’ERP.
=> 12003 : Une erreur SQL s’est produite lors de l’exécution de l’instruction d’insertion des données dans la table de destination

Exemple de paramétrage :

SIF("Articles.csv","GPSQL.ABArticles","FICHIER=ParamSIF.txt")