Generay speaking, a procedure is a routine that can accept arguments but does not return any values. A function is a routine that can accept arguments and returns one or more values. Axional Ax library support calling either database procedures or functions.

Return Method
JSResultSet executeFunction(String sql, Object ...args)
JSResultSet executeFunction(String sql, Function<Integer,String> columnNameMap, Object ...args)
Map<String, Object> executeFunctionWithParameters(String sql, Consumer<FunctionCallConfigurator> columnNameMap)
JSResultSet executeProcedure(String sql, Object ...args)
JSResultSet executeProcedure(String sql, Function<Integer,String> columnNameMap, Object ...args)

1 Calling functions

1.1 Functions

Most databases support SPL functions. SPL functions are UDRs (user defined routines) that in most of database engines return a single value. To write and register an SPL function, use a CREATE FUNCTION statement.

Informix database can return multiple values from a function like if it were a procedure.

1.1.1 Single value

The simpliest data that can be returned in a SPL function is a basic type value.

Copy
-- Return number of rows from specified table
CREATE FUNCTION IF NOT EXISTS test_function1(p_tabname VARCHAR(30))
    RETURNING INTEGER;
   
    DEFINE m_tabrows INTEGER; 

    SELECT nrows 
      INTO m_tabrows 
      FROM systables
     WHERE tabname = p_tabname;

  RETURN m_tabrows;
END FUNCTION
Copy
-- Return number of rows from specified table
CREATE OR REPLACE FUNCTION test_function1(p_tabname VARCHAR2)
RETURN INTEGER
AS
  m_tabrows integer;
BEGIN    
   m_tabrows := 0;
   BEGIN
      SELECT table_name, num_rows
        INTO m_tabname, m_tabrows
        FROM all_tables
      WHERE table_name = p_tabname
        AND owner = (SELECT sys_context('userenv','current_schema') FROM dual);

      EXCEPTION WHEN NO_DATA_FOUND THEN NULL;
    END;

  RETURN m_tabrows;
END;
/
Copy
-- Return number of rows from specified table
CREATE OR REPLACE FUNCTION test_function1(tablename text)
  RETURNS INTEGER
AS $$
DECLARE
    tabrows INTEGER;
BEGIN
    tablename := 'public.' || tablename;

    EXECUTE format('SELECT count(1) FROM %s', tablename)
    INTO tabrows;

    return tabrows;
END
$$ LANGUAGE 'plpgsql';

Let's see how to execute it (enter a table name that exists in the database):

Copy
<script>
var nrows = Ax.db.executeFunction("test_function1", "systables");
console.log(nrows);

nrows = Ax.db.executeFunction("test_function1", "systables");
console.log(nrows.toOne()["(expression)"]);

nrows = Ax.db.executeFunction("test_function1", "systables");
console.log(nrows.toValue());
</script>
+------------+
|(expression)|
|int         |
+------------+
|         683|
+------------+

683

683

1.1.2 Single row values

A SPL function can return more than one value from a single row of a table. The following example shows an SPL function that returns two column values from a single row of a table.

Copy
-- Return tabid and number of rows from specified table
DROP FUNCTION IF EXISTS test_function1;

CREATE FUNCTION IF NOT EXISTS test_function1(p_tabname VARCHAR(30))
    RETURNING ROW(a int, b int);
   
    DEFINE m_tabid   INTEGER; 
    DEFINE m_tabrows INTEGER; 

    SELECT tabid, nrows 
      INTO m_tabid, m_tabrows 
      FROM systables
     WHERE tabname = p_tabname;

  RETURN ROW(m_tabid, m_tabrows);
END FUNCTION;
Copy
CREATE OR REPLACE TYPE test_type_record AS OBJECT
( tabname       VARCHAR2(30),
  tabrows       INTEGER
);
/

-- Return table name and number of rows from specified table
CREATE OR REPLACE FUNCTION test_function_return_record(p_tabname VARCHAR2)
RETURN test_type_record
AS
  m_tabname varchar2(30);
  m_tabrows integer;
  var_record test_type_record;
BEGIN    
   m_tabname := p_tabname;
   m_tabrows := 0;
   var_record := test_type_record(m_tabname,m_tabrows);
   BEGIN

      SELECT table_name, num_rows 
        INTO m_tabname, m_tabrows
        FROM all_tables 
      WHERE table_name = p_tabname
        AND owner = (SELECT sys_context('userenv','current_schema') FROM dual);
      EXCEPTION WHEN NO_DATA_FOUND THEN NULL;
    END;

  var_record.tabname := m_tabname;
  var_record.tabrows := m_tabrows;
  RETURN (var_record);
