![Passing input to the EC Gateway executable [EDI 4.2]](arrow-left.gif){kind=icon}
The EC Gateway DLL shared library includes the ability to pass input into EC Gateway from the calling program and return output to the calling program. This is accomplished through an array of data structures called DATAIOSTRUCT where each structure contains a tag name, a pointer to the value, the length of the value, and the length of the buffer containing the value. Each structure can be referenced by its tag name or by its index, which is its position in the array structure.
With this capability, EC Gateway can dynamically increase the size of the array that it returns to the calling program. For example, if EC Gateway were to return an output for each item in the data, it would not know in advance, nor would the calling program know, how many items are to be returned. However, the array can be increased in size, one structure for each item found in the data.
The syntax for calling the DLL shared library is:
__declspec( dllexport ) int __stdcall wsprocesDataIO (LPSTR lpszCmdLine, DATAIOSTRUCT ** pDataIO)
where lpszCmdLine is the command line for the wsproces executable defined in section 3.6.
The structure DATAIOSTRUCT is defined as:
typedef struct {
char *tag;
char **pdata;
long *pdatalen;
long *pbuflen;
} DATAIOSTRUCT;
This structure has four fields, which are:
tag – is for a pointer to the name of the data that can be referenced within a script.
pdata – is for a pointer to the buffer for the data.
pdatalen – is for a pointer to the length of the data.
pbuflen – is for a pointer to the length of the storage buffer allocated for the data.
The array is terminated by an extra structure with its tag pointer set to NULL.
With this API, if there is no input data or output data to be passed in memory, the array of data I/O structures is not needed and the calling application should set the second parameter to NULL. The calling application must define a command line, which must include the script file name. For upward compatibility, for example if converting from the executable to the DLL, you can still enter the input parameters using the command line syntax of -p1 through -p20 and you can still assign them using the Assign command.
Use the AssignInput and AssignOutput commands to move data between the array of data structures and EC Gateway message variables, parameter variables, or shared memory variables.
When using the AssignInput command, you must provide values for the Destination, Source By, and Source Value parameters.
The Destination parameter identifies the variable to initialize. You can choose a Message variable, a Parameter variable, or a Shared Memory variable for the destination.
Source By is a string, either Tag or Index.
Source Value depends on the value for Source By:
If the Source By is Tag, then the value should be a string with the tag name of one of the structures in the array.
If the Source By is Index, then the value should be an integer with the index of a structure in the array.
The first structure in the array corresponds to index zero (0).
When you use the AssignOutput command, you must provide the values for Destination By, Destination Value, Source Data, and Overwrite/Append parameters.
Destination By and Destination Value define which structure in the array you want to set. Destination By is a string, either Tag or Index. Destination Value depends on the Destination By value.
If the Destination By value is Tag, then the value should be a string. If that value matches a tag name in the original structure, that structure is updated. If that value does not match any tag name in the structure, EC Gateway automatically adds another structure to the array with that tag name.
If the Destination By value is Index, then the value must be an integer in the range of the already existing structures in the array. If the Index is not in range, it does not add another structure to the array.
The Source Data identifies the variable with the data to be used to update the structure. You can choose a Message variable, a Parameter variable, or a Shared Memory variable for the destination.
The Overwrite/Append indicates whether the data should overwrite the data already in the buffer or append to it.
