Fichier Lisezmoi pour l'exemple d'utilitaire de ligne de commande ascmd

Mis à jour : 12 décembre 2006

L'utilitaire de ligne de commande ascmd permet à un administrateur de base de données d'exécuter un script XMLA, une requête MDX ou une instruction DMX sur une instance de Microsoft SQL Server 2005 Analysis Services (SSAS). Cette utilitaire de la ligne de commande contient des fonctionnalités destinées à Analysis Services qui s'apparentent à l'utilitaire sqlcmd inclus dans SQL Server 2005. Pour plus d'informations, consultez la rubrique Utilitaire sqlcmd dans SQL Server 2005. Les résultats de l'exécution du script, de la requête ou de l'instruction peuvent être stockés dans un fichier avec les informations de trace pertinentes du Générateur de profils SQL Server. Par défaut, l'emplacement d'installation de l'utilitaire de ligne de commande ascmd est le suivant :

<system_drive>\Program Files\Microsoft SQL Server\90\Samples\Analysis Services\Administrator\ascmd

Scénarios

Les scénarios suivants proposent des exemples d'utilisation de l'utilitaire de ligne de commande ascmd.

Traitement d'une partition à partir d'un outil tiers

Un administrateur de base de données doit traiter des partitions et des dimensions dans le cadre d'un processus d'extraction, de transformation et de chargement (ETL) toutes les nuits. L'outil ETL n'est pas un outil SQL Server et l'administrateur de base de données ne peut pas utiliser la prise en charge intégrée des scripts XMLA de l'Agent SQL Server ou bien exécuter un package SQL Server 2005 Integration Services (SSIS). L'administrateur de base de données souhaite une solution automatisée qui utilise un outil tiers. La solution est un utilitaire de la ligne de commande qui exécute un script XMLA. L'utilitaire est ensuite appelé de l'outil tiers. L'administrateur de base de données charge et compile l'exemple d'utilitaire de ligne de commande ascmd. Après la compilation, l'administrateur de base de données peut recourir à l'utilitaire de ligne de commande ascmd en vue d'exécuter des scripts XMLA conçus pour traiter des partitions et des dimensions.

Sauvegarde d'une base de données OLAP à partir d'un outil tiers

La même société requiert un autre administrateur de base de données pour automatiser la sauvegarde d'une base de données Analysis Services. Une fois encore, étant donné que le logiciel de planification utilisé par la société n'est pas un outil SQL Server, cette tâche doit être exécutée à partir de la ligne de commande. L'administrateur de la base de données génère le script XMLA approprié (à l'aide de SQL Server Management Studio). Le logiciel de planification tiers utilise ensuite l'utilitaire de ligne de commande ascmd pour exécuter le script XMLA et sauvegarder la base de données OLAP.

Utilisation d'un script XMLA lors de l'installation

Un éditeur de logiciels requiert un développeur pour intégrer l'exécution d'un script XMLA directement dans l'installation d'un produit de la société. Le développeur doit exécuter un script XMLA et récupérer l'état (et les événements de trace) pour savoir si la base de données Analysis Services a été créée correctement. Il peut utiliser l'utilitaire de ligne de commande ascmd pour effectuer cette opération.

Langages

• C#, le langage de l'utilitaire de ligne de commande ascmd.
• Fichiers de commandes chargés de démarrer l'utilitaire de ligne de commande ascmd.

Configuration requise

Pour utiliser efficacement l'utilitaire de ligne de commande ascmd, vous devez installer tous les logiciels suivants ou certains d'entre eux :

• Microsoft SQL Server 2005 Analysis Services (SSAS)
  Une instance de Analysis Services doit être installée et en cours d'exécution, car l'utilitaire de ligne de commande ascmd permet de se connecter à une instance de Analysis Services et d'exécuter des requêtes MDX, des scripts XMLA et des instructions DMX.

• SQL Server Management Studio et Business Intelligence Development Studio
  Ces deux environnements de travail fournissent l'infrastructure de prise en charge permettant d'effectuer toute tâche liée à Analysis Services. Vous pouvez implémenter une tâche donnée par le biais de l'interface utilisateur ou par programme.

• Objets AMO (Analysis Management Objects)
  AMO est nécessaire pour exécuter l'utilitaire de ligne de commande ascmd sur un ordinateur sur lequel Analysis Services n'est pas installé. AMO peut être installé à partir du Feature Pack de SQL Server 2005, que vous pouvez télécharger en accédant au Centre de téléchargement Microsoft à l'adresse suivante : https://www.microsoft.com/downloads.

• .NET Framework 2.0
  Le programme .NET Framework 2.0 est nécessaire pour l'exécution de l'utilitaire de ligne de commande ascmd. Vous pouvez télécharger ce programme sur le Centre de téléchargement Microsoft à l'adresse suivante https://www.microsoft.com/downloads.