END;
/
Copy
CREATE TYPE test_function1_return_type AS
( tabname       TEXT,
  tabrows       INTEGER
);

-- Return table name and number of rows from specified table
CREATE OR REPLACE FUNCTION test_function1(tablename text)
  RETURNS  test_function1_return_type
AS $$
DECLARE
    result_record test_function1_return_type;
BEGIN
    tablename := 'public.' || tablename;
    result_record.tabname := tablename;

    EXECUTE format('SELECT count(1) FROM %s', tablename)
    INTO result_record.tabrows;

    return result_record;
END
$$ LANGUAGE 'plpgsql';

Let's see how to execute it (enter a table name that exists in the database):

Copy
<script>
    var rs = Ax.db.executeFunction("test_function1", "systables");
    var row = rs.toOne() 
    console.log(row);
    console.log(row["(expression)"][0]);
    console.log(row["(expression)"][1]);
</script>
{(expression)=[1, 103]}
1
103

In previous example, default column name "(expression)" is asigned to parameter returned. You can change the name of returned values from an executeFunction call, by passing a mapping function as second parameter :

Copy
<script>
    var rs = Ax.db.executeFunction("test_function1", columnIndex => {
        switch (columnIndex) {
            case 1: return "rowtype";
            default: return "undefined";        
        }
    }, "systables").toOne();
    console.log(rs["rowtype"][0]);
    console.log(rs["rowtype"][1]);
</script>
1
103

1.1.3 Multiple rows

The following example is an SPL function that returns more than one row.

Copy
-- Return system tables with more than specific number of rows
CREATE FUNCTION IF NOT EXISTS test_function2()
   RETURNING ROW(color VARCHAR(30), val INTEGER);
   
   RETURN ROW('Red',   10) WITH RESUME;
   RETURN ROW('Green', 20) WITH RESUME;
   RETURN ROW('Blue',  30) WITH RESUME;
END FUNCTION
Copy
CREATE OR REPLACE FUNCTION test_function_cursor2(p_numrows INTEGER)
RETURN SYS_REFCURSOR
AS
  var_cursor SYS_REFCURSOR;
BEGIN    

   BEGIN
      OPEN var_cursor FOR
      SELECT table_name, num_rows 
        FROM all_tables 
      WHERE num_rows >p_numrows
        AND owner = (SELECT sys_context('userenv','current_schema') FROM dual);
      EXCEPTION WHEN NO_DATA_FOUND THEN NULL;
    END;
  RETURN (var_cursor);
END;
/

Let's see how to execute it:

Copy
<script>
    var rs = Ax.db.executeFunction("test_function2");
    for (var row of rs) {
        console.log(row);
    }
</script>
+------------+
|(expression)|
+------------+
|[Red, 10]   |
|[Green, 20] |
|[Blue, 30]  |
+------------+

1.1.4 Passing multiple arguments

In the previous examples we have been using a function receiving only one value as input parameter.

You can pass multiple arguments (varargs) to a function that will be passed in same order to the correspoding function arguments. The following example is a simple echo function that returns values passed as arguments.

Copy
CREATE FUNCTION IF NOT EXISTS test_function3
    (p_int INTEGER, p_float FLOAT, p_dec DECIMAL(14, 6), p_date DATE, p_char CHAR(20))
    RETURNING ROW(r_int INTEGER, r_float FLOAT, r_dec DECIMAL(14, 6), r_date DATE, r_char CHAR(20));

    RETURN  ROW(p_int, p_float, p_dec, p_date, p_char);
END FUNCTION
Copy
<script>
   Ax.db.execute(`DROP FUNCTION IF EXISTS test_function3`);
   Ax.db.execute(`
CREATE FUNCTION IF NOT EXISTS test_function3
    (p_int INTEGER, p_float FLOAT, p_dec DECIMAL(14, 6), p_date DATE, p_char CHAR(20))
    RETURNING ROW(r_int INTEGER, r_float FLOAT, r_dec DECIMAL(14, 6), r_date DATE, r_char CHAR(20));

    RETURN  ROW(p_int, p_float, p_dec, p_date, p_char);
END FUNCTION  
`);
    var rs = Ax.db.executeFunction("test_function3", 1, 1.234, 1.23456, new Date(), "Hello");
    console.log(rs);
</script>
+------------------------------------------------------------+
|(expression)                                                |
+------------------------------------------------------------+
|[1, 1.234, 1.234560, 2019-03-25, Hello               ]      |
+------------------------------------------------------------+

