[Proposal] Enhanced Usability for SAP JCo Function Execution in Ballerina with Multiple Parameters

[RDPerera]

This proposal outlines the mapping of JCo data types to Ballerina data types for the SAP JCo Connector. The objective is to ensure accurate and efficient data exchange between SAP systems and Ballerina applications by providing clear and consistent mappings for both import (setters) and export (getters) parameter types.

JCo to Ballerina Data Type Mapping

ABAP Type	Description	Ballerina Type
CHAR	Fixed-length character string	string
CHAR	Single character	string
NUMC	Numeric text	string
INT1	1-byte integer	int
INT2	2-byte integer	int
INT4	4-byte integer	int
INT8	8-byte integer (if supported)	int
FLTP	Floating-point number	float
DEC	Packed decimal	decimal
RAW/XSTR	Variable-length byte string	byte[]
CHAR/FLAG	Character representing true/false (e.g., 'X' for true)	boolean
DATS	Date in the format YYYYMMDD	time:Date
TIMS	Time in the format HHMMSS	time:TimeOfDay
DATS/TIMS	Combination of date and time	time:Utc
LANG	Language key	string
CUKY	Currency key	string
QUAN	Quantity field	decimal
UNIT	Unit of measure	string

Complex ABAP Type	Description	Ballerina Type
STRUCTURE	Group of fields	record {}
TABLE	Multi-row dataset, array of structures	record{}[]

[niveathika]

When considering the use case for input parameters and output parameters in SAP JCo, the RFC accepts multiple values. To improve usability, we can introduce two functions in Ballerina:

public type FieldType string|int|float|decimal|boolean|byte[]|time:Date|time:TimeOfDay|time:Utc|record {|FieldType...;|}|record {|FieldType...;|}[];

isolated remote function execute(string functionName, FieldType? importParams = (), typedesc<FieldType|FieldType[]|map<FieldType>|xml|json?> exportParams = <>) returns exportParams|Error;

isolated remote function executeWithMultipleParams(string functionName, FieldType[]|map<FieldType>? importParams = (), typedesc<FieldType|FieldType[]|map<FieldType>|xml|json?> exportParams = <>) returns exportParams|Error;

The execute() function can be used when there is only one input parameter, and executeWithMultipleParams() can be used for multiple values.

For the output return, all simple types can be used to bind to specific types:

// Returns one string field
string result = check jcoClient->execute("functionName", "a");

// Returns multiple fields in order
FieldType[] results = check jcoClient->execute("functionName", "a");

// Returns multiple fields with parameter names
map<string> resultsMap = check jcoClient->execute("functionName", "a");

// Returns one JCoStructure
record{||} structure = check jcoClient->execute("functionName", "a");

// Returns one JCoStructure with parameter names
map<record{||}> structuresMap = check jcoClient->execute("functionName", "a");

// Returns a table
record{||}[] table = check jcoClient->execute("functionName", "a");

// Returns multiple tables in positional value
record{||}[][] tables = check jcoClient->execute("functionName", "a");

To handle the case where multiple JCoStructures are expected in an array, we introduce a special annotation:

public annotation MultiStructure on type;

@MultiStructure
type MultipleValues record{||}[];

MultipleValues _ = check jcoClient->execute("", "a");

This exception addresses potential confusion when the user expects either one return value of table type or multiple JCoStructures in an array.

Note on Data Mapping in Ballerina
In Ballerina, another consideration for data mapping is to process all return values if the return type is an open record, or only return specified fields for closed records. This will not apply to JCoStructure or JCoTable. Due to compile-time validation of types, the user must always use a closed record. Since these types contain only limited fields, significant performance degradation due to this behavior is not expected.