• Microsoft Visual Studio 2005 ou .NET Framework SDK 2.0
  Nous vous recommandons d'utiliser le programme Visual Studio 2005 au moment de créer et de personnaliser l'application exemple ascmd. Si vous ne disposez pas du programme Visual Studio 2005, optez pour le kit .NET Framework SDK 2.0. Le Kit de développement .NET Framework SDK contient MSBuild.exe (consultez « Compilation de l'exemple » plus loin dans ce document).

• Base de données Adventure Works DW fournie avec SQL Server 2005
  Les exemples de bases de données sont utiles pour tester l'utilitaire de ligne de commande ascmd. Pour plus d'informations, consultez Installation des exemples de bases de données AdventureWorks et d'autres exemples via le programme d'installation dans la documentation en ligne de SQL Server 2005.

  Une version mise à jour de la base de données AdventureWorks est également disponible pour téléchargement sur la page Web du SQL Server Developer Center (Centre des développeurs SQL Server).

  Une version mise à jour des exemples du moteur de base de données SQL Server 2005 est également disponible pour téléchargement sur la page Web du SQL Server Developer Center (Centre des développeurs SQL Server).

Arguments

Les arguments ci-après sont pris en charge à partir de la ligne de commande de l'utilitaire ascmd.

• –Ulogin_id
  Représente l'ID de connexion (casse indifférente).

  Remarque :
  L'utilisation de login_id diffère pour l'utilitaire sqlcmd et l'utilitaire ascmd. Dans l'utilitaire sqlcmd, login_id représente une connexion SQL Server alors que dans l'utilitaire ascmd cet argument représente une connexion Windows.

  Pour l'accès TCP/IP, Analysis Services prend uniquement en charge les connexions approuvées. Si vous spécifiez le paramètre –U (et le mot de passe correspondant à l'aide du paramètre –P), l'utilitaire de ligne de commande ascmd ouvre une session Windows en utilisant le compte spécifié, puis emprunte l'identité du compte lors de l'exécution d'un script XMLA, d'une requête MDX ou d'une instruction DMX. L'ID de connexion doit se présenter sous la forme suivante <domaine>\<nom d'utilisateur>, et le domaine doit être spécifié. Si le paramètre –U n'est pas spécifié, l'authentification est basée sur le compte Windows de l'utilisateur qui exécute l'utilitaire de ligne de commande ascmd.

  Si une connexion HTTP (ou HTTPS) est spécifiée par le paramètre –S, l'utilitaire de ligne de commande ascmd n'ouvre pas de session Windows. Les paramètres –U et –P (s'ils sont spécifiés), font partie intégrante de la chaîne de connexion au serveur IIS (Internet Information Services). Selon la configuration d'IIS, les paramètres –U et –P peuvent être utilisés pour l'authentification de base. Pour plus d'informations sur le paramètre de chaîne de connexion UID, consultez Classe AdomdConnection dans la documentation en ligne de SQL Server 2005.

• –Ppassword
  Mot de passe spécifié par l'utilisateur correspondant au paramètre –U. Si vous spécifiez le paramètre –U mais pas le paramètre –P, le mot de passe est considéré comme vide (chaîne vide de longueur nulle). Si vous spécifiez le paramètre –P mais pas le paramètre –U, le paramètre –P est ignoré.

  Remarque relative à la sécurité :

  N'utilisez pas de mot de passe vide. Utilisez un mot de passe fort. Pour plus d'informations, consultez Mots de passe forts dans la documentation en ligne de SQL Server 2005. Le mot de passe du paramètre –P est stocké en texte clair dans le fichier de script, de requête ou d'instruction ; il est visible par tous les utilisateurs qui ont accès au moniteur de l'ordinateur ou au fichier lui-même. Si vous utilisez cette fonction, appliquez des listes de contrôle d'accès (ACL) aux fichiers ou utilisez d'autres techniques de sécurité pour vous assurer que seuls les utilisateurs approuvés peuvent lire les fichiers.

• –Sserver\instance ou –Shttp[s]://server[:port]/virtualdirectory/msmdpump.dll
  Indique l'instance Analysis Services à laquelle l'utilitaire de ligne de commande ascmd se connectera et sur laquelle il s'exécutera. Si le paramètre –P n'est pas spécifié, l'utilitaire de ligne de commande ascmd se connecte à l'instance par défaut de Analysis Services sur l'ordinateur local qui exécute TCP (connexion à localhost), puis exécute le script XMLA, la requête MDX ou l'instruction DMX.

• –ddatabase
  Indique la base de données dans laquelle la requête MDX ou l'instruction DMX s'exécutera. Le paramètre –d est ignoré si l'utilitaire de ligne de commande ascmd exécute un script XMLA, car le nom de la base de données est incorporé dans les scripts XMLA.

• –tquery-timeout
  Indique le nombre de secondes avant l'expiration de l'exécution d'un script XMLA, d'une requête MDX ou d'une instruction DMX. L'utilitaire de ligne de commande ascmd ajoute la clause TIMEOUT =<query-timeout> à la chaîne de connexion.

• –tcconnect-timeout
  Indique le nombre de secondes avant l'expiration de la connexion de l'utilitaire ascmd à l'instance Analysis Services. L'utilitaire de ligne de commande ascmd ajoute la clause CONNECT TIMEOUT = <connect-timeout> à la chaîne de connexion.

• –iinput-file
  Identifie le fichier qui contient le script XMLA, la requête MDX ou l'instruction DMX. Vous devez spécifier une valeur pour le paramètre –i ou –Q lorsque vous utilisez l'utilitaire de ligne de commande ascmd. Si vous ne spécifiez aucun paramètre –i ou –Q, ou bien spécifiez les deux à la fois, le système génère une erreur.

  Remarque :
  Contrairement à l'utilitaire de ligne de commande sqlcmd (qui gère plusieurs fichiers d'entrée), l'utilitaire de ligne de commande ascmd ne traite qu'un seul fichier d'entrée à la fois. Si vous disposez de plusieurs fichiers d'entrée, chacun d'eux doit être appelé et exécuté séparément.

  Le fichier d'entrée spécifié avec le paramètre –i ou –Q doit avoir une structure XML valide et les caractères spéciaux doivent être codés au format HTML. Par exemple, lorsque vous utilisez une perluète (&) dans votre texte, ce caractère doit être codé sous la forme &. Ainsi, [Produit].&1922] doit être codé [Produit].&amp;[1922]. De même, un signe inférieur à (<) doit être codé sous la forme <, un caractère supérieur à (>) sous la forme > et les guillemets doubles (") sous la forme ". Cela est essentiel pour les requêtes MDX et les instructions DMX car la syntaxe des clés de membre utilise le symbole « et » commercial (&).

  Remarque :

  Si le texte d'entrée ne ressemble pas à un script XMLA, ce qui signifie qu'il ne commence pas par une commande XMLA valide comme <Statement> ou <Create> (voir la liste complète plus loin dans ce document), l'utilitaire de ligne de commande ascmd part alors du principe que le texte est une commande <Statement> et code ensuite le texte au format HTML pour vous et l'inclut dans une balise d'élément XML <Statement> … </Statement>. Cette opération est effectuée pour faciliter l'exécution de requêtes MDX et d'instructions DMX. Si vous souhaitez utiliser des éléments <Statement> et écrire vous-même le texte HTML, il vous est possible de le faire. L'utilitaire de ligne de commande ascmd accepte toutes les commandes XMLA valides.

  Un fichier d'entrée peut comprendre plusieurs lots d'instructions séparés par des commandes GO. Chaque lot d'instructions au sein d'un fichier d'entrée peut contenir un script XMLA, une requête MDX ou une instruction DMX. Chaque commande GO doit figurer sur une seule ligne. Lorsqu'une commande GO est trouvée, le système envoie au serveur l'entrée qui précède la commande GO. Une commande GO implicite se trouve à la fin du flux d'entrée. Le fichier de sortie généré est formaté en insérant les flux XML retournés dans un élément de <lots multiples>. Consultez le Scénario 11 pour un exemple d'un fichier d'entrée qui contient des lots multiples.

  Chaque lot s'exécute, aboutit ou échoue indépendamment. L'état de retour de chaque lot est enregistré dans le fichier de sortie que vous devez analyser pour déterminer le succès ou l'échec de chaque lot.

• –ooutput-file | NUL | NUL:filename
  Identifie le fichier qui reçoit les résultats (au format XML) du script XMLA ou un jeu de cellules retourné par la requête MDX ou l'instruction DMX. Si le fichier spécifié existe déjà, il est automatiquement remplacé. Les noms de fichiers comportant des espaces doivent être placés entre guillemets (""). Si le nom du fichier n'est pas valide, un message d'erreur est généré et l'utilitaire de ligne de commande ascmd se ferme.

  L'utilitaire de ligne de commande ascmd ne prend pas en charge l'écriture simultanée de plusieurs processus ascmd dans le même fichier ; si vous tentez d'effectuer cette opération, le fichier sera corrompu ou incorrect.

  Si le fichier de sortie spécifié est NUL ou NUL:filename, les résultats de l'exécution sont ignorés, sauf si vous utilisez le paramètre –T pour spécifier un fichier de trace, auquel cas les résultats sont stockés dans ce dernier. Il est utile de spécifier un fichier de sortie NUL avec le paramètre –T lorsque vous spécifiez un niveau de trace Duration avec le paramètre –Tl.

  Par exemple, vous pouvez créer une série de requêtes MDX et les exécuter à l'aide de l'utilitaire de ligne de commande ascmd, ignorer la sortie (qui peut être très volumineuse), enregistrer la durée des requêtes dans un fichier de trace, puis charger ces valeurs dans une base de données. Vous pouvez ainsi évaluer les écarts de performance dans le temps. Vous pouvez également opter pour le niveau de trace Duration-result et le paramètre –Tl pour inclure à la fois la durée et le résultat de l'exécution dans le fichier de trace.

  Remarque :

  L'utilitaire de ligne de commande ascmd prend en charge le format de codage international. Les fichiers d'entrée et de sortie utilisent le codage UTF-8 avec les indicateurs d'ordre des octets activés. Si votre éditeur de texte ne prend pas en charge le format UTF-8 et qu'une requête MDX, un script XMLA ou une instruction DMX comporte des caractères internationaux, vous pouvez utiliser le Bloc-notes pour convertir le fichier d'entrée au format UTF-8. Pour ce faire, ouvrez-le dans le Bloc-notes, dans le menu Fichier, cliquez sur Enregistrer sous, puis dans la zone de texte Codage, sélectionnez UTF-8. Vous pouvez ensuite utiliser le fichier avec le paramètre –i. Les fichiers de sortie et de trace (–o et –T) sont toujours écrits avec le codage UTF-8 et les indicateurs d'ordre des octets pour garantir la conservation des caractères Unicode.

