`NTiProgramParameter` Class

Description

The NTiProgramParameter class represents an IBM i program or IBM i system API parameter. It can be input, output or input/output.

Properties

Name	Type	Default Value	Description
`InputData`	`byte[]`		Parameter input data
`OutputData`	`byte[]`		Parameter output data
`Direction`	`System.Data.ParameterDirection`	`ParameterDirection.InputOutput`	Parameter direction: `ParameterDirection.InputOutput` : Input/Output `ParameterDirection.Input` : Input `ParameterDirection.Output` / `ParameterDirection.ReturnValue` : Output

Constructors

1. New empty parameter

Syntax	Description
new `NTiProgramParameter()`	Creates an empty parameter with the direction `InputOutput`.
new `NTiProgramParameter(ParameterDirection direction)`	Creates an empty parameter with a specific direction (`Input`, `Output`, or `InputOutput`).

new NTiProgramParameter(); // Empty parameter (InputOutput)
new NTiProgramParameter(ParameterDirection.Input); // Input parameter only

2. New raw binary type parameter

Syntax	Description
new `NTiProgramParameter(byte[] value)`	Creates a parameter with binary input data (`byte[]`).
new `NTiProgramParameter(byte[] value, ParameterDirection direction)`	Creates a binary parameter with a specific direction (`Input`, `Output`, or `InputOutput`).

new NTiProgramParameter(new byte[] {0x00}); // Binary parameter initialised with an array of bytes
new NTiProgramParameter(new byte[] {0xFF}, ParameterDirection.Input); // Binary input parameter only

3. New character parameter

The length parameter corresponds to the length expected by the program for this parameter. Value will be either truncated or padded with blanks (0x40).

Syntax	Description
new `NTiProgramParameter(string value, int length)`	Creates a string parameter truncated or padded to `length` characters (padded with `0x40` blanks).
new `NTiProgramParameter(string value, int length, ParameterDirection direction)`	Creates a string parameter with a specific direction.
new `NTiProgramParameter(string value, int length, int ccsid)`	Specifies a `ccsid` for character encoding.
new `NTiProgramParameter(string value, int length, int ccsid, ParameterDirection direction)`	Specifies a `ccsid` and a direction.

new NTiProgramParameter(‘Hello’, 10); // Character string truncated/padded to 10 characters
new NTiProgramParameter(‘World’, 10, 1208); // With specific CCSID encoding

4. New character array parameter

The length parameter corresponds to the final length of each value.

Syntax	Description
new `NTiProgramParameter(string[] values, int length)`	Creates a parameter with an array of strings, each string having a fixed length of characters.
new `NTiProgramParameter(string[] values, int length, ParameterDirection direction)`	Creates an array of strings with a specific direction.
new `NTiProgramParameter(string[] values, int length, int ccsid)`	Creates an array of character strings with a specific encoding (CCSID).
new `NTiProgramParameter(string[] values, int length, int ccsid, ParameterDirection direction)`	Creates an array of strings with a specific encoding and direction.
new `NTiProgramParameter(IEnumerable<string> values, int length)`	Uses an `IEnumerable` collection to create an array of fixed-length strings.
new `NNTiProgramParameter(IEnumerable<string> values, int length, ParameterDirection direction)`	Uses an `IEnumerable` collection with a specific direction.
new `NTiProgramParameter(IEnumerable<string> values, int length, int ccsid)`	Uses an `IEnumerable` collection with CCSID encoding.
new `NTiProgramParameter(IEnumerable<string> values, int length, int ccsid, ParameterDirection direction)`	Uses an `IEnumerable` collection with a CCSID encoding and a specific direction.

new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10); // Array of strings with a fixed length of 10 characters
new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10, ParameterDirection.Input); // Array of strings with one input direction only
new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10, 1208);  // Array of strings with specific CCSID encoding
new NTiProgramParameter(new[] {"QTIME", "QDATE"}, 10, 1208, ParameterDirection.Input); // Array of strings with CCSID encoding and input direction only
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10); // Use of an IEnumerable collection with a fixed length
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10, ParameterDirection.Input);  // Use of an IEnumerable collection with one input direction only
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10, 1208); // Use of an IEnumerable collection with CCSID encoding
new NTiProgramParameter(new List {"QTIME", "QDATE"}, 10, 1208, ParameterDirection.Input); // Use of an IEnumerable collection with CCSID encoding and input direction

