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`	`ParameterDirection.InputOutput`	Direction du paramètre: `ParameterDirection.InputOutput` : Entrée/Sortie `ParameterDirection.Input` : Entrée `ParameterDirection.Output` / `ParameterDirection.ReturnValue` : Sortie

Constructeurs

1. Nouveau paramètre vide

Syntaxe	Description
new `NTiProgramParameter()`	Crée un paramètre vide avec la direction `InputOutput`.
new `NTiProgramParameter(ParameterDirection direction)`	Crée un paramètre vide avec une direction spécifique (`Input`, `Output`, ou `InputOutput`).

new NTiProgramParameter(); // Paramètre vide (InputOutput)
new NTiProgramParameter(ParameterDirection.Input); // Paramètre d'entrée uniquement

2. Nouveau paramètre de type binaire brut

Syntaxe	Description
new `NTiProgramParameter(byte[] value)`	Crée un paramètre avec des données binaires d'entrée (`byte[]`).
new `NTiProgramParameter(byte[] value, ParameterDirection direction)`	Crée un paramètre binaire avec une direction spécifique (`Input`, `Output`, ou `InputOutput`).

new NTiProgramParameter(new byte[] {0x00}); // Paramètre binaire initialisé avec un tableau de bytes
new NTiProgramParameter(new byte[] {0xFF}, ParameterDirection.Input); // Paramètre binaire d'entrée uniquement

3. 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).

Syntaxe	Description
new `NTiProgramParameter(string value, int length)`	Crée un paramètre chaîne de caractères tronqué ou complété à `length` caractères (remplissage avec des blancs `0x40`).
new `NTiProgramParameter(string value, int length, ParameterDirection direction)`	Crée un paramètre chaîne avec une direction spécifique.
new `NTiProgramParameter(string value, int length, int ccsid)`	Spécifie un `ccsid` pour l'encodage des caractères.
new `NTiProgramParameter(string value, int length, int ccsid, ParameterDirection direction)`	Spécifie un `ccsid` et une direction.

new NTiProgramParameter("Hello", 10); // Chaîne de caractères tronquée/paddée sur 10 caractères
new NTiProgramParameter("World", 10, 1208); // Avec encodage CCSID spécifique

4. Nouveau paramètre de type tableau de caractères

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

Syntaxe	Description
new `NTiProgramParameter(string[] values, int length)`	Crée un paramètre avec un tableau de chaînes de caractères, chaque chaîne ayant une longueur fixe de length caractères.
new `NTiProgramParameter(string[] values, int length, ParameterDirection direction)`	Crée un tableau de chaînes de caractères avec une direction spécifique.
new `NTiProgramParameter(string[] values, int length, int ccsid)`	Crée un tableau de chaînes de caractères avec un encodage spécifique (CCSID).
new `NTiProgramParameter(string[] values, int length, int ccsid, ParameterDirection direction)`	Crée un tableau de chaînes avec un encodage et une direction spécifiques.
new `NTiProgramParameter(IEnumerable<string> values, int length)`	Utilise une collection `IEnumerable` pour créer un tableau de chaînes de caractères de longueur fixe.
new `NNTiProgramParameter(IEnumerable<string> values, int length, ParameterDirection direction)`	Utilise une collection `IEnumerable` avec une direction spécifique.
new `NTiProgramParameter(IEnumerable<string> values, int length, int ccsid)`	Utilise une collection `IEnumerable` avec un encodage CCSID.
new `NTiProgramParameter(IEnumerable<string> values, int length, int ccsid, ParameterDirection direction)`	Utilise une collection `IEnumerable` avec un encodage CCSID et une direction spécifique.

new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10); // Tableau de chaînes avec une longueur fixe de 10 caractères
new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10, ParameterDirection.Input); // Tableau de chaînes avec une direction d'entrée uniquement
new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10, 1208); // Tableau de chaînes avec un encodage CCSID spécifique
new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10, 1208, ParameterDirection.Input); // Tableau de chaînes avec un encodage CCSID et une direction d'entrée uniquement
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10); // Utilisation d'une collection IEnumerable avec une longueur fixe
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10, ParameterDirection.Input); // Utilisation d'une collection IEnumerable avec une direction d'entrée uniquement
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10, 1208); // Utilisation d'une collection IEnumerable avec un encodage CCSID
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10, 1208, ParameterDirection.Input); // Utilisation d'une collection IEnumerable avec un encodage CCSID et une direction d'entrée

5. Nouveau paramètre de type entier

Entier 32 bits (4 octets):

Syntaxe	Description
new `NTiProgramParameter(int value)`	Crée un paramètre avec un entier 32 bits (Binary(4)).
new `NTiProgramParameter(int value, ParameterDirection direction)`	Crée un paramètre entier avec une direction spécifique.

new NTiProgramParameter(100); // Entier 32 bits

16 bits (2 octets):

Syntaxe	Description
new `NTiProgramParameter(short value)`	Crée un paramètre avec un entier 16 bits (Binary(2)).
new `NTiProgramParameter(short value, ParameterDirection direction)`	Crée un paramètre entier avec une direction spécifique.

new NTiProgramParameter((short)50); // Entier 16 bits

6. Nouveau paramètre de type tableau d'entiers

Entiers 32 bits (4 octets):

Syntaxe	Description
new `NTiProgramParameter(int[] values)`	Crée un paramètre avec un tableau d'entiers 32 bits.
new `NTiProgramParameter(int[] values, ParameterDirection direction)`	Crée un tableau d'entiers 32 bits avec une direction spécifique.
new `NTiProgramParameter(IEnumerable<int> values)`	Utilise une collection IEnumerable pour créer un tableau d'entiers 32 bits.
new `NTiProgramParameter(IEnumerable<int> values, ParameterDirection direction)`	Utilise une collection IEnumerable pour créer un tableau d'entiers 32 bits avec une direction spécifique.

new NTiProgramParameter(new int[] { 100, 200, 300 }); // Tableau d'entiers 32 bits
new NTiProgramParameter(new int[] { 100, 200, 300 }, ParameterDirection.Input); // Tableau d'entiers 32 bits, direction entrée uniquement
new NTiProgramParameter(new List { 100, 200, 300 }); // Collection IEnumerable d'entiers 32 bits
new NTiProgramParameter(new List { 100, 200, 300 }, ParameterDirection.Output); // Collection IEnumerable d'entiers 32 bits avec direction sortie

Entiers 16 bits (2 octets):

Syntaxe	Description
new `NTiProgramParameter(short[] values)`	Crée un paramètre avec un tableau d'entiers 16 bits.
new `NTiProgramParameter(short[] values, ParameterDirection direction)`	Crée un tableau d'entiers 16 bits avec une direction spécifique.
new `NTiProgramParameter(IEnumerable<short> values)`	Utilise une collection IEnumerable pour créer un tableau d'entiers 16 bits.
new `NTiProgramParameter(IEnumerable<short> values, ParameterDirection direction)`	Utilise une collection IEnumerable pour créer un tableau d'entiers 16 bits avec une direction spécifique.

new NTiProgramParameter(new short[] { 10, 20, 30 }); // Tableau d'entiers 16 bits
new NTiProgramParameter(new short[] { 10, 20, 30 }, ParameterDirection.Output); // Tableau d'entiers 16 bits, direction sortie uniquement
new NTiProgramParameter(new List { 10, 20, 30 }); // Collection IEnumerable d'entiers 16 bits
new NTiProgramParameter(new List { 10, 20, 30 }, ParameterDirection.Input); // Collection IEnumerable d'entiers 16 bits avec direction entrée

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

Syntaxe	Description
new `NTiProgramParameter(decimal value, int precision, int scale)`	Crée un paramètre décimal PACKED avec une précision et une échelle spécifiques.
new `NTiProgramParameter(decimal value, int precision, int scale, ParameterDirection direction)`	Crée un paramètre décimal PACKED avec une direction spécifique.

new NTiProgramParameter(123.45, 7, 2); // Paramètre décimal PACKED avec précision 7, échelle 2
new NTiProgramParameter(678.90, 9, 3, ParameterDirection.Input); // Paramètre décimal PACKED avec direction entrée uniquement

Méthodes

1. Append() `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});

