Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

On this Page

Table of Contents
maxLevel3
excludeOlder Versions|Additional Resources|Related Links|Related Information

Overview

You can use this Snap to execute stored procedures in an Oracle database and write OUTparameter values to the output view. If an OUT parameter is:

  • Custom type OBJECT, then the output is displayed as a JSON object. 

  • Custom type TABLE, then the output is displayed as a JSON array. 

This Snap supports executing stored functions with OUT and INOUT parameters and writes these parameters in the output view along with the returnval key.

Multiexcerpt include macro
nameOracle JDBC Driver Upgrade
templateDataeJyLjgUAARUAuQ==
pageOracle Snap Pack
addpanelfalse

Info
iconfalse

Breaking change

With the 439patches29008Snap Pack version if any of your existing Oracle pipelines use the encoded ROWID(by manually handling the Base64 encoded data), your pipelines might break. To prevent your pipelines from failing, you must update your Snap Pack version to the latest version.


Info
iconfalse

Behavior change

Earlier, the ROWID columns were displayed in binary (Base64 encoded data) form in the output. With the 439patches29008, the Oracle Execute and Select Snaps display the ROWID columns in string form in the output (which can be used for other operations downstream).



Snap type:

Write


Examples:

Example 1: Stored procedure has output parameters firstNamelastName and both are of built-in type VARCHAR2.

The output document is:

Code Block
{
    firstName: "John",
    lastName: "Smith"
}

Example 2: Stored procedure has three output parameters firstName, lastName, and hobbies where firstName and lastName are of built-in type VARCHAR2 and hobbies is of custom type TABLE.

The output document is:

Code Block
{
    firstName: "John",
    lastName: "Smith",
    hobbies:[
                        "swimming",
                        "reading",
                        "joking"
                      ]
}

Example 3: Stored procedure has three output parameters firstName, lastName, and location where firstName and lastName are of built-in type VARCHAR2 and location is of custom type OBJECT.

The output document is:

Code Block
{
    firstName: "John",
    lastName: "Smith",
    location: {
                        "ADDRESS":"1520 8th Ave N",
                        "CITY":"San Mateo",
                        "STATE":"CA"
                      }
}

Example 4: Stored function accepts a customerId (NUMBER) and returns the customer's name (VARCHAR2).
The output document is:

{

   "returnval": "Acme Corporation"

}


Note
The attribute names of OBJECT are not displayed with the default JDBC driver.  With a custom JDBC driver, they are displayed as Field1, Field2, Field3, etc.


Warning

User-defined types are only supported with a specific version of the JDBC driver. Refer to the JDBC Driver setting in Oracle Account.


Info

There is a limitation in Oracle JDBC driver that prevents the passing of a record type parameters to the stored procedure. Refer the link: http://docs.oracle.com/cd/E11882_01/java.112/e16548/apxref.htm#JJDBC28928

A workaround could be to write a wrapper stored procedure to avoid passing of record type parameter directly to the original stored procedure.


Known Issues
Insert excerpt
Oracle Thin Account
Oracle Thin Account
nameOracle_KI_Custom_JAR
nopaneltrue
Support for Ultra pipelinesWorks in Ultra Tasks.
Account: 

This Snap uses account references created on the Accounts page of SnapLogic Manager to handle access to this endpoint.  See Oracle Account for information on setting up this type of account.


Views:


Input

This Snap allows none or one input view. If an input view is defined, then values from an incoming document can be used as input parameters to the stored procedure.
 
Note: The attribute names of custom type OBJECT are case-sensitive. For example, for custom type LOCATION with three fields ADDRESS, CITY and STATE, the input below is acceptable:
    location: 

Code Block
{
                            "ADDRESS":"1520 8th Ave N",
                            "CITY":"San Mateo",
                            "STATE":"CA"
                          }
But the input below won't be accepted:
    location: {
                             "address":"1520 8th Ave N",
                            "city":"San Mateo",
                            "state":"CA"
                          }


OutputThis Snap has exactly two document output views, Output Parameters and Result Set.
Error

This Snap has at most one error view and produces zero or more documents in the view.


Settings

Label


Required. The name for the Snap. You can modify this to be more specific, especially if you have more than one of the same Snap in your pipeline.

Schema Name

Specify the database schema name. The suggestions in the Schema field are populated only when at least a single table exists in the schema. If no tables exist to use that schema, only SYS, SYSTEM, and XDB are populated.

You can pass the values as expressions using the pipeline parameters but cannot use values from the upstream Snap.

Default value: None



Example: SYS

Package name


The package name where the procedure resides.  The property is suggestible and will return all packages of the DB. If a schema is defined, then it will only return the packages of that schema. 
Example: PACKAGE2

To invoke stored functions in a package, you need to upgrade the Oracle JDBC driver to 12.1.0.2 or later.

Note

User-defined types are supported only with a specific version of the JDBC driver. Refer to the JDBC Driver setting in Oracle Thin Account.


Stored Procedure Name

Required. Stored procedure to execute. The property is suggestible and will return all procedures of the DB. If a package is defined, then it will only return the procedures of that package. If a schema is defined and no package is defined, then it will return all procedures of that schema.