1.2 Fetching a single value of type row

From previous examples we can see all data returned is a ResultSet as we any function may return one or multiple rows. You need to iterate the ResultSet to fetch firs row and so on. This can be tedious when we are processing only one row

When application knows a function will return only one value, it can transform the ResultSet into a JSON object to simplify data processing.

Copy
<script>
    var rs = Ax.db.executeFunction("test_function3", columnIndex => {
        switch (columnIndex) {
            case 1: return "rowtype";
            default: return "undefined";        
        }
    },
    // arguments
    1, 1.234, 1.23456, new Date(), "Hello"
    );
    var row = rs.toOne();
    console.log(row);
    console.log(row.rowtype);
    console.log(row.rowtype[0] + ", " + row.rowtype[1] + ", " + row.rowtype[2]);
</script>
{rowtype=[1, 1.234, 1.234560, 2019-03-25, Hello               ]}
[[1, 1.234, 1.234560, 2019-03-25, Hello               ]]
1, 1.234, 1.234560

  • If ResultSet returns no rows, a JSON object with columns set to null values is returned.
  • If ResultSet retutrns more than one row an SQLException will be thrown as only one row is expected.
  • Calling toOne() function with (argument required="message") will make function throws SQLException(message) if no row is found.

2 Calling Procedures

SPL procedures are UDRs written in Stored Procedure Language (SPL) that do not return a value. To write and register an SPL routine, use the CREATE PROCEDURE statement.

In general a procedure is a routine that can accept arguments but does not return any values. Even so, many database agents allow procedures return values (for example Informix).

2.1 No return

You can call a procedure not returning any values by executing Ax.db.executeProcedure. First argument is the name of the procedure you want to execute followed by parameter values you want to pass to procedure in same order it were declared in the procedure signature.

If the procedure doesn't return any parameter, execution of Ax.db.executeProcedure returns a null value.

Copy
-- Creates a temporary table with the number of rows from specified table
CREATE PROCEDURE IF NOT EXISTS test_procedure1(p_tabname VARCHAR(30))
    DROP TABLE IF EXISTS t_tmp_1;

    SELECT tabname, nrows
      FROM systables
     WHERE tabname = p_tabname
     INTO TEMP t_tmp_1  WITH NO LOG;
END PROCEDURE;
Copy
-- Creates a temporary table with the number of rows from specified table
CREATE OR REPLACE PROCEDURE test_procedure1(p_tabname VARCHAR2)
AS
    table_or_view_not_exist exception;
    pragma exception_init(table_or_view_not_exist, -942);
    attempted_ddl_on_in_use_GTT exception;
    pragma exception_init(attempted_ddl_on_in_use_GTT, -14452);

    m_sql  VARCHAR2(32767);
    m_new INTEGER;
begin

    DBMS_OUTPUT.PUT_LINE('Starts test_procedure1');

    BEGIN
        EXECUTE IMMEDIATE 'drop table t_tmp_1';

        EXCEPTION 
            WHEN table_or_view_not_exist THEN
              DBMS_OUTPUT.PUT_LINE('Table t_tmp_1 does not exists');
            WHEN attempted_ddl_on_in_use_GTT THEN
              DBMS_OUTPUT.PUT_LINE('Table t_tmp_1 is in use (truncate)');
              EXECUTE IMMEDIATE 'TRUNCATE table t_tmp_1';
              EXECUTE IMMEDIATE 'drop table t_tmp_1';
    END;          

      DBMS_OUTPUT.PUT_LINE('Create table t_tmp_1');

      m_sql := 'CREATE GLOBAL TEMPORARY TABLE t_tmp_1 ON COMMIT PRESERVE ROWS AS 
             SELECT table_name, num_rows 
               FROM all_tables 
              WHERE owner = (SELECT sys_context(''userenv'',''current_schema'') FROM dual)
                AND table_name = '''||p_tabname||''' ';
    EXECUTE IMMEDIATE m_sql;

END;
/

Let's see how to execute it (enter a table name that exists in the database):

Copy
<script>
    Ax.db.execute(`
CREATE PROCEDURE IF NOT EXISTS test_procedure1(p_tabname VARCHAR(30))
    DROP TABLE IF EXISTS t_tmp_1;

    SELECT tabname, nrows
      FROM systables
     WHERE tabname = p_tabname
     INTO TEMP t_tmp_1  WITH NO LOG;
END PROCEDURE;
    `);
    
    console.log("Execute returns: " + Ax.db.executeProcedure("test_procedure1", "systables"));
    console.log("========================================");
    console.log(Ax.db.executeQuery("select * from t_tmp_1"));
