x

GET_API_DEFINITION Parameters:

Parameter Name	Mode	Data Type	Description
API_NAME	IN	VARCHAR2	The name of the API to be called by the wrapper.
REQUEST_SCHEMA	OUT	VARCHAR2	API Input parameter and data type string.
RESPONSE_SCHEMA	OUT	VARCHAR2	API Output parameter and data type string.
DEBUG_LEVEL	IN	NUMBER	0 = Debug off. 1 = Debug on.
WRAPPER_STATUS	OUT	VARCHAR2	Wrapper status.

REQUEST SCHEMA:

The following initialization parameters are required to run the standard APIs: org_id, application_id, responsibility_id, and user_id. These will be passed as part of the request schema, although they are not generated from the data dictionary. Each request_schema generated by the get_api_definition will start with the four required initialization parameters as follows:

REQUEST_SCHEMA = 'ORG_ID|||NUMBER|||USER_ID|||NUMBER|||
APPLICATION_ID|||NUMBER|||RESPONSIBILITY_ID|||NUMBER|||..........'

IN OUT PARAMETERS:

Parameters with a mode of IN/OUT will be passed in both the REQUEST and RESPONSE schema. There will be no other designation for IN/OUT parameters.

CUSTOM TABLE FOR IN/OUT PARAMETERS:

A custom table, iway_api_parameters, will be loaded with the IN/OUT parameters for a given API when that API is called in the get_api_definition procedure. The procedure will remove any existing records for the given API and then load the table with the appropriate IN/OUT parameters. This will be used by the run_api procedure as described in the following section.

DELIMITERS:

The field delimiter is |||, the record delimiter (which is used for pl/sq advanced record types) is ###, and the table type delimiter is ***.

PARAMETER FORMAT:

1. Table type parameter name.
2. Table type delimiter.
3. Field name or null value.
4. Field delimiter.
5. Datatype.

Example metadata for table based on a pl/sql record:

In this example, the table type parameter name = 'P_LINES_TABLE' which is based on a pl/sql record with three fields, 'link_to_line_index', 'rev_exist', 'unearn_exist'.

P_LINES_TABLE***LINK_TO_LINE_INDEX|||BINARY_INTEGER|||
P_LINES_TABLE***REV_EXIST|||VARCHAR2|||
P_LINES_TABLE***UNEARN_EXIST|||VARCHAR2

Example of table based on varchar2:

In this example, when tables are comprised of a scalar datatype, the table type parameter name = 'P_TBL_VCHR' and there are no field names.

P_TBL_VCHR***|||VARCHAR2

Since there is no field name between the table delimiter and the field delimiter, it is a table based on a scalar datatype of varchar2.

DEBUG LEVEL:

The debug_level parameter is passed with a value of 1, so that the wrapper will write messages to the log file, IWAY_WRAPPER_LOG.txt. You can change this setting in the iway_ora_api_wrapper.pks file and recompile the wrapper.

For more detailed debugging, you must logon to the iWay Service Manager Administration Console and modify the trace settings by selecting the Deep check box, as shown in the following image.

Click Update when you are finished.

For more information on how to modify trace settings using the iWay Service Manager Administration Console, see the iWay Service Manager User’s Guide.

WRAPPER STATUS:

The wrapper status parameter returns wrapper specific success or failure messages. For example, if you pass an incorrect API name to the get_api_definition, the wrapper status will be as follows:

WRAPPER_RETURN_STATUS|||ERROR|||WRAPPER_RETURN_CODE|||
INVALID_API_NAME|||WRAPPER_RETURN_MESSAGE|||

Invalid API name supplied. Cannot obtain Parameter Definitions from Oracle.

Parsed, it looks like this:

WRAPPER_RETURN_STATUS	ERROR
WRAPPER_RETURN_CODE	INVALID_API_NAME
WRAPPER_RETURN_MESSAGE	Invalid API name supplied. Cannot obtain Parameter Definitions from Oracle.

x

RUN_API Parameters:

Parameter Name	Mode	Data Type	Description
API_NAME	IN	VARCHAR2	The name of the API to be called on by the wrapper.
API_PARAMETER_VALUES	IN	VARCHAR2	String with the parameter_name, data type, and value based on the REQUEST_SCHEMA of the get_api_definition procedure.
API_OUTPUT_PARAMETERS	IN	VARCHAR2	The definition of the API output parameters. These parameters are needed as placeholders during the dynamic call to the APIs.
API_RETURN_STATUS	OUT	VARCHAR2	API output values, error codes and messages.
DEBUG_LEVEL	IN	NUMBER	0 = Debug off. 1 = Debug on.