ExampleaddSeventeen
Default value: [None] 

Procedure sequence


Required for overloaded procedures. Sequence number that indicates the procedure to be used for overloaded procedures. The property is optional and only to be used when the selected procedure is overloaded. The starting index is always 1. The property is suggestible and will return the available indexes of the overloaded procedure, if any. The procedure sequence instructions apply similarly to stored functions.

Example:

  • A procedure sp1 exists in a package pkg1 as sp1 (arg1, arg2) and sp1 (arg1, arg2, arg3), then the sequence number defines which procedure is used. Sequence number 1 uses sp1 (arg1, arg2) and sequence number 2 uses sp1 (arg1, arg2, arg3)
  • A function f1 exists in a package pkg1 as f1 (arg1, arg2) and f1 (arg1, arg2, arg3), then the sequence number defines which function is used. Sequence number 1 uses f1 (arg1, arg2) and sequence number 2 uses f1 (arg1, arg2, arg3).
Ignore Null Parameters


Excerpt

Select this check box to enable the Snap to ignore the parameters evaluated as null. This applies to parameters with defined default values.

Default value: Not selected


Parameter Values


Select the input parameter values for the stored procedure. If you define parameter values, you must do so in the same order as they appear in the stored procedure definition.

Example: There is a stored procedure named createGreeting. It has two input parameters: p1 and p2 of type VARCHAR2. Then you need to provide two string values. The first value goes to p1 and the second value goes to p2.

Default value: [None]

Note

Quotation marks should not be used when setting input parameters unless they are part of the input value itself, since they are treated as escaped plain characters. For example, if the desired input value is TEST_VALUE1, the input parameter should be set as TEST_VALUE1, if you set it as "TEST_VALUE1", it will be recognized as \"TEST_VALUE1\".


Info

If you do not provide any parameters in the Snap, you can still view the required input parameters in the Target Schema of the upstream Mapper Snap. The parameters are dynamically populated based on the column keys of the stored procedure; you can map the parameters and pass them as an input to the Stored Procedure Snap.


Pass through


If selected, the input document will be passed through to the output views under the key 'original'. The document will be passed to the Parameter output view, and it will also be passed to the Result Set output view if there is output sent from this view.

Note
This property applies only to the Execute Snaps with SELECT statement or the Select Snaps. 

Default value: Not selected 


Custom type parameters mapping

optional

Supports mappings for all parameters. 

       Parameter index

The index is of the custom type parameter.  It is suggestible based on stored procedure name.

Note
  • The first parameter's index is 1 for stored procedures. 
  • The first parameter's index is 2 for stored functions. 
  • The return value has index 1 for stored functions.


        Parameter type

The custom type name the parameter is of.  Its suggestible based on database account.


Multiexcerpt include macro
nameSnap Execution
pageSOAP Execute


Multiexcerpt include macro
nameExecution_Detail_Write
pageSOAP Execute

Examples


We will provide two examples, the first one calls a simple stored procedure, the second one calls a procedure with user-defined type parameters.


Expand
title1. Calling a simple Stored Procedure

In this example we want to call stored procedure TEST_PROC.


Here is the definition of stored procedure TEST_PROC:

Code Block
CREATE OR REPLACE PROCEDURE TEST_PROC 
(
    in_sbset_id         IN  NUMBER
    ,test_date          IN  DATE
    ,test_timestamp     IN  TIMESTAMP
    ,test_timestamptz   IN  TIMESTAMP WITH TIME ZONE
    ,test_timestampltz  IN  TIMESTAMP WITH LOCAL TIME ZONE
    ,out_result         OUT VARCHAR2
)

AS
    l_sql_statement VARCHAR(4000);

BEGIN
    DBMS_OUTPUT.PUT_LINE('Started');
    DBMS_OUTPUT.PUT_LINE('test_date : ' || test_date);
    DBMS_OUTPUT.PUT_LINE('test_timestamp : ' || test_timestamp);
    DBMS_OUTPUT.PUT_LINE('test_timestamptz : ' || test_timestamptz);
    DBMS_OUTPUT.PUT_LINE('test_timestampltz : ' || test_timestampltz);
    l_sql_statement := 'INSERT INTO TEST_TABLE VALUES (
                           '||in_sbset_id||',
                           TO_DATE('''||test_date||''',''DD-MON-YYYY'') ,
                           TO_TIMESTAMP('''||test_timestamp||''') ,
                           TO_TIMESTAMP_TZ('''||test_timestamptz||''') ,
                           CAST('''||test_timestampltz||''' AS TIMESTAMP WITH LOCAL TIME ZONE))';
    COMMIT;
        
    DBMS_OUTPUT.PUT_LINE('l_sql_statement ::  '||l_sql_statement);
    EXECUTE IMMEDIATE l_sql_statement;
    COMMIT;

    DBMS_OUTPUT.PUT_LINE('Completed');
    out_result := 'SUCCESSFUL';
END TEST_PROC;

 First, we use an Oracle Execute Snap, to get some input data from table TEST_TABLE.