• –Ttrace-file
  Identifie un fichier qui reçoit des événements de trace Analysis Services à partir de l'utilitaire de ligne de commande ascmd qui exécute le script XMLA, la requête MDX ou l'instruction DMX. Si le fichier existe déjà, il est automatiquement remplacé (à l'exception des fichiers de trace créés avec les paramètres –TlDuration et –TlDuration-result). Les noms de fichiers comportant des espaces doivent être placés entre guillemets (""). Si le nom du fichier n'est pas valide, un message d'erreur est généré et l'utilitaire de ligne de commande ascmd se ferme.

  L'utilitaire de ligne de commande ascmd ne prend pas en charge l'écriture simultanée de plusieurs processus ascmd dans le même fichier ; si vous tentez d'effectuer cette opération, le fichier sera corrompu ou incorrect. Si le paramètre –T n'est pas spécifié, la sortie de trace n'est pas capturée et les paramètres –Tf, –Tl, Td et –Tt sont ignorés.

  Remarque :
  Le paramètre –T n'est pas disponible pour les connexions HTTP ou HTTPS. Vous devez utiliser une connexion client/serveur ordinaire en spécifiant le paramètre –S.

• –xcextended-connect-string
  Indique une chaîne de connexion étendue insérée directement dans la chaîne de connexion, sans contrôle des valeurs. La chaîne ne doit pas comporter de point-virgule à droite ou à gauche (;). Par exemple, la chaîne de connexion étendue ci-après change la taille des paquets réseau utilisée entre le serveur et le processus ascmd de 4 096 à 16 384 et demande également que les paramètres régionaux du client soient définis sur en-US (Anglais États-Unis) :

  -xc "Packet Size=16384;LocaleIdentifier=1033"

  Par défaut, l'utilitaire de ligne de commande ascmd n'ajoute aucune information de chaîne de connexion étendue. De nombreuses options de l'utilitaire de ligne de commande ascmd peuvent être implémentées comme paramètre de chaîne de connexion étendue (par exemple, en définissant Database=<database name> directement). Cependant, nous vous recommandons d'utiliser les options ascmd standard lorsque cela est possible et d'opter pour des paramètres de chaîne de connexion étendue uniquement si aucune autre méthode n'est disponible.

• –Tftext | csv
  Indique le format de fichier pour le paramètre –T (si ce paramètre est spécifié). La valeur par défaut est csv. Les options disponibles sont les suivantes :

  • Pour l'option text, le fichier est écrit au format texte. Voici quelques exemples de format :
    <current time> <event-class>.<event-subclass>, [name=value]
  • Pour l'option csv, le fichier est écrit au format séparé par des virgules. Le délimiteur de colonnes par défaut est | (barre verticale) ; le paramètre –Td permet de modifier le délimiteur par défaut pour un fichier csv. La première ligne du fichier indique les en-têtes des colonnes de valeurs.

• –Tddelim-char
  Spécifie un seul caractère comme délimiteur de fichier de trace lorsque vous sélectionnez le format CSV comme format de fichier de trace à l'aide du paramètre –Tf. Le délimiteur par défaut est | (barre verticale).

• –Tttrace-timeout
  Indique le nombre de secondes pendant lesquelles le moteur Analysis Services patiente avant d'achever la trace (si vous spécifiez le paramètre –T). Une trace est considérée terminée si aucun message de trace n'a été enregistré au cours de la période spécifiée. La valeur de délai d'attente de la trace par défaut est de 5 secondes.

• –Tltrace-level
  Indique quelles données sont collectées et enregistrées dans le fichier de trace. Cinq valeurs sont possibles :

  • High – enregistre tous les événements de trace ; valeur par défaut.
  • Medium – enregistre tous les événements de trace, à l'exception des événements ProgressReportCurrent et Notification.
  • Low – enregistre uniquement les événements de trace contenant « End » ou « Error ».
  • Duration – n'enregistre aucun événement de trace, mais détermine à la place la durée d'exécution du script, de la requête ou de l'instruction via le processus ascmd. Écrit une seule entrée dans le fichier de trace indiquant l'heure actuelle, la durée, le texte d'exécution, la base de données et le nom du serveur.
  • Duration-result – enregistre les mêmes informations que le paramètre Duration ainsi que le résultat de l'exécution dans la dernière colonne du fichier de trace.

  Remarque :

  Les fichiers de trace générés avec les paramètres Duration et Duration-result ne sont pas remplacés à chaque exécution (comme cela est le cas avec les fichiers de trace générés avec les paramètres High, Medium et Low). Avec les paramètres Duration et Duration-result, si un fichier de trace existe déjà, il est ouvert et les nouvelles valeurs sont insérées à la fin du fichier. Si le fichier de trace n'existe pas, il est créé.

• –Q*"cmdline query or script"*
  Spécifie le script, la requête ou l'instruction directement sur la ligne de commande plutôt que dans un fichier.

  Remarque :

  L'utilitaire de ligne de commande sqlcmd permet de spécifier une requête d'entrée d'une autre façon (à l'aide du paramètre –q). Malheureusement, cette option lit les données dans sysinput et vous ne pouvez pas l'écrire sans ajouter des langages de construction. Par exemple, l'utilitaire sqlcmd utilise « go » et « exit » pour contrôler les commandes sysinput. Cette méthode de spécification d'entrée de requête supplémentaire n'est pas prise en charge par l'utilitaire de ligne de commande ascmd.