5. New integer parameter

32-bit integer (4 bytes):

Syntax	Description
new `NTiProgramParameter(int value)`	Creates a parameter with a 32-bit integer (Binary(4)).
new `NTiProgramParameter(int value, ParameterDirection direction)`	Creates an integer parameter with a specific direction.

new NTiProgramParameter(100); // 32-bit integer

16-bit integer (2 bytes):

Syntax	Description
new `NTiProgramParameter(short value)`	Creates a parameter with a 16-bit integer (Binary(2)).
new `NTiProgramParameter(short value, ParameterDirection direction)`	Creates an integer parameter with a specific direction.

new NTiProgramParameter((short)50); // 16-bit integer

6. New integer array type parameter

32-bit integers (4 bytes):

Syntax	Description
new `NTiProgramParameter(int[] values)`	Creates a parameter with an array of 32-bit integers.
new `NTiProgramParameter(int[] values, ParameterDirection direction)`	Creates an array of 32-bit integers with a specific direction.
new `NTiProgramParameter(IEnumerable<int> values)`	Uses an IEnumerable collection to create an array of 32-bit integers.
new `NTiProgramParameter(IEnumerable<int> values, ParameterDirection direction)`	Uses an IEnumerable collection to create an array of 32-bit integers with a specific direction.

new NTiProgramParameter(new int[] { 100, 200, 300 });  // 32-bit integer array
new NTiProgramParameter(new int[] { 100, 200, 300 }, ParameterDirection.Input); // 32-bit integer array, input direction only
new NTiProgramParameter(new List { 100, 200, 300 }); // IEnumerable collection of 32-bit integers
new NTiProgramParameter(new List { 100, 200, 300 }, ParameterDirection.Output);  // IEnumerable collection of 32-bit integers with output direction

16-bit integers (2 bytes):

Syntax	Description
new `NTiProgramParameter(short[] values)`	Creates a parameter with an array of 16-bit integers.
new `NTiProgramParameter(short[] values, ParameterDirection direction)`	Creates an array of 16-bit integers with a specific direction.
new `NTiProgramParameter(IEnumerable<short> values)`	Uses an IEnumerable collection to create an array of 16-bit integers.
new `NTiProgramParameter(IEnumerable<short> values, ParameterDirection direction)`	Uses an IEnumerable collection to create an array of 16-bit integers with a specific direction.

new NTiProgramParameter(new short[] { 10, 20, 30 });  // 16-bit integer array
new NTiProgramParameter(new short[] { 10, 20, 30 }, ParameterDirection.Output); // 16-bit integer array, output direction only
new NTiProgramParameter(new List { 10, 20, 30 }); // IEnumerable collection of 16-bit integers
new NTiProgramParameter(new List { 10, 20, 30 }, ParameterDirection.Input); // IEnumerable collection of 16-bit integers with input direction

7. New decimal type parameter (PACKED(precision, scale))

Syntax	Description
new `NTiProgramParameter(decimal value, int precision, int scale)`	Creates a PACKED decimal parameter with a specific precision and scale.
new `NTiProgramParameter(decimal value, int precision, int scale, ParameterDirection direction)`	Creates a PACKED decimal parameter with a specific direction.

new NTiProgramParameter(123.45, 7, 2); // PACKED decimal parameter with precision 7, scale 2
new NTiProgramParameter(678.90, 9, 3, ParameterDirection.Input); // Decimal parameter PACKED with direction input only

Methods

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

The Append method is used to complete the input data value of an existing parameter. This method is useful when a parameter has a complex structure made up of several pieces of data, possibly of different types. Parameters and usage are analogous to the constructors above.

Variant	Description
`Append(byte[] value)`	Adds the `value` data after the parameter data without modification
`Append(string value, int length)` `Append(string value, int length, int ccsid)`	Adds a `value` character string of fixed length `length` using the CCSID of the current QZRCSRVS job or by specifying the CCSID used for character encoding
`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)`	Adds a string of characters `values`, each of fixed length `length` using the CCSID of the current QZRCSRVS job or by specifying the CCSID used for character encoding
`Append(int value)`	Adds a 32-bit integer `value`
`Append(short value)`	Adds a 16-bit integer `value`
`Append(int[] value)` `Append(IEnumerable<int> value)`	Adds a collection of 32-bit integers `values`
`Append(short[] value)` `Append(IEnumerable<short> value)`	Adds a collection of 16-bit integers `values`
`Append(decimal value, int precision, int scale)`	Adds a decimal number `value` in PACKED(precision, scale) format