Then, we use a Mapper Snap to map the data from the Oracle - Execute Snap to the Target paths, which the Oracle Stored Procedure Snap uses later.

In the Oracle Stored Procedure Snap, we define the stored procedure and parameters.

Upon validation, we see the output preview of the Oracle Stored Procedure Snap as shown below:



Expand
title2. Oracle Stored Procedure with user-defined parameters

In this example we will call a Oracle Stored Procedure PROC_WITH_CUSTOM_IN_PARAM which has parameters of user-defined types.

Here is the definition of the stored procedure PROC_WITH_CUSTOM_IN_PARAM:

Code Block
CREATE OR REPLACE PROCEDURE PROC_WITH_CUSTOM_IN_PARAM
(
    pPairsCount     IN  NUMBER
    ,pPrefix        IN  VARCHAR2
    ,pINMUIDS       IN  STRARRAY32
    ,pMUIDs         OUT STRARRAY32
    ,pAuthKeys      OUT STRARRAY49
    ,pDemoPeriod    OUT NUMBER
    ,pTransID       OUT NUMBER
    ,pErrorCd       OUT NUMBER
    ,pErrorMsg      OUT VARCHAR2
)

AS BEGIN
    select COUNT('s') Into pTransID from ACTRESS a;
    pMUIDs := STRARRAY32();
    pMUIDs.EXTEND(1);
    pAuthKeys := STRARRAY49();
    pAuthKeys.EXTEND(1);
    pMUIDs(1) := inMUIDS(1);
    pAuthKeys(1) := 'ABCD-r2mi-7vax-xn3m-hahj-2bqa-ev6f-dn3r-225x-ABCD';
    pErrorCd := 0;

    EXCEPTION 
    WHEN OTHERS THEN
        pErrorCd := 1;
        pErrorMsg := 'Some Error Happened.';

END PROC_WITH_CUSTOM_IN_PARAM;

First we use a JSON Generator Snap to pass parameter values as shown below to the Stored Procedure Snap:

Then we use the Stored Procedure Snap procedure name and define parameter values. As there are several parameters that are user-defined types, we add custom type mapping for them. Each mapping row consists of parameter index and type. Parameter index is the index when it is defined, and the parameter type is the name of the user-defined type. You can also use the Suggest button to get the list of available indices or types and select the needed one.

Upon validation, we see the output preview of the Oracle - Stored Procedure Snap as shown below:



Expand
title3. Calling a simple stored function with custom type mapping

This Pipeline demonstrates invoking a stored function using the Oracle Stored Procedure Snap by defining a custom type mapping and documenting the indexing behavior. The return value has index 1 and the first parameter has index 2.

The code in the following section defines the stored function - payroll_pkg.employee_info.

Paste code macro
CREATE TABLE employee (

id NUMBER(6),
title VARCHAR2(128),
salary NUMBER(8,2),
hire_date DATE,
constraint pk_employee primary key (id)

);

CREATE TABLE people(

id NUMBER(6),
first_name VARCHAR2(128),
last_name VARCHAR2(128),
employee_id NUMBER(6),
constraint pk_people primary key (id),
foreign key (employee_id) references employee(id)

);

CREATE OR REPLACE TYPE employee_t IS OBJECT(

title VARCHAR2(128),
salary NUMBER(8,2),
hire_date DATE

);
/

CREATE OR REPLACE TYPE employee_tbl IS TABLE OF employee_t;
/

CREATE OR REPLACE PACKAGE payroll_pkg AS

FUNCTION employee_info(employee_id IN NUMBER) RETURN employee_tbl;

END payroll_pkg; 
/

CREATE OR REPLACE PACKAGE BODY payroll_pkg AS

FUNCTION employee_info(employee_id IN NUMBER)

RETURN employee_tbl
AS
   l_employee_tbl employee_tbl := employee_tbl();
BEGIN
  SELECT employee_t(e.title, e.salary, e.hire_date)
    BULK COLLECT INTO l_employee_tbl
   FROM employee e 
WHERE e.id = employee_id;

return l_employee_tbl;
END employee_info;

END payroll_pkg;
/

-- seed data
INSERT INTO employee VALUES (100, 'manager', 50000, TO_DATE('2020-01-02', 'YYYY-MM-DD')); 
INSERT INTO employee VALUES (200, 'clerk', 12345, TO_DATE('2018-10-17', 'YYYY-MM-DD'));

INSERT INTO people VALUES (1, 'Mary', 'Weller', 100);
INSERT INTO people VALUES (2, 'Frank', 'Smith', 200);


We use the Oracle Execute Snap to query people table.

Then, we use the Mapper Snap to map Employee ID and Full name.

We use the Oracle - Stored Procedure Snap and select the stored procedure.

The Oracle Stored Procedure Snap invokes a stored function to lookup employee information, such as the employee's salary and hire date. The function accepts an Employee ID and returns a table of custom types (employee).

Downloads

Multiexcerpt include macro
namedownload_instructions
pageOpenAPI

Attachments
patterns*.slp, *.zip

Insert excerpt
Oracle Snap Pack
Oracle Snap Pack
nopaneltrue