• –v var=value...
  Spécifie des variables de script supplémentaires. Chaque variable est une paire var=value. Si la valeur contient des espaces ou des caractères de contrôle incorporés, elle doit figurer entre guillemets ("). Par exemple :

  -v maxparallel=4 option= "degree of freedom"

  Vous pouvez spécifier aucune, une ou plusieurs paires var=value.

• –? ou /?
  Affiche un résumé de la syntaxe des options de l'utilitaire de ligne de commande ascmd.

Chiffrement des clés et génération de l'exemple

Si vous n'avez pas encore créé un fichier de clé de nom fort, utilisez la procédure suivante pour générer ce fichier.

Pour générer un fichier de clé de nom fort

1. Ouvrez une invite de commandes Microsoft Visual Studio 2005. Cliquez sur Démarrer, pointez sur Tous les programmes et sur Kit de développement Microsoft .NET Framework SDK 2.0, puis cliquez sur Invite de commandes du Kit de développement SDK.

   -- Ou --

   Ouvrez une invite de commandes Microsoft .NET Framework. Cliquez sur Démarrer, pointez sur Tous les programmes et sur Kit de développement Microsoft .NET Framework SDK 2.0, puis cliquez sur Invite de commandes du Kit de développement SDK.

2. Utilisez la commande CD (changer de répertoire) pour remplacer le dossier actif dans la fenêtre de l'invite de commandes par le dossier dans lequel les exemples sont installés.

   Remarque :

   Pour déterminer le dossier dans lequel se trouvent les exemples, cliquez sur le bouton Démarrer, pointez successivement sur Tous les programmes, sur Microsoft SQL Server 2005 et sur Documentation et didacticiels, puis cliquez sur le répertoire Samples. Si l'emplacement d'installation par défaut a été utilisé, les exemples se trouvent dans <lecteur_système>:\Program Files\Microsoft SQL Server\100\Samples.

3. À l'invite de commandes, exécutez la commande suivante pour générer le fichier de clé :

   sn -k SampleKey.snk

   Important :
   Pour plus d'informations sur la paire de clés de nom fort, consultez l'article de sécurité concernant les noms forts et la sécurité dans .NET Framework, dans le Centre de développement .NET sur MSDN.

Vous pouvez compiler l'exemple via l'une des deux approches suivantes.

• À l'aide de Visual Studio 2005, compilez l'exemple en utilisant la solution Visual Studio disponible dans le dossier <chemin_d'installation>\Samples\Analysis Services\Administrator\ascmd\cs.

• À l'aide de MSBuild fourni avec le kit .NET Framework SDK 2.0, compilez l'exemple en exécutant les commandes suivantes à l'invite de commandes :

  cd Analysis Services\Administrator\ascmd\CS\ascmd
  msbuild ascmd.csproj /nologo /v:quiet /p:Configuration=Debug;Platform=<platform>
  

Remarque :
Microsoft Visual Studio est pris en charge à cent pour cent sur des ordinateurs x86 et x64 mais pas sur des ordinateurs Itanium. Une fois l'utilitaire de ligne de commande ascmd compilé, vous pouvez l'exécuter sur n'importe quel ordinateur x86, x-64 ou Itanium.

Dans le code précédent, la valeur de paramètre <platform> peut être x86 pour les ordinateurs 32 bits, x64 pour les ordinateurs x64 ou Itanium pour les ordinateurs IA-64. Il est préférable de compiler la version appropriée de l'utilitaire de ligne de commande ascmd car les performances peuvent être réduites si vous exécutez du code 32 bits sur un ordinateur 64 bits.

Remarque :

Si vous compilez l'utilitaire de ligne de commande ascmd sur un ordinateur dont l'architecture est différente de celle de l'ordinateur cible (par exemple, sur un ordinateur 32 bits avec la valeur de paramètre x64 ou Itanium), vous recevez alors trois messages d'avertissement indiquant que trois DLL système distinctes ne sont pas disponibles (« …cible un processeur différent »). Ce comportement est classique et attendu. Après avoir compilé l'utilitaire de ligne de commande ascmd, copiez l'exécutable compilé sur votre serveur cible et exécutez-le à partir de ce dernier (serveur sur lequel les DLL appropriées sont disponibles).

Utilisation de variables de script et d'environnement

L'utilitaire de ligne de commande ascmd prend en charge les variables de script définies par l'utilisateur et réservées du système. Vous pouvez les utiliser dans des scripts XMLA, des requêtes MDX et des instructions DMS. Les valeurs de ces variables peuvent être renseignées en spécifiant des valeurs de variables d'environnement ou des valeurs de paramètres de ligne de commande.

Les règles suivantes s'appliquent aux variables de script définies par l'utilisateur et aux variables d'environnement :

• Une variable peut contenir un nombre illimité de caractères en minuscules et en majuscules, de chiffres, de tirets (-) ou de traits de soulignement (_).
• Une variable ne peut pas contenir des caractères incorporés ou des caractères de contrôle, p.ex., CR, LF, TAB.

Variables de script réservées du système

Les variables de script réservées du système sont des variables de script définies par l'utilitaire de ligne de commande ascmd pour contenir les valeurs associées à chacun des paramètres de ligne de commande. Dans certains cas, les variables d'environnement peuvent également être utilisées pour contenir les valeurs de ces variables de script réservées du système. En ce qui concerne les variables de script réservées du système que vous pouvez renseigner ou extraire à partir des variables d'environnement et des paramètres de ligne de commande, la valeur spécifiée pour le paramètre de ligne de commande (le cas échéant) remplace toute valeur de variable d'environnement spécifiée.

Le tableau suivant décrit les variables de script réservées du système, les paramètres de ligne de commande associés et le cas échéant, les variables d'environnement associées.

Remarque :
Seules trois variables de script réservées du système peuvent être définies à l'aide d'un paramètre de ligne de commande (les paramètres –i, –o et –T). Il n'existe pas de variable d'environnement ASCMD correspondante pour renseigner la variable de script réservée du système qui correspond à ces trois paramètres de ligne de commande.

Notez que dans certains cas du tableau précédent, plusieurs variables de script réservées du système proviennent d'un seul paramètre ou d'une seule variable d'environnement. Dans l'exemple suivant, les trois variables de script réservées du système sont dérivées du paramètre de la variable d'environnement ASCMDSERVER.

• C:\>SET ASCMDSERVER=http://myserver/my_virtual_dir/msmdpump.dll

L'instruction SET précédente spécifiant une valeur pour la variable d'environnement ASCMDSERVER définit les valeurs ci-après pour les trois variables de script réservées du système suivantes :

• ASCMDSERVER="http://myserver/my_virtual_dir/msmdpump.dll"
• ASCMDINSTANCE=""
• ASCMDHTTPCONNECTION="true"

Dans l'exemple suivant, ces mêmes variables de script réservées du système sont renseignées avec des valeurs différentes par le biais d'une instruction SET différente :

• C:\>SET ASCMDSERVER=myserver\myinstance

L'instruction SET précédente spécifiant une valeur pour la variable d'environnement ASCMDSERVER définit les valeurs pour les trois variables de script réservées du système suivantes :

• ASCMDSERVER="myserver"
• ASCMDINSTANCE="myinstance"
• ASCMDHTTPCONNECTION="false"

Utilisation de variables de script réservées du système à l'invite de commandes

S'il existe une variable d'environnement correspondant à une variable de script réservée du système (la correspondance ne tient pas compte de la casse), la valeur de la variable d'environnement est adoptée comme valeur par défaut pour la variable de script réservée du système et pour le paramètre de ligne de commande associé. Par exemple, vous pouvez utiliser l'instruction SET suivante, exécutée pour définir la variable d'environnement ASCMDDBNAME :

• C:\>SET ASCMDDBNAME="Adventure Works DW"

Dans ce cas, « Adventure Works DW » sera la base de données par défaut (paramètre –d) lorsque vous exécuterez l'utilitaire de ligne de commande ascmd (sauf si vous spécifiez une valeur différente sur la ligne de commande).

Utilisation de variables de script réservées du système dans des scripts, des requêtes ou des instructions

Les variables de script définies par le système peuvent également être utilisées dans un script XMLA, une requête MDX ou une instruction DMX. Les exemples suivants illustrent des invocations de ligne de commande de l'utilitaire de ligne de commande ascmd qui utilisent des variables de script. De plus amples exemples illustrant les scénarios d'utilisation sont fournis plus loin dans ce document.

• C:\>ascmd -S <nom du serveur> -i process.xmla -v cube=<CubeID>

process.xmla (simplifié)

<Batch>
    <Parallel>
         <Process>
             <Object>
                  <DatabaseID>$(ASCMDDBNAME)</DatabaseID>
                  <CubeID>($CUBE)</CubeID>
            . . .
         </Process>
    </Parallel>
</Batch>

Variables de script définies par l'utilisateur

Une variable de script définie par l'utilisateur est une variable de script définie à l'aide du paramètre –v sur la ligne de commande, ou définie comme variable d'environnement. Lorsque l'utilitaire de ligne de commande ascmd rencontre une variable dans un script XMLA, une requête MDX ou une instruction DMX, et que la variable n'a pas été renseignée à l'aide du paramètre –v, l'utilitaire recherche une variable d'environnement portant le même nom et utilise la valeur de cette variable. Si l'utilitaire de ligne de commande ascmd ne détecte aucune variable d'environnement correspondante, la variable de script est supprimée et remplacée par une chaîne vide ("").

Les règles suivantes s'appliquent aux variables de script définies par l'utilisateur à l'aide du paramètre –v sur la ligne de commande :

• Les espaces de début et de fin sont supprimés de la section « value » d'une variable.
• La variable ne peut pas commencer par la chaîne « ascmd ».

Utilisation de requêtes MDX, de scripts XMLA et d'instructions DMX dans les fichiers d'entrée

L'utilitaire de ligne de commande ascmd prend en charge l'exécution de requêtes MDX, de scripts XMLA et d'instructions DMX dans les fichiers d'entrée. Le script d'entrée transmis à l'utilitaire de ligne de commande ascmd est un élément de commande XMLA.

Les éléments de commande sont les suivants :

• Alter
• Backup
• Batch
• BeginTransaction
• Cancel
• ClearCache
• CommitTransaction
• Create
• Delete
• DesignAggregations
• Drop
• Insert
• Lock
• MergePartitions
• NotifyTableChange
• Process
• Restore
• RollbackTransaction
• Statement (utilisé pour l'exécution de requêtes MDX et d'instructions DMX)
• Subscribe
• Synchronize
• Unlock
• Update
• UpdateCells

Pour exécuter des commandes sur plusieurs objets à la fois, utilisez la commande <Batch>. Pour exécuter des requêtes MDX et des instructions DMX, utilisez la commande <Statement>. Pour plus d'informations, consultez Command Element (XMLA) dans la documentation en ligne de SQL Server 2005. Les exemples suivants montrent comment structurer les requêtes MDX, les instructions DMX et les scripts XMLA.

Important :
Comme dans toutes les structures XML, les commandes tiennent compte de la casse. Ainsi, par exemple, vous devez faire figurer toutes les requêtes MDX entre des balises <Statement> …. </Statement> et la commande doit être « Statement », et non pas « statement » ou « STATEMENT ».

Outre les commandes XMLA, l'utilitaire de ligne de commande ascmd peut également servir à l'exécution de requêtes XMLA personnalisées dans le but d'exécuter pratiquement toutes les requêtes exprimées au format XMLA. Par exemple, vous pouvez faire appel à l'utilitaire de ligne de commande ascmd pour émettre l'une des requêtes XMLA suivantes :

• Requêtes XMLA de découverte en vue d'interroger des métadonnées Analysis Services. Ces métadonnées fournissent des informations sur les éléments suivants  :
  • Objets stockés dans la base de données Analysis Services, notamment les cubes définis sur le serveur.
  • Ressources employées, telles que les connexions ouvertes sur le serveur.
• Requêtes d'exécution chargées d'appliquer des commandes mais qui modifient ces dernières en spécifiant une liste de propriétés et une liste de paramètres. Un exemple de ce type de requête est fourni plus loin dans ce document. Voir Exemple d'exécution.

Si le texte d'entrée n'est pas mis en forme en tant que commande XMLA, requête de découverte ou requête d'exécution, l'utilitaire de ligne de commande ascmd considère alors que le texte en question est une requête MDX ou une instruction DMX. Dans ce cas, l'utilitaire de ligne de commande ascmd code le texte au format HTML et l'insère entre des éléments <Statement> … </Statement> avant de le traiter en tant que commande XMLA. Cette opération vous permer d'entrer facilement une requête MDX ou une instruction DMX. Consultez le scénario 1 (Interrogation d'un cube Analysis Services) plus loin dans ce document pour obtenir un exemple sur l'utilisation de cette fonctionnalité.

Exemple MDX :

<Statement>
SELECT NON EMPTY
         [Employees].Members ON ROWS,
         [Measures].[Internet Gross Profit] ON COLUMNS 
FROM [Adventure Works]
</Statement>

Cet exemple utilise une requête MDX au sein d'une instruction XMLA pour retourner la mesure Internet Gross Profit (Marge brute Internet) de chaque membre de la hiérarchie d'attribut Employees qui n'apparaît pas vide dans le cube Adventure Works.

Exemple DMX :