The Append() method returns a reference to the parameter and can therefore be called in a chain to build complex data structures.
Example:
//parm below is composed as follows:
//    -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(...)`

The GetString method is used to retrieve text from the output data of an existing parameter. This method is used after the execution of a program to read in the data returned by the program.

Variant	Description
`GetString()` `GetString(int ccsid)`	Returns the entire parameter output as text (`string`) using the CCSID of the current QZRCSRVS job or by specifying the CCSID used for character encoding	.
`GetString(int offset, int length)` `GetString(int offset, int length, int ccsid)`	Returns `length` characters from the `offset` position in the parameter output data as text (`string`) using the CCSID of the current QZRCSRVS job or specifying the CCSID used for character encoding

param.GetString(0, 64); // Retrieves 64 characters from offset 0

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

The GetInt method is used to retrieve an integer from the output data of an existing parameter. This method is used after the execution of a program to read in the data returned by the program.

Variant	Description
`GetInt()`	Returns the first 4 bytes of the output data as an integer (`int`).
`GetInt(int offset)`	Returns the 4 bytes from the `offset` position in the output data as an integer (`int`).

param.GetInt(4); // Retrieves an integer from offset 4

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

The GetBytes method is used to retrieve the output data of an existing parameter in raw binary form. This method is used after a program has been executed to read the data returned by the program.

Variant	Description
`GetBytes()`	Returns the entire parameter output data in raw binary form (`byte[]`)
`GetBytes(int offset, int length)`	Returns `length` bytes from the `offset` position in the parameter output data in raw binary form (`byte[]`)

param.GetBytes(0, 10); // Gets 10 bytes from offset 0

Type extensions

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

The Add() method for elements of type IList<NTiProgramParameter> is extended to take on the same functionality as constructors.

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

The AsOutput(), AsInput() and AsInputOutput() methods respectively define the direction of a parameter to ParameterDirection.Output, ParameterDirection.Input and ParameterDirection.InputOutput.

They apply to the parameter directly and return a reference to the same parameter.

Example of use

This example shows the execution of a MYPGM program from the MYLIB library with the following parameters:

Description	Type	Direction	Value
Text 1	CHAR(10)	Input	Hello
Text 2	CHAR(10)	Input	World
Start position	BYTE(1)	Input	0x00
Length of return variable	BYTE(4)	Input	128
Return variable	CHAR(128)	Output	empty
Error code	CHAR(50)	InputOutput	empty

We want to read different values in the return variable, composed as follows:

Offset	Length	Description
0	64	Message 1
64	64	Message 2

The call would be made using the following code:

//Opening an NTi connection:
NTiConnection conn = new NTiConnection(connectionString);
conn.Open();

//Creation of the parameter list:
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)
};

//Call the program
conn.CallProgram("MYLIB", "MYPGM", parms);

//Retrieving data from the return variable (parameter no. 5)
string message1 = parms[4].GetString(0, 64);
string message2 = parms[4].GetString(64, 64);

`NTiProgramParameter` Class

Description

Properties

Constructors

1. New empty parameter

2. New raw binary type parameter

3. New character parameter

4. New character array parameter

5. New integer parameter

6. New integer array type parameter

7. New decimal type parameter (PACKED(precision, scale))

Methods

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

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

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

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

Type extensions

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

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

Example of use

AUMERIAL

DOCUMENTATION

NTiProgramParameter Class

Description

Properties

Constructors

1. New empty parameter

2. New raw binary type parameter

3. New character parameter

4. New character array parameter

5. New integer parameter

6. New integer array type parameter

7. New decimal type parameter (PACKED(precision, scale))

Methods

1. Append() Append(...)

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

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

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

Type extensions

IList<NTiProgramParameter>.Add(...)

AsOutput(), AsInput(), AsInputOutput()

Example of use

AUMERIAL

DOCUMENTATION

`NTiProgramParameter` Class

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

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

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

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

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

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