2. GetString() `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

param.GetString(0, 64); // Récupère 64 caractères à partir de l'offset 0

3. GetInt() `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`)

param.GetInt(4); // Récupère un entier à partir de l'offset 4

4. GetBytes() `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[]`)

param.GetBytes(0, 10); // Récupère 10 octets à partir de l'offset 0

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 parms = new List() {
  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);

Classe `NTiProgramParameter`

Description

Propriétés

Constructeurs

1. Nouveau paramètre vide

2. Nouveau paramètre de type binaire brut

3. Nouveau paramètre de type caractères

4. Nouveau paramètre de type tableau de caractères

5. Nouveau paramètre de type entier

6. Nouveau paramètre de type tableau d'entiers

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

Méthodes

1. Append() `Append(...)`

2. GetString() `string GetString(...)`

3. GetInt() `int GetInt(...)`

4. GetBytes() `byte[] GetBytes(...)`

Extensions du type

`IList<NTiProgramParameter>.Add(...)`

`AsOutput()`, `AsInput()`, `AsInputOutput()`

Exemple d'utilisation

AUMERIAL

DOCUMENTATION

Classe NTiProgramParameter

Description

Propriétés

Constructeurs

1. Nouveau paramètre vide

2. Nouveau paramètre de type binaire brut

3. Nouveau paramètre de type caractères

4. Nouveau paramètre de type tableau de caractères

5. Nouveau paramètre de type entier

6. Nouveau paramètre de type tableau d'entiers

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

Méthodes

1. Append() Append(...)

2. GetString() string GetString(...)

3. GetInt() int GetInt(...)

4. GetBytes() byte[] GetBytes(...)

Extensions du type

IList<NTiProgramParameter>.Add(...)

AsOutput(), AsInput(), AsInputOutput()

Exemple d'utilisation

AUMERIAL

DOCUMENTATION

Classe `NTiProgramParameter`

1. Append() `Append(...)`

2. GetString() `string GetString(...)`

3. GetInt() `int GetInt(...)`

4. GetBytes() `byte[] GetBytes(...)`

`IList<NTiProgramParameter>.Add(...)`

`AsOutput()`, `AsInput()`, `AsInputOutput()`