<Statement>
ALTER MINING STRUCTURE [Bike Buyer]
ADD MINING MODEL [Decision Tree]
(
    [Customer Key],
    [Age],
    [Bike Buyer] PREDICT,
    [Commute Distance],
    [Education],
    [Gender],
    [House Owner Flag],
    [Marital Status],
    [Number Cars Owned],
    [Number Children At Home],
    [Occupation],
    [Region],
    [Total Children],
    [Yearly Income]
) USING Microsoft_Decision_Trees
WITH DRILLTHROUGH
</Statement>

Cet exemple utilise une requête DMX dans une instruction XMLA pour modifier la structure d'exploration [Bike Buyer] en ajoutant un nouveau modèle d'exploration.

Exemple XMLA :

<Batch xmlns="https://schemas.microsoft.com/analysisservices/2003/engine">
   <Parallel>
      <Process xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Object>
            <DatabaseID>Adventure Works DW</DatabaseID>
            <CubeID>Adventure Works DW</CubeID>
            <MeasureGroupID>Fact Internet Sales 1</MeasureGroupID>
            <PartitionID>Internet_Sales_2001</PartitionID>
         </Object>
         <Type>ProcessFull</Type>
         <WriteBackTableCreation>UseExisting</WriteBackTableCreation>
      </Process>
   </Parallel>
</Batch>

Cet exemple utilise une instruction XMLA pour traiter en entier la partition Internet_Sales_2001.

Exemple de découverte :

<Discover xmlns="urn:schemas-microsoft-com:xml-analysis">
   <RequestType>MDSCHEMA_CUBES</RequestType>
   <Restrictions>
      <RestrictionList>
         <CATALOG_NAME>Adventure Works DW</CATALOG_NAME>
      </RestrictionList>
   </Restrictions>
   <Properties>
      <PropertyList>
         <Catalog>Adventure Works DW</Catalog>
         <Format>Tabular</Format>
      </PropertyList>
   </Properties>
</Discover>

Cet exemple utilise une requête de découverte XMLA pour retourner les cubes disponibles dans la base de données Adventure Works DW. Les perspectives sont retournées aux applications comme si elles étaient des cubes , de ce fait, les données retournées incluent à la fois les cubes et les perspectives.

Exemple d'exécution :

<Execute xmlns="urn:schemas-microsoft-com:xml-analysis">
   <Command>
      <Statement>
         SELECT [Measures].MEMBERS ON COLUMNS FROM [Adventure Works]
      </Statement>
   </Command>
   <Properties>
      <PropertyList>
         <Catalog>Adventure Works DW</Catalog>
         <Format>Tabular</Format>
         <AxisFormat>ClusterFormat</AxisFormat>
      </PropertyList>
   </Properties>
</Execute>

Cet exemple utilise une requête MDX dans une instruction XMLA. Notez en revanche que la section de liste des propriétés de la requête XMLA précise que le format de retour est Tabulaire et non Multidimensionnel. Le format multidimensionnel est le format adopté par défaut pour une commande d'instruction XMLA. Du fait que le format de retour est de type tabulaire (ensemble de lignes), le fichier de sortie peut être utilisé par une application qui maîtrise mieux les ensembles de lignes à plat xsd que les ensembles de cellules et l'ensemble de lignes à plat peut être plus facilement chargé dans une base de données relationnelle SQL puisqu'il apparaît désormais sous la forme d'une table.

Exemples de scénarios ASCMD

Les scénarios suivants proposent des exemples d'utilisation de l'utilitaire de ligne de commande ascmd.

Scénario 1 : Interrogation d'un cube Analysis Services

Dans ce scénario, vous créez un fichier d'entrée contenant une requête MDX (le fichier query.mdx). Cette dernière comporte une variable de script définie par l'utilisateur (cube). Vous appelez ensuite ce fichier d'entrée à partir de l'utilitaire de ligne de commande ascmd, puis vous spécifiez une valeur pour cette variable sur la ligne de commande à l'aide du paramètre –v.

fichier query.mdx :

Format 1 :

<Statement>
/* THIS IS AN MDX COMMENT */
SELECT [Measures].[Internet Sales Amount] ON COLUMNS
FROM $(cube)
WHERE [Customer].[Country].&amp;[United States]
</Statement>

Format 2 :

/* THIS IS AN MDX COMMENT */
SELECT [Measures].[Internet Sales Amount] ON COLUMNS
FROM $(cube)
WHERE [Customer].[Country].&[United States]

Exemple de ligne de commande :

C:\>ascmd -S myserver -d "Adventure Works DW" -i query.mdx -o result.xml -v cube="[Adventure Works]"

Dans le format 1, notez que la clé de l'élément United States est traitée en remplaçant le caractère « & » de la requête MDX (caractère indiquant qu'il s'agit de la clé de membre et non du nom) par &amp; (tel que requis dans le cadre du codage HTML) et que l'élément <Statement> est précisé. Avec le format 2, ni le codage HTML, ni l'élément <Statement> ne sont nécessaires. La raison est liée au fait que le texte d'entrée ne commence pas avec une commande XMLA valide et que l'utilitaire de ligne de commande ascmd considère alors que le texte d'entrée est une instruction et code automatiquement au format HTML l'entrée et l'insère entre des éléments <Statement> avant exécution.

Scénario 2 : Sauvegarde d'une base de données dans un domaine non approuvé

Dans ce scénario, vous sauvegardez une base de données sur un serveur qui se trouve dans un domaine non approuvé à l'aide de l'utilitaire de ligne de commande ascmd. Du fait que la base de données se trouve dans un domaine non approuvé, ce scénario exige une connexion HTTP. Dans ce scénario, IIS (Internet Information Services) et Analysis Services sont tous les deux en cours d'exécution sur le serveur distant (« myserver ») ; ce serveur dispose d'un répertoire virtuel ISS nommé « olapadmin », configuré avec l'authentification de base. En outre, le serveur distant dispose d'un compte local nommé « olapadmin » avec les autorisations de sauvegarde appropriées. Spécifiez le nom de la base de données, la méthode d'accès, le nom d'utilisateur, le mot de passe et le fichier de sauvegarde sur la ligne de commande à l'aide des paramètres de ligne de commande ascmd, puis spécifiez un fichier d'entrée XMLA (backup.xmla) contenant les variables de script pour la base de données et le fichier de sauvegarde.

fichier backup.xmla :

<Backup xmlns="https://schemas.microsoft.com/analysisservices/2003/engine">
   <Object>
      <DatabaseID>$(ascmddbname)</DatabaseID>
   </Object>
   <File>$(backupfile).abf</File>
</Backup>

Exemple de ligne de commande :

C:\>ascmd -S https://myserver/msolap90/msmdpump.dll -U myserver\olapadmin -P #1PWD -d "Adventure Works DW" -i backup.xmla -v backupfile="AdvWorks"

Notez l'utilisation du schéma HTTPS dans l'exemple de ligne de commande. Il permet de chiffrer le mot de passe au moment de son envoi au serveur distant sur le réseau.

Scénario 3 : Traitement de plusieurs partitions

Dans ce scénario, vous traitez plusieurs partitions à l'aide de l'utilitaire de ligne de commande ascmd. Les variables de script utilisées dans le script de traitement XMLA (process.xmla) permettent de spécifier le degré de parallélisme, les noms de base de données et de cube et le type de traitement. Ce script XMLA montre également comment utiliser des commentaires dans un script XMLA. Lorsque vous appelez le script de traitement process.xmla à partir de l'utilitaire de ligne de commande ascmd, vous spécifiez les noms de serveur et de base de données, un fichier de sortie pour les résultats XMLA, un fichier de trace pour les événements de trace, le niveau de trace et le degré de parallélisme avec un fichier de commandes (process.bat). Le fichier de trace peut contenir les mêmes événements et informations que ceux que renverrait Générateur de profils SQL Server si un administrateur contrôlait le système au cours du traitement.

fichier process.xmla :

