PLSProviderEngine.ci Module

Use this module when you want to invoke a provider to produce results that can be displayed or acted on in a custom table or report that you create. Providers invoked by this method must be written so that they take a single string as input and return a single string as output.

Module construction

The following string functions are included in this module:

CallProvider

This function invokes a provider (whose GUID-based identifier must appear in the sProvider argument) with a single string as input (the sArgs argument). The input string can consist of anything that is meaningful to the provider that you invoke.

The provider then returns a string-based token.

Construction of CallProvider:

STRING FUNCTION CallProvider(STRING sProvider, STRING sArgs)
	INT hHandle;
	STRING sResult;
	ErrSet(1);
	sProvider = "^"" + sProvider + "^"";
	sArgs = "^"" + sArgs + "^"";
	hHandle = DLLOpen("ProviderGatewayUnmanaged.dll", "MakeRequest", "CCC");
	sResult = DLLCall(hHandle, sProvider + "," + sArgs);
	DLLClose(hHandle);
	IF IsError() THEN RETURN "ERROR"; END
	RETURN sResult;
END
--------------

GetProviderStatus

This function reports the status of a provider invocation by showing the percentage of its completeness. A provider has completed its work when the status reaches 100 percent,

To retrieve status with this function, pass in a token (obtained previously by calling CallProvider) and examine the number contained in the function's return string (from 0 to 100).

Construction of GetProvider Access:

------------
STRING FUNCTION GetProviderStatus(STRING sToken)
	INT hHandle;
	INT iPercent;
	ErrSet(1);
		sToken = "^"" + sToken + "^"";
	hHandle = DLLOpen("ProviderGatewayUnmanaged.dll", "GetPercent", "JC");
	iPercent = DLLCall(hHandle, sToken);
	DLLClose(hHandle);
	IF IsError() THEN RETURN "ERROR"; END
	RETURN iPercent;
END
-------------

GetProviderResult

This function retrieves the result from a provider. Pass a unique token (obtained previously by calling CallProvider) to this function. It returns the provider result as a string. Note that you should only call this function after you verify that the provider work is 100 percent complete.

Construction of GetProviderResult:

------------
STRING FUNCTION GetProviderResult(STRING sToken)
	INT hHandle;
	STRING sResult;
	ErrSet(1);
	sToken = "^"" + sToken + "^"";
	hHandle = DLLOpen("ProviderGatewayUnmanaged.dll", "GetResult", "CC");
	sResult = DLLCall(hHandle, sToken);
	DLLClose(hHandle);
	IF IsError() THEN RETURN "ERROR"; END
	RETURN sResult;
END
--------------