</script>
Execute returns: null
========================================
+----------------------------------------+----------------+
|tabname                                 |nrows           |
+----------------------------------------+----------------+
|systables                               |           103.0|
+----------------------------------------+----------------+

2.2 Single return parameter

When calling a procedure, doesn't matter if it returns a single or multiple parameters, it always returns a resultset with parameters returned as columns.

Usually a procedure returns a single row, so you can use toOne() method to avoid resultset iteration.

Copy
CREATE PROCEDURE IF NOT EXISTS test_procedure2(value INTEGER)
    RETURNING INTEGER;
    IF value IS NULL THEN
        RETURN 1;
    ELSE
        RETURN 0;
    END IF
END PROCEDURE;

Let's see how to execute it:

Copy
<script>
    Ax.db.execute(`
CREATE PROCEDURE IF NOT EXISTS test_procedure2(value INTEGER)
    RETURNING INTEGER;
    IF value IS NULL THEN
        RETURN 1;
    ELSE
        RETURN 0;
    END IF
END PROCEDURE;

    `);
    
    var rs = Ax.db.executeProcedure("test_procedure2", 150);
    var data = rs.toOne()
    console.log("Result is: " + data["(expression)"]);
</script>
Result is: 0

2.3 Multiple return parameters

As explained in previous section, when using procedures, returning multiple parameters is similar than returning a single one. Result from procedure execution is a ResultSet with a single or multiple columns.

Lets see a simple procedure that returns multiple values (two) for a given input value and how to call it according specific engine.

Copy
DROP PROCEDURE IF  EXISTS test_procedure3;
CREATE PROCEDURE IF NOT EXISTS test_procedure3(value INTEGER)
    RETURNING INTEGER AS a, INTEGER AS b
    RETURN value * 2, value / 2;
END PROCEDURE;
Copy
Copy
<script>
    var rs = Ax.db.executeProcedure("test_procedure3", 6);
    
    for (var row of rs)
       console.log(row);
</script>
{a=12, b=3}

2.3.1 Column name mapping

From previous examples we may see that procedure has a named returned data, and this names are returned as part of resultset. But, if you don't name return parameters explicitly, database returns the same name for all columns: expression.

The problem is we will not be able to use a javascript object to fetch the data.

Let's try to fetch data getting every row as a JavaScript object (Map).

Copy
<script>
    Ax.db.execute(`CREATE PROCEDURE IF NOT EXISTS test_procedure4(value INTEGER)
    RETURNING INTEGER, INTEGER
    RETURN value * 2, value / 2;
END PROCEDURE;`);
    var rs = Ax.db.executeProcedure("test_procedure4", 6);

    for (var row of rs)
       console.log(row);
</script>
{(expression)=3}

We can see, first parameter is lost and we only get last value.

A solution is to use a column name mapper using JDBC columnIndex to return the desired column name corresponding to return variable ordinal.

Copy
<script>
    var rs = Ax.db.executeProcedure("test_procedure4", columnIndex => {
        switch (columnIndex) {
            case 1: return "p_mul";
            case 2: return "p_div";
            default: return "undefined";        
        }
    },
    // arguments
    6
    );
    console.log(rs);
</script>
+----------+----------+
|p_mul     |p_div     |
+----------+----------+
|        12|         3|
+----------+----------+

2.4 Multiple rows with multiple return params

Invoking calls to procedures returning multiple rows is similar to invoking a call returning a single row. A resultset is returned and you need to iterate it to get all rows returned.

Copy
<script>
    Ax.db.execute(`CREATE PROCEDURE IF NOT EXISTS test_procedure5(value INTEGER)
    RETURNING INTEGER AS multiplied, INTEGER AS divided
    RETURN value * 2, value / 2 WITH RESUME;
    RETURN value * 4, value / 4 WITH RESUME;
    RETURN value * 6, value / 6 WITH RESUME;
    RETURN value * 8, value / 8 WITH RESUME;
    RETURN value * 10, value / 10 WITH RESUME;
END PROCEDURE;`);
    var rs = Ax.db.executeProcedure("test_procedure5", 40);
    
    for (var row of rs)
       console.log(row);
</script>
{multiplied=80, divided=20}
{multiplied=160, divided=10}
{multiplied=240, divided=6}
{multiplied=320, divided=5}
{multiplied=400, divided=4}