<Batch xmlns="https://schemas.microsoft.com/analysisservices/2003/engine">
   <Parallel maxparallel="$(MAXPARALLEL)">
   <!-- SEE ABOVE FOR HOW MANY PARITIONS PROCESSED IN PARALLEL -->
      <Process xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Object>
            <DatabaseID>$(ASCMDDBNAME)</DatabaseID>
            <CubeID>$(ASCMDDBNAME)</CubeID>
            <!-- Just so happens CubeID=DatabaseID=Database name :-) -->
            <MeasureGroupID>Fact Internet Sales 1</MeasureGroupID>
            <PartitionID>Internet_Sales_2001</PartitionID>
         </Object>
         <Type>$(PROCESSTYPE)</Type>
         <WriteBackTableCreation>UseExisting</WriteBackTableCreation>
      </Process>
      <Process xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Object>
            <DatabaseID>$(ASCMDDBNAME)</DatabaseID>
            <CubeID>$(ASCMDDBNAME)</CubeID>
            <MeasureGroupID>Fact Internet Sales 1</MeasureGroupID>
            <PartitionID>Internet_Sales_2002</PartitionID>
         </Object>
         <Type>$(PROCESSTYPE)</Type>
         <WriteBackTableCreation>UseExisting</WriteBackTableCreation>
      </Process>
      <Process xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Object>
            <DatabaseID>$(ASCMDDBNAME)</DatabaseID>
            <CubeID>$(ASCMDDBNAME)</CubeID>
            <MeasureGroupID>Fact Internet Sales 1</MeasureGroupID>
            <PartitionID>Internet_Sales_2004</PartitionID>
         </Object>
         <Type>$(PROCESSTYPE)</Type>
         <WriteBackTableCreation>UseExisting</WriteBackTableCreation>
      </Process>
      <Process xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
         <Object>
            <DatabaseID>$(ASCMDDBNAME)</DatabaseID>
            <CubeID>$(ASCMDDBNAME)</CubeID>
            <MeasureGroupID>Fact Internet Sales 1</MeasureGroupID>
            <PartitionID>Internet_Sales_2003</PartitionID>
         </Object>
         <Type>$(PROCESSTYPE)</Type>
         <WriteBackTableCreation>UseExisting</WriteBackTableCreation>
      </Process>
   </Parallel>
</Batch>

fichier process.bat :

@echo off
call :generate-timestamp
ascmd -S myserver -d "Adventure Works DW" -i process.xmla
         -o process.xml -T process-%timestamp%.csv -Tl medium 
         -v maxparallel=4 processtype=ProcessFull
if ERRORLEVEL 1 goto errseen
goto :EOF
:errseen
echo ** Error seen in processing
goto :EOF

:generate-timestamp
set now_date=%date%
set now_time=%time%
set now_Year=%now_date:~10,4%
set now_Month=%now_date:~4,2%
set now_Day=%now_date:~7,2%
set now_Hour=%now_time:~0,2%
set now_Min=%now_time:~3,2%
if "%now_Hour:~0,1%"==" " set now_Hour=0%now_Hour:~1,1%
set timestamp=%now_year%%now_month%%now_day%_%now_hour%%now_min%
goto :EOF

Notez que le fichier de traitement par lots utilise un horodateur dans le fichier de sortie. Cela permet l'enregistrement simultané de plusieurs exécutions.

Scénario 4 : Création d'une nouvelle base de données sur un serveur

Dans ce scénario, vous utilisez l'utilitaire de ligne de commande ascmd pour appeler un fichier de script XMLA afin de créer une nouvelle base de données sur un serveur. Le nom de la base de données est défini dans le script XMLA en utilisant une variable de script définie par l'utilisateur, et la valeur de cette variable est définie sur la ligne de commande à l'aide du paramètre –v.

fichier create.xmla :

Le fichier a été créé dans SQL Server Management Studio. Pour créer votre propre fichier, cliquez avec le bouton droit sur la base de données, puis cliquez sur Créer dans le menu Script.

<Create xmlns="https://schemas.microsoft.com/analysisservices/2003/engine">
      <ObjectDefinition>
            <Database xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
                  <ID>$(dbname)</ID>
                  <Name>$(dbname)</Name>
                  <Description>A Unified Dimensional Model that encompasses the Adventure Works data warehouse.</Description>
                  <Language>1033</Language>
                  <Collation>Latin1_General_CI_AS</Collation>
                  <DataSourceImpersonationInfo>
                     <ImpersonationMode>Default</ImpersonationMode>
                  </DataSourceImpersonationInfo>
                  <Dimensions>
                        <Dimension>
                              <ID>Dim Promotion</ID>
                              <Name>Promotion</Name>
                              <Annotations>
 . . .

Exemple de ligne de commande :

C:\>ascmd -S myserver -i create.xmla -v dbname="My Adventure Works DW"

Dans le script XMLA précédent, vous pouvez également utiliser des variables de script pour configurer des objets tels que la chaîne de connexion à une source de données, les noms de serveur et de base de données utilisés dans la source de données ou les noms de champ dans la vue de la source de données.

Scénario 5 : Création d'une application Cache Warmer

Dans ce scénario, vous utilisez un fichier de commandes (cache_warmer.bat) pour lancer l'utilitaire de ligne de commande ascmd et appeler plusieurs requêtes MDX qui mettent en route le cache de données Analysis Services. Par exemple, vous pouvez appeler ce fichier de commandes quotidiennement à 14:00 ou après le chargement par lot nocturne à l'aide de l'Agent SQL Server. Dans le fichier de traitement par lots, définissez les variables d'environnement pour les noms de serveur, de base de données et de cube. Étant donné que les noms de serveur et de base de données spécifiés comme variables d'environnement correspondent exactement aux noms des variables de script réservées du système, ils font office de valeurs par défaut pour les paramètres de ligne de commande –S et –d. La variable de script définie par l'utilisateur pour le nom du cube est utilisée dans toutes les requêtes MDX.

fichier query1.mdx :

Fichiers : query1.mdx à query6.mdx au format query1.txt

<Statement>
SELECT [Measures].[Internet Sales Amount] ON COLUMNS
FROM $(cube)
WHERE [Customer].[Country].&amp;[United States]
</Statement>

Créez d'autres fichiers en remplaçant [United States] par d'autres pays figurant dans la base de données Adventure Works : [Australia], [Canada], [France], [Germany] ou [United Kingdom].

fichier cache_warmer.bat :

set ascmdserver=myserver
set ascmddbname=Adventure Works DW
set cube=[Adventure Works]

set QUERYDIR=..\queries
set OUTPUTDIR=..\queries
echo -------------------------
set f=
for %%f in (%QUERYDIR%\*.mdx) do (
    call :query %%f
            if ERRORLEVEL 1 goto :EOF
)
echo -------------------------
echo Done.
goto :EOF

:query
echo Query: %1
echo ---------
ascmd -T %OUTPUTDIR%\querylog.txt -Tl duration 
         -Tf text -o %OUTPUTDIR%\%~n1.xml -i %1
echo Errorlevel: %ERRORLEVEL%
echo -------------------------
if ERRORLEVEL 1 goto :errseen
goto :EOF

:errseen
echo -------------------------
echo   ******
echo   ****** ERROR SEEN ******
echo   ******   Exiting    ******
goto :EOF

Scénario 6 : Création d'une procédure de validation

Dans ce scénario, vous vous servez de l'utilitaire de ligne de commande ascmd pour appeler plusieurs fichiers de requêtes MDX (comme dans le scénario précédent) une fois l'exécution de nuit d'un processus ETL terminée. Le paramètre de durée –Tl permet d'enregistrer la durée de chaque requête MDX dans un fichier de trace tout en dirigeant la sortie du script MDX vers un fichier NULL (-oNUL). Vous pouvez également utiliser le paramètre de durée -Tl pour enregistrer les résultats d'exécution dans le journal des traces. Le recours à l'utilitaire de ligne de commande ascmd vous permet de suivre le temps nécessaire à chaque requête MDX et de comparer ces résultats quotidiennement afin de vérifier que des valeurs figurant dans la même plage sont retournées. Si les résultats de durée d'un jour précis apparaissent trop démesurés, cela signifie peut-être que les résultats de l'exécution du processus ETL doivent être supprimés.

Exemple de ligne de commande :

C:\>ascmd -i %queryfile% -o NUL -T querylog.csv -Tl duration

Scénario 7 : Automatisation de la création et de la formation d'un modèle d'exploration de données

Dans ce scénario, vous appelez une série d'instructions DMX à l'aide de l'utilitaire de ligne commande ascmd. Ces instructions DMX sont les suivantes :

• une instruction DMX qui crée une structure d'exploration (Bike Buyer Structure.DMX) et utilise des variables d'environnement pour définir les noms de serveur et de base de données ;
• une instruction DMX (Clustering_Model.dmx) qui ajoute un modèle d'exploration de données en clusters à la structure ;
• une instruction DMX (DT_Model.dmx) qui ajoute un modèle d'exploration de données d'arbre de décision à la structure ;
• une instruction DMX (Process Bike Buyer Structure.dmx) chargée de traiter la structure et les modèles d'exploration.

Une fois la structure d'exploration en place, vous pouvez recourir à l'utilitaire de ligne de commande ascmd pour appeler plusieurs instructions DMX capables d'interroger la structure d'exploration par le biais de différents modèles d'exploration.

Création de la structure d'exploration

fichier Bike Buyer Structure.dmx :