API PARAMETER VALUES

The adapter sends back the four initialization parameters defined in the get_api_definition request_schema for a given API. These are required parameters. The parameters are passed as part of the normal request_schema in the get_api_definition procedure.

IN OUT PARAMETERS:

The run_api parameter will test parsed API parameters from the API_PARAMETER_VALUES wrapper input parameter against the iway_api_parameter table to determine if any parameters are of mode IN/OUT. Those API parameters that are IN/OUT will be assigned a variable, the value passed in the api_parameter_values parameter will be assigned to that variable, and the variable will be passed to the API as an IN/OUT parameter. Those API parameters that are IN parameters will be passed with the actual value provided.

The API_OUTPUT_PARAMETERS response_schema parameter is also tested to ensure that the IN/OUT parameters already added to the call string as part of the API_PARAMETER_VALUES parsing are excluded. This is to make sure that the IN/OUT parameter is not added twice to the dynamically built call string.

The RETURN_STATUS parameter strings together all of the OUT and IN/OUT parameters, and their associated values, passed as part of the API_OUTPUT_PARAMETERS parameter and returns them to the adapter.

DELIMITERS:

The field delimiter is |||, the record delimiter is ### (which is used for pl/sq advanced record types), and the table type delimiter is ***.

PARAMETER FORMATS:

For run time, the format will be based on table type parameters as follows:

When data is passed for table type parameters from the adapter to the wrapper in run_api, the adapter must pass the parameter name, the table row number, the table field name if the table is based on PL/SQL record, and the actual data value if it is based on scalar datatype.

1. Table type parameter name.
2. Table type delimiter.
3. Field name or null value.
4. Field delimiter
5. Data

Example of table based on a pl/sql record:

In this example, the table type parameter name = 'P_LINES_TABLE' which is based on a pl/sql record with three fields, 'link_to_line_index', 'rev_exist', 'unearn_exist'.

P_LINES_TABLE(1)***LINE_RECLINK_TO_LINE_INDEX|||103|||
P_LINES_TABLE(1)***REV_EXIST|||YES|||
P_LINES_TABLE(1)***UNEARN_EXIST|||NO|||
P_LINES_TABLE(2)***LINK_TO_LINE_INDEX|||2|||
P_LINES_TABLE(2)***REV_EXIST|||NO|||
P_LINES_TABLE(2)***UNEARN_EXIST|||YES|||

Example of table based on varchar2:

In this example, when tables are comprised of a scalar datatype, the table type parameter name = 'P_TBL_VCHR' and there are no field names.

P_TBL_VCHR(1)***|||Hi There - This is row 1|||
P_TBL_VCHR(2)***|||Hi There - This is row 2|||
P_TBL_VCHR(1)***|||And so on and so on...|||

API RETURN STATUS

The run_api procedure uses API_RETURN_STATUS to provide API and wrapper specific messages.

DEBUG LEVEL:

When the debug_level parameter is passed with a value of 1, the wrapper will write messages to the log file.

DATA TYPE CONVERSIONS:

Oracle API data type	Converted Adapter schema data type
BIT	Boolean
BOOLEAN	Boolean
TINYINT	Short
SMALLINT	Short
INTEGER	Int
BIGINT	Long
FLOAT	Double
REAL	Double
DOUBLE	Double
NUMERIC	Double
NUMBER	Double
DECIMAL	Int

All other oracle API data types will be converted and represented as 'string' in the schemas.

x

The wrapper generates additional parameters that are sent to the adapter when generating schemas. These are special parameters that are needed to run any Stored procedure.

Org_ID: The ID of the organization that the user needs to execute the API. For example, the ID of the Seattle Manufacturing organization.

Responsibility_ID: The ID of the responsibility that will be used to execute the API. For example, the Receivables manager responsibility ID.

User_ID: The ID of the user that will be used to execute the procedure, such as the ID of sysadmin.

Application_ID: The ID of the application module that will be used to execute the API. For example, ID of the general Ledger module.

iWay_Oraapps: Whether the procedure should be executed with oracle application logic or as a normal RDBMS procedure. Leaving this parameter blank or setting it to Y will execute it as an oracle application procedure and setting it to N will execute it as a Non-Oracle apps procedure.