class ntiprogramparameter

Classe NTiProgramParameter

Description

La classe NTiProgramParameter représente un paramètre de prgramme IBM i ou d'API système IBM i. Il peut être d'entrée, sortie ou d'entrée/sortie.

Propriétés

Nom	Type	Valeur par défaut	Description
InputData	byte[]		Données d'entrée du paramètre
OutputData	byte[]		Données de sortie du paramètre
Direction	System.Data.ParameterDirection	InputOutput	Direction du paramètre: InputOutput : Entrée/Sortie Input : Entrée Output / ReturnValue : Sortie

Constructeurs

Nouveau paramètre vide

new()
new(ParameterDirection direction)

Nouveau paramètre de type binaire brut

new(byte[] value)
new(byte[] value, ParameterDirection direction)

Nouveau paramètre de type caractères

Le paramètre length correspond à la longueur attendue par le programme pour ce paramètre. Value sera soit tronqué soit paddée par des blancs (0x40).

new(string value, int length);
new(string value, int length, ParameterDirection direction);
new(string value, int length, int ccsid);
new(string value, int length, int ccsid, ParameterDirection direction);

Nouveau paramètre de type tableau de caractères

Le paramètre length correspond à la longueur finale de chaque valeur.

new(string[] values, int length);
new(string[] values, int length, ParameterDirection direction);
new(string[] values, int length, int ccsid);
new(string[] values, int length, int ccsid, ParameterDirection direction);
new(IEnumerable<string> values, int length);
new(IEnumerable<string> values, int length, ParameterDirection direction);
new(IEnumerable<string> values, int length, int ccsid);
new(IEnumerable<string> values, int length, int ccsid, ParameterDirection direction);

Nouveau paramètre de type entier

Entier 32 bits (4 octets):

new(int value);
new(int value, ParameterDirection direction);

Entier 16 bits (2 octets):

new(short value);
new(short value, ParameterDirection direction);

Nouveau paramètre de type tableau d'entiers

Entiers 32 bits (4 octets):

new(int[] values);
new(int[] values, ParameterDirection direction);
new(IEnumerable<int> values);
new(IEnumerable<int> values, ParameterDirection direction);

Entiers 16 bits (2 octets):

new(short[] values);
new(short[] values, ParameterDirection direction);
new(IEnumerable<short> values);
new(IEnumerable<short> values, ParameterDirection direction);

Nouveau paramètre de type décimal (PACKED(precision, scale))

new(decimal value, int precision, int scale);
new(decimal value, int precision, int scale, ParameterDirection direction);

Méthodes

Append(...)

La méthode Append permet de compléter la valeur des données d'entrée d'un paramètre existant. Cette méthode est utile lorsqu'un paramètre a une structure complexe composée de plusieurs données éventuellement de types différents. Les paramètres et l'utilisation sont analogues aux constructeurs ci-dessus.

Variante	Description
Append(byte[] value)	Ajoute les données value à la suite des données du paramètre sans modification
Append(string value, int length) Append(string value, int length, int ccsid)	Ajoute une chaîne de caractères value de longueur fixe length en utilisant le CCSID du job QZRCSRVS en cours ou en spécifiant le CCSID utilisé pour l'encodage des caractères
Append(string[] values, int length) Append(IEnumerable<string> values, int length) Append(string[] values, int length, int ccsid) Append(IEnumerable<string> values, int length, int ccsid)	Ajoute une chaînes de caractères values, chacune de longueur fixe length en utilisant le CCSID du job QZRCSRVS en cours ou en spécifiant le CCSID utilisé pour l'encodage des caractères
Append(int value)	Ajoute un entier 32 bits value
Append(short value)	Ajoute un entier 16 bits value
Append(int[] value) Append(IEnumerable<int> value)	Ajoute une collection d'entiers 32 bits values
Append(short[] value) Append(IEnumerable<short> value)	Ajoute une collection d'entiers16 bits values
Append(decimal value, int precision, int scale)	Ajoute un nombre décimal value au format PACKED(precision, scale)

La méthode Append() retoure une référence au paramètre et peut ainsi être appelée en chaîne pour construire des structures de données complexes.
Exemple:

//parm ci-dessous est composé ainsi:
//    -CHAR(10) = "QTEMP"
//    -CHAR(10) = "LIBTMP"
//    -BYTE(4)  = 10 (integer)
//    -BYTE(1)  = 0x00

var parm = new NTiProgramParameter("QTEMP", 10).Append("LIBTMP", 10).Append(10).Append(new byte[]{0x00});

string GetString(...)

La méthode GetString permet de récupérer du texte dans les données de sortie d'un paramètre existant. On utilise cette méthode après l'exécution d'un programme pour lire dans les données retournées par le programme.

Variante	Description
GetString() GetString(int ccsid)	Retourne l'intégralité des données de sortie du paramètre sous forme de texte (string) en utilisant le CCSID du job QZRCSRVS en cours ou en spécifiant le CCSID utilisé pour l'encodage des caractères
GetString(int offset, int length) GetString(int offset, int length, int ccsid)	Retourne length caractères à partir de la position offset dans les données de sortie du paramètre sous forme de texte (string) en utilisant le CCSID du job QZRCSRVS en cours ou en spécifiant le CCSID utilisé pour l'encodage des caractères

int GetInt(...)

La méthode GetInt permet de récupérer un nombre entier dans les données de sortie d'un paramètre existant. On utilise cette méthode après l'exécution d'un programme pour lire dans les données retournées par le programme.

Variante	Description
GetInt()	Retourne les 4 premiers octets des données de sortie sous forme d'un entier (int)
GetInt(int offset)	Retourne les 4 octets à partir de la position offset dans les données de sortie sous forme d'un entier (int)

byte[] GetBytes(...)

La méthode GetBytes permet de récupérer les données de sortie d'un paramètre existant sous forme binaire brute. On utilise cette méthode après l'exécution d'un programme pour lire dans les données retournées par le programme.

Variante	Description
GetBytes()	Retourne l'intégralité des données de sorties du paramètre sous forme binaire brute (byte[])
GetBytes(int offset, int length)	Retourne length octets à partir de la position offset dans les données de sorties du paramètre sous forme binaire brute (byte[])

Extensions du type

IList<NTiProgramParameter>.Add(...)

La méthode Add() des éléments de type IList<NTiProgramParameter> est étendue pour reprendre les mêmes fonctionnalités que les constructeurs.

AsOutput(), AsInput(), AsInputOutput()

Les méthodes AsOutput(), AsInput() et AsInputOutput() permettent respectivement de definir la direction d'un paramètre à ParameterDirection.Output, ParameterDirection.Input et ParameterDirection.InputOutput.

Elles s'appliquent au paramètre directement et renvoient une référence à ce même paramètre.

Exemple d'utilisation

Cet exemple présente l'exécution d'un programme MYPGM de la bibliothèque MYLIB dont les paramètres sont les suivants:

Description	Type	Direction	Valeur
Texte 1	CHAR(10)	Input	Hello
Texte 2	CHAR(10)	Input	World
Position de départ	BYTE(1)	Input	0x00
Longueur de la variable retour	BYTE(4)	Input	128
Variable retour	CHAR(128)	Output	vide
Code d'erreur	CHAR(50)	InputOutput	vide

On souhaite lire différentes valeurs dans la variable retour composée ainsi:

Offset	Longueur	Description
0	64	Message 1
64	64	Message 2

L'appel serait réalisé avec le code suivant:

//Ouverture d'une connexion NTi:
NTiConnection conn = new NTiConnection(connectionString);
conn.Open();

//Création de la liste de paramètres:
List<NTiProgramParameter> parms = new List<NTiProgramParameter>() {
  new NTiProgramParameter("Hello", 10).AsInput(),
  new NTiProgramParameter("World", 10).AsInput(),
  new NTiProgramParameter(new byte[] {0x00}).AsInput(),
  new NTiProgramParameter(128).AsInput(),
  new NTiProgramParameter("", 128).AsOutput(),
  new NTiProgramParameter("", 50)
};

//Appel du programme
conn.CallProgram("MYLIB", "MYPGM", parms);

//Récupération des données dans la variable retour (paramètre n°5)
string message1 = parms[4].GetString(0, 64);
string message2 = parms[4].GetString(64, 64);