<Statement>
CREATE MINING STRUCTURE [Bike Buyer]
(
    [Customer Key] LONG KEY,
    [Age]LONG DISCRETIZED(Automatic,10),
    [Bike Buyer] LONG DISCRETE,
    [Commute Distance] TEXT DISCRETE,
    [Education] TEXT DISCRETE,
    [Gender] TEXT DISCRETE,
    [House Owner Flag] TEXT DISCRETE,
    [Marital Status] TEXT DISCRETE,
    [Number Cars Owned]LONG DISCRETE,
    [Number Children At Home]LONG DISCRETE,
    [Occupation] TEXT DISCRETE,
    [Region] TEXT DISCRETE,
    [Total Children]LONG DISCRETE,
    [Yearly Income] DOUBLE CONTINUOUS
)
</Statement>

Exemple de ligne de commande :

C:\>set ascmdserver=myserver

C:\>set ascmddbname=Adventure Works DW

C:\>ascmd -i "Bike Buyer Structure.dmx"

Ajout d'un modèle d'exploration de données en clusters à une structure

fichier Clustering_Model.dmx :

<Statement>
ALTER MINING STRUCTURE [Bike Buyer]
ADD MINING MODEL [Clustering]
USING Microsoft_Clustering 
</Statement>

Exemple de ligne de commande :

C:\>ascmd -i "Clustering_Model.dmx"

Ajout d'un modèle d'exploration de données d'arbre de décision à la structure

fichier DT_Model.dmx

<Statement>
ALTER MINING STRUCTURE [Bike Buyer]
ADD MINING MODEL [Decision Tree]
(
    [Customer Key],
    [Age],
    [Bike Buyer] PREDICT,
    [Commute Distance],
    [Education],
    [Gender],
    [House Owner Flag],
    [Marital Status],
    [Number Cars Owned],
    [Number Children At Home],
    [Occupation],
    [Region],
    [Total Children],
    [Yearly Income]
) USING Microsoft_Decision_Trees
WITH DRILLTHROUGH
</Statement>

Exemple de ligne de commande :

C:\>ascmd -i "DT_Model.dmx"

Traitement de la structure et des modèles d'exploration

fichier Process Bike Buyer Structure.dmx :

<Statement>
INSERT INTO MINING STRUCTURE [Bike Buyer]
(
    [Customer Key],
    [Age],
    [Bike Buyer],
    [Commute Distance],
    [Education],
    [Gender],
    [House Owner Flag],
    [Marital Status],
    [Number Cars Owned],
    [Number Children At Home],
    [Occupation],
    [Region],
    [Total Children],
    [Yearly Income]
)
OPENQUERY([$(ASCMDDBNAME)],
    'SELECT CustomerKey, Age, BikeBuyer,
             CommuteDistance,EnglishEducation,
             Gender,HouseOwnerFlag,MaritalStatus,
             NumberCarsOwned,NumberChildrenAtHome, 
             EnglishOccupation,Region,TotalChildren,
             YearlyIncome 
      FROM dbo.vTargetMail')
</Statement>

Exemple de ligne de commande :

C:\>ascmd -i "DT_Model.dmx"

Interrogation de la structure à l'aide du modèle d'exploration de données d'arbre

fichier SELECT_DRILLTHROUGH.dmx :

<Statement>
SELECT * 
FROM [Decision Tree].CASES
</Statement>

fichier BATCH_PREDICTION.dmx :

<Statement>
SELECT
   TOP 10
   t.[LastName],
   t.[FirstName],
   [Decision Tree].[Bike Buyer],
   PredictProbability([Bike Buyer])
From
   [Decision Tree]
PREDICTION JOIN
 OPENQUERY([$(ASCMDDBNAME)],
      'SELECT
         [LastName],
         [FirstName],
         [MaritalStatus],
         [Gender],
         [YearlyIncome],
         [TotalChildren],
         [NumberChildrenAtHome],
         [Education],
         [Occupation],
         [HouseOwnerFlag],
         [NumberCarsOwned]
      FROM
         [dbo].[ProspectiveBuyer]
      ') AS t
ON
   [Decision Tree].[Marital Status] = t.[MaritalStatus] AND
   [Decision Tree].[Gender] = t.[Gender] AND
   [Decision Tree].[Yearly Income] = t.[YearlyIncome] AND
   [Decision Tree].[Total Children] = t.[TotalChildren] AND
   [Decision Tree].[Number Children At Home] = t.[NumberChildrenAtHome] AND
   [Decision Tree].[Education] = t.[Education] AND
   [Decision Tree].[Occupation] = t.[Occupation] AND
   [Decision Tree].[House Owner Flag] = t.[HouseOwnerFlag] AND
   [Decision Tree].[Number Cars Owned] = t.[NumberCarsOwned]
WHERE [Decision Tree].[Bike Buyer] =1
ORDER BY PredictProbability([Bike Buyer]) DESC
</Statement>

fichier SELECT_DISCRETE.dmx :

<Statement>
SELECT DISTINCT [Bike Buyer] 
FROM [Decision Tree]
</Statement>

Exemple de ligne de commande :

C:\>ascmd -i SELECT_DRILLTHROUGH.dmx

C:\>ascmd -i BATCH_PERDICTION.dmx

C:\>ascmd -i SELECT_DISCRETE.dmx

Scénario 8 : Effacement du cache de données Analysis Services

Dans ce scénario, vous utilisez l'utilitaire de ligne de commande ascmd pour appeler un script XMLA (ClearCache.xmla) qui efface le cache de données Analysis Services entre chaque exécution lors de l'analyse des performances. Le fichier ClearCache.xmla contient des variables de script pour les noms de base de données et de cube. Ce script XMLA est appelé par un fichier de traitement par lots (ClearCache.bat) qui indique les noms de serveur, d'instance, de base de données, de fichier d'entrée, de fichier de sortie et de cube.

fichier ClearCache.xmla :

<Batch xmlns="https://schemas.microsoft.com/analysisservices/2003/engine">
   <ClearCache>
               <Object>
                      <DatabaseID>$(ASCMDDBNAME)</DatabaseID>
                      <CubeID>$(CUBE)</CubeID>
               </Object>
       </ClearCache>
</Batch> 

fichier ClearCache.bat :

@echo off
ascmd -S myserver\myinstance -d "Adventure Works DW" -i ClearCache.xmla
         -o ClearCache.xml -v cube="Adventure Works DW"

if ERRORLEVEL 1 goto :errseen
goto :EOF

:errseen
echo **** Error seen ****
echo ********************
goto :EOF

Scénario 9 : Identification de la personne actuellement connectée à votre serveur

Dans ce scénario, vous procédez à l'extraction d'une liste de connexions actives sur le serveur par le biais de l'utilitaire de la ligne de commande ascmd. Une application peut exploiter ces informations pour retarder le traitement jusqu'à ce que des utilisateurs précis soient déconnectés ou pour envoyer un message électronique aux opérateurs si quelqu'un dispose d'une connexion en cours (autre que la connexion de l'exécution par lot nocturne).

Fichier connections.xmla :

<Discover xmlns="urn:schemas-microsoft-com:xml-analysis">
   <RequestType>DISCOVER_CONNECTIONS</RequestType>
   <Restrictions />
   <Properties>
      <PropertyList>
         <Content>Data</Content>     <!-- Only the data; no schema -->
      </PropertyList>
   </Properties>
</Discover>

Exemple de ligne de commande :

C:\>ascmd -S myserver -i connections.xmla -o current_connections.xml

Scénario 10 : Une partition a-t-elle été traitée et si oui, quand a-t-elle été traitée la dernière fois ?

Dans ce scénario, vous vous servez de l'utilitaire de la ligne de commande ascmd pour déterminer si une partition a été traitée et à quel moment elle l'a été. Ces informations sont faciles à extraire puisqu'elles sont stockées sous la forme d'une propriété dans l'objet partition. Vous pouvez donc utiliser une demande DISCOVER_XML_METADATA pour les extraire.

fichier connections.xmla :

<Discover xmlns="urn:schemas-microsoft-com:xml-analysis">
   <RequestType>DISCOVER_XML_METADATA</RequestType>
   <Restrictions>
      <RestrictionList>
        <DatabaseID>$(DatabaseID)</DatabaseID>
        <CubeID>$(CubeID)</CubeID>
        <MeasureGroupID>$(MeasureGroupID)</MeasureGroupID>
        <PartitionID>$(PartitionID)</PartitionID>
      <!-- Ask for just this object referenced -->
      <ObjectExpansion>ReferenceOnly</ObjectExpansion>
      </RestrictionList>
   </Restrictions>
   <Properties>
      <PropertyList>
         <Content>Data</Content>     <!-- Only the data; no schema -->
      </PropertyList>
   </Properties>
</Discover>

Scénario 11 : utilisation de la commande GO pour effectuer une opération d'écriture différée

Dans ce scénario, vous scindez en deux portions l'opération d'écriture différée à l'aide de l'utilitaire de ligne de commande ascmd : modifiez les données et validez-les. L'opération d'écriture différée nécessite l'utilisation de la commande GO du fait que les deux instructions MDX nécessaires pour une opération d'écriture différée (les instructions Update Cube et Commit Transaction) doivent être émises l'une après l'autre au sein de la même transaction. MDX ne prend pas en charge leur émission au sein du même lot.

Pour ce scénario, vous devez modifier la base de données Adventure Works DW pour prendre en charge l'écriture différée. La base de données existante ne contient pas actuellement un exemple d'un cube prenant en charge l'écriture différée. Pour créer et vérifier un cube qui prend en charge l'écriture différée, procédez comme suit :

1. Pour définir un nouveau cube appelé « Writeback »

2. Ouvrez Business Intelligence Development Studio.

3. Dans le menu Fichier, pointez sur Ouvrir, puis cliquez sur Base de données Analysis Services.

4. Dans la boîte de dialogue Se connecter à la base de données, tapez votre nom de serveur dans la zone de texte Serveur, sélectionnez la base de données Adventure Works DW dans la liste Base de données, puis cliquez sur OK.

5. Dans le volet Explorateur de solutions, cliquez avec le bouton droit sur Cubes et choisissez Nouveau cube.

6. Dans l'Assistant Cube, cliquez sur Suivant dans la page Assistant Cube, sélectionnez Construire le cube en utilisant une source de données, désactivez la case à cocher Génération automatique, puis cliquez sur Suivant.

7. Sélectionnez Adventure Works DW dans la liste Vues de sources de données disponibles dans la page Sélectionner une vue de source de données et cliquez sur Suivant.

8. Sur la page Identifier les tables de faits et de dimension, activez la case à cocher Fait pour la table FactSalesQuota et la case à cocher Dimensionpour les tables dbo.DimTime et dbo.DimEmployee, puis cliquez sur Suivant.

9. dbo.DimTime (dimension s'appelle Date)dbo.DimEmployeeFactSalesQuota (utilise seulement la mesure « Sales Amount Quota »)

10. Sur la page Vérifier les dimensions partagées, sélectionnez Date et Employé dans la liste Dimensions disponibles, cliquez sur > pour ajouter ces dimensions à la liste Dimensions de cube, puis cliquez sur Suivant.

11. Sur la page Sélectionnez les mesures, désactivez la case à cocher Fact Sales Quota, activez la case à cocher Sales Amount Quota, puis cliquez sur Suivant.

12. Dans la page Fin de l'Assistant, remplacez le nom du cube par Writeback, puis cliquez sur Terminer.

13. Pour activer l'écriture différée pour le groupe de mesures Fact Sales Quota

14. Dans le Concepteur de cube, sélectionnez l'onglet Partitions.

15. Cliquez avec le bouton droit sur la partition Fact Sales Quota dans la liste de partitions et cliquez sur Paramètres d'écriture différée.

16. Dans la boîte de dialogue Activer l'écriture différée - Fact Sales Quota, vérifiez le nom de la table d'écriture différée par défaut puis cliquez sur OK pour créer cette table et activer l'écriture différée pour cette partition.

17. Vous remarquerez que deux partitions s'affichent désormais : l'une pour la table de faits ; l'autre pour la table d'écriture différée.

18. Pour traiter le cube d'écriture différée

19. Dans l'Explorateur de solutions, cliquez avec le bouton droit sur Écriture différée dans le nœud Cubes, puis cliquez sur Traiter.

20. Cliquez sur Oui si le système vous demande d'enregistrer les modifications.

21. Dans la boîte de dialogue Traiter le cube - Écriture différée, cliquez sur Exécuter.

22. Si vous développez les commandes de traitement, vous verrez l'instruction CREATE TABLE SQL utilisée pour créer la table relationnelle d'écriture différée.

23. Au terme du traitement, vérifiez dans la zone Statut que le traitement a réussi, puis cliquez sur Fermer.

24. Cliquez sur Fermer de nouveau pour fermer la boîte de dialogue Traiter la partition - WriteTable_Fact Sales Quota.

25. Fermez Business Intelligence Development Studio.

26. Pour vérifier que l'écriture différée fonctionne

27. Ouvrez SQL Server Management Studio.

28. Connectez-vous à votre serveur, puis dans l'Explorateur d'objets, développez Bases de données, cliquez avec le bouton droit sur Adventure Works DW, pointez sur Nouvelle requête et cliquez sur MDX.

29. Dans la fenêtre de requête MDX, exécutez la requête MDX suivante pour retourner le devis des ventes courantes pour le premier trimestre 2002 (Q1FY2002) et Stephen Y. Jiang :

    /* Employee 272 is [Stephen Y. Jiang]*/
    SELECT [Measures].[Sales Amount Quota] ON COLUMNS
    FROM [Writeback]
    WHERE ([Employee].[Employee].[Stephen Y. Jiang],[Date].[Calendar].[Calendar Quarter].[Q1 CY 2002])
    

30. Modifiez la cellule pour retourner $2,200 en émettant l'instruction MDX suivante :

    UPDATE CUBE [Writeback]
    SET ([Employee].[Employee].[Stephen Y. Jiang],
    [Date].[Calendar].[Calendar Quarter].[Q1 CY 2002]) = 2200
    

31. Validez la transaction en exécutant l'instruction MDX suivante :

    COMMIT TRANSACTION
    

    À ce stade, vous pouvez examiner la table « dbo.WriteTable_Fact Sales Quota » dans la base de données relationnelle Adventure Works DW pour vérifier quelle l'écriture différée a eu lieu pour la cellule. Si vous le faites, vous remarquerez que c'est le delta (-88800) qui est écrit dans la table relationnelle. La table de faits d'origine reste inchangée.

fichier writeback.mdx :

/* What is the existing value? */
SELECT [Measures].[Sales Amount Quota] ON COLUMNS
FROM [Writeback]
WHERE ([Employee].[Employee].&[272],
[Date].[Calendar].[Calendar Quarter].&[2002]&[1])
GO
/* Update the cube with a new value */
UPDATE CUBE [Writeback]
SET ([Employee].[Employee].&[272],
[Date].[Calendar].[Calendar Quarter].&[2002]&[1]) = 33000 /* some different value */
GO
/* Commit it */
Commit Transaction
GO
/* See what the updated value is */
SELECT [Measures].[Sales Amount Quota] ON COLUMNS
FROM [Writeback]
WHERE ([Employee].[Employee].&[272],
[Date].[Calendar].[Calendar Quarter].&[2002]&[1])
GO

Exemple de ligne de commande :

C:\>ascmd -S myserver -d "Adventure Works DW" -i writeback.mdx -o writeback_result.xml -v cube="[Writeback]"

Writeback_result.xml :

<multiple-batches>
   <return xmlns="urn:schemas-microsoft-com:xml-analysis">
      <root xmlns= . . .>
         <...metadata about the result set...>
<CellData xmlns="urn:schemas-microsoft-com:xml-analysis:mddataset">
  <Cell CellOrdinal="0">
     <Value xsi:type="xsd:double" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">0</Value> 
     <FmtValue>2200</FmtValue> 
  </Cell>
</CellData>
      </root>
   </return>
   <return xmlns="urn:schemas-microsoft-com:xml-analysis">
      <root xmlns="urn:schemas-microsoft-com:xml-analysis:empty" /> 
   </return>
   <return xmlns="urn:schemas-microsoft-com:xml-analysis">
      <root xmlns="urn:schemas-microsoft-com:xml-analysis:empty" /> 
   </return>
   <return xmlns="urn:schemas-microsoft-com:xml-analysis">
      <root xmlns= . . .>
         <...metadata about the result set...>
<CellData xmlns="urn:schemas-microsoft-com:xml-analysis:mddataset">
  <Cell CellOrdinal="0">
     <Value xsi:type="xsd:double" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">0</Value> 
     <FmtValue>33000</FmtValue> 
  </Cell>
</CellData>
      </root>
   </return>
</multiple-batches>

Remarquez qu'il existe deux jeux de résultats vides pour les instructions UPDATE CUBE et COMMIT TRANSACTION.

Voir aussi

Autres ressources

XML for Analysis (XMLA)
XML for Analysis Reference (XMLA)
Discover Method (XMLA)
Execute Method (XMLA)

Aide et Informations

Assistance sur SQL Server 2005