SQL Stored Procedure Samples
-----------------------------
1 SQL stored procedure sample file purpose
2 How to create a SQL stored procedure
3 How to call a SQL stored procedure

1 SQL stored procedure sample file purpose
---------------------------------------
1.1 Sample inputparam.sp
    This sample is mainly used for demonstrating SQL stored procedure's input 
    parameter, output parameter, data type, assignment statement, expression, 
    and database built-in function.
    This SQL stored procedure's main function is to receive all types of input
    data by input parameter, and process these input data, then insert them 
    into table sqlsp_alltype.
    For more information, see the file inputparam.sp.
    
1.2 Sample outputparam.sp
    This sample is mainly used for demonstrating SQL stored procedure's output 
    parameter.
    This SQL stored procedure's main function is to retrieve the first row from
    the table sqlsp_alltype, and return it to caller by output parameters.
    For more information, please see the file outputparam.sp.

1.3 Sample resultset.sp
    This sample is mainly used for demonstrating how a SQL stored procedure
    return a result set to caller.
    This SQL stored procedure's main function is to retrieve the first nTOP 
    rows from the table sqlsp_alltype and return a result set to caller.
    For more information, please see the file resultset.sp.
    
1.4 Sample loopif.sp
    This sample is mainly used for demonstrating IF statement, LOOP statement,
    and CONTINUE HANDLER statement.
    This SQL stored procedure's main function is to retrieve all grade data of 
    a course according to inputted course id(cid) from the grade table sqlsp_grade,
    then calculate the number of each level of A,B,C respectively.
    For more information, please see the file loopif.sp.
    
1.5 Sample whilecase.sp
    This sample is mainly used for demonstrating WHILE statement and CASE 
    statement.
    This SQL stored procedure's main function is to retrieve all grade data of 
    a course according to inputted course id(cid) from the grade table sqlsp_grade,
    then calculate the number of each level of A,B,C respectively.
    For more information, please see the file whilecase.sp.

1.6 Sample forcase.sp
    This sample is mainly used for demonstrating FOR statement and CASE 
    statement.
    This SQL stored procedure's main function is to retrieve all grade data of 
    a course according to inputted course id(cid) from the grade table sqlsp_grade,
    then calculate the number of each level of A,B,C respectively.
    For more information, please see the file forcase.sp.

1.7 Sample dynamic1.sp
    This sample is mainly used for demonstrating DYNAMIC SQL, including
    EXECUTE IMMEDIATE statement, PREPARE statement, EXECUTE statement,
    and DEALLOCATE PREPARE statement. 
    The usage of EXECUTE statement will be divided into the following three cases: 
    - has no input parameter, no return value. 
    - has input parameter, no return value. 
    - has input parameter and return value.
    This SQL stored procedure's main function is to delete all tuples from 
    table sqlsp_t1, and insert some rows into table sqlsp_t1 with dynamic SQL,
    finally, return the count of inserted rows.
    For more information, please see the file dynamic1.sp.

1.8 Sample dynamic2.sp
    This sample is mainly used for demonstrating DYNAMIC CURSOR, including 2 
    cases: to process data with dynamic cursor, and to return a result set with
    dynamic cursor.
    This SQL stored procedure's main function is to calculate the average of
    column C1 and the sum of column C1 respectively, finally return all tuples
    from sqlsp_t1;
    For more information, please see the file dynamic2.sp.

1.9 Sample dynamic3.sp
    This sample is a simple application of DYNAMIC SQL.
    This SQL stored procedure will delete all tables matched table name pattern
    and schema name pattern given by caller.
    For more information, please see the file dynamic3.sp.

1.10 Sample nest1.sp, nest2.ec, nest3.sp
    These 3 samples are mainly used for demonstrating NEST CALL between a SQL
    stored procedure and an ESQL/C stored procedure. The SQLSP_NEST3 will call 
    ESQLSP_NEST2, and the ESQLSP_NEST2 will call SQLSP_NEST1.
    It is the same function of these 3 stored procedures to query the student
    name(sname) by student ID(sid).
    For more information, please see the file nest1.sp, nest2.ec and nest3.sp.

1.11 Sample updateonduty.sp, doorcardtrigger.sql
    These 2 samples are mainly used for demonstrating the SQL stored procedure 
    is called by trigger.
    The file updateonduty.sp will create a SQL stored procedure 
    SQLSP_UPDATEONDUTY which will update the table sqlsp_DoorCardOnDuty.
    The file doorcardtrigger.sql is a SQL script that will create a trigger on 
    the table sqlsp_DoorCard.
    For more information, please see the file updateonduty.sp and doorcardtrigger.sql.

1.12 Sample callsqlsp.cs
    This sample demonstrates how a C# program call a SQL stored procedure.
    For more information, please see the file callsqlsp.cs.
    
1.13 Sample CallSqlSp.java
    This sample demonstrates how a java program call a SQL stored procedure.
    For more information, please see the file CallSqlSp.java.
    
1.14 Sample createtable.sql
    This SQL script will prepare all tables and data for above-mentioned SQL stored 
    procedure samples.

2 How to create a SQL stored procedure
---------------------------------------
2.1 The basic steps to create SQL stored procedure
    (1) Write a SQL stored procedure with any text editor, save it as a file with
        .sp extension normally.
    (2) Before creating it, you can configure some keywords in dmconfig.ini optionally.
        DB_FODIR: the path of system file objects. The SQL stored procedure
                  source file will be saved into this directory.
        DB_SPDIR: the path of stored procedures. The SQL stored procedure 
                  object files and intermediate files generated during creation
                  will be put into this directory.
        DB_SPLOG: the path of stored procedure logs. The error message file 
                  generated during creation and the trace log file printed by 
                  TRACE statement will be in this directory.
    (3) Create a SQL stored procedure with the dmSQL or the JDBA tool.

2.2 The example to create SQL stored procedure with dmSQL
    We'll take the file loopif.sp as an example to describe the details
    of creating SQL stored procedure.
    The file loopif.sp will create a SQL stored procedure called SQLSP_LOOPIF.
    for more information about SQLSP_LOOPIF, please see the file loopif.sp.
    
    (1) Windows platform 
        a) Start 'DBMaker Server' from 'DBMaker 5.4' program folder, select
           database 'DBSAMPLE5' and start it.
        b) Start 'dmSQL' from 'DBMaker 5.4' program folder.
        c) Execute the following commands to create SQL stored procedures in dmSQL:
             dmSQL> connect to "DBSAMPLE5" "SYSADM" "";
             dmSQL> run 'C:\DBMaker\5.4\samples\SQLSP\createtable.sql';
             dmSQL> create procedure from 'C:\DBMaker\5.4\samples\SQLSP\loopif.sp';
           Now, a SQL stored procedure named SQLSP_LOOPIF has been created.
        d) Execute the following command to test SQL stored procedures in dmSQL:
             dmSQL> CALL SQLSP_LOOPIF(1002,?,?,?);
    
    (2) Linux platform
        a) Execute the following command in terminal to start database 
           'DBSAMPLE5':
             /APP_HOME/bin/dmserver DBSAMPLE5 &
        b) Execute the following command in terminal to start dmsql:
             /APP_HOME/bin/dmsqlc
        c) Execute the following commands to create SQL stored procedures 
           in dmsqlc:
             dmSQL> connect to "DBSAMPLE5" "SYSADM" "";
             dmSQL> run '/APP_HOME/samples/SQLSP/createtable.sql';
             dmSQL> create procedure from '/APP_HOME/samples/SQLSP/loopif.sp';
           Now, a SQL stored procedure named SQLSP_LOOPIF has been created.
        d) Execute the following command to test SQL stored procedures in dmsqlc:
             dmSQL> CALL SQLSP_LOOPIF(1002,?,?,?);

2.3 The example to create SQL stored procedure with the JDBA tool
    We'll take the file loopif.sp as an example to describe the detail process
    of creating SQL stored procedure.
    The file loopif.sp will create a SQL stored procedure called SQLSP_LOOPIF.
    for more information about SQLSP_LOOPIF, please see the file loopif.sp.
    NOTE: Some tables will be referred by this SQL stored procedure, please
          prepare these tables in advance. For more information about tables,
          please see the file createtable.sql.

    (1) Windows platform
        a) Start 'DBMaker Server' from 'DBMaker 5.4' program folder, select
           database 'DBSAMPLE5' and start it .
        b) Start 'JDBATool' from 'DBMaker 5.4' program folder, and connect to
           the database 'DBSAMPLE5'.
        c) Create SQL stored procedure with the JDBA tool:
             Select DATABASE/STORED PROCEDURE in the left tree view, click 
             [CREATE] button in the right panel, to open the wizard to create
             stored procedure.
             Follow wizard, select language type: SQL, click [IMPORT] button
             to import the file C:\DBMaker\5.4\samples\SQLSP\loopif.sp, click
             [FINISH] button to complete creation.
           Now, a SQL stored procedure named SQLSP_LOOPIF has been created.
        d) Test SQL stored procedure in JDBATool:
             Select the SQL stored procedure SQLSP_LOOPIF, click [EXECUTE] 
             button, input related parameter value, such as 1002, click [OK].
           
    (2) Linux platform
        a) Execute the following command in terminal to start database 
           'DBSAMPLE5':
             /APP_HOME/bin/dmserver DBSAMPLE5 &
        b) Execute the following command in terminal to start JDBATool, and 
           connect to database 'DBSAMPLE5':
             /APP_HOME/bin/jdba
        c) Create SQL stored procedure with JDBATool:
             Select DATABASE/STORED PROCEDURE in the left tree view, click 
             [CREATE] button in the right panel, to open the wizard to create
             stored procedure.
             Follow wizard, select language type: SQL, click [IMPORT] button
             to import the file /APP_HOME/samples/SQLSP/loopif.sp, 
             click [FINISH] button to complete creation.
           Now, a SQL stored procedure named SQLSP_LOOPIF has been created.
        d) Test SQL stored procedure in JDBATool:
             Select the SQL stored procedure SQLSP_LOOPIF, click [EXECUTE] 
             button, input related parameter value, such as 1002, click [OK].

  NOTE:
    The sample nest2.ec is an ESQL/C stored procedure. Creating ESQL/C stored
    procedures is similar to creating SQL stored procedures, we can execute the
    following command to create an ESQL/C stored procedure in dmSQL tool:
      dmSQL> create procedure from 'C:\DBMaker\5.4\samples\SQLSP\test2.ec';
    Nevertheless, it is necessary for creating an ESQL/C stored procedure to 
    specify C compiler when installing DBMaker.

3 How to call a SQL stored procedure
  Like the stored procedure created by ESQL/C or JAVA, the SQL stored procedure 
  can be called directly by client tool, programs, stored procedures and triggers.
---------------------------------------
    
3.1 The syntax of calling SQL stored procedure
      CALL procedure-name[parameter-list]; 
    or
      EXECUTE PROCEDURE procedure-name[parameter-list]; 
    NOTE:
      When calling a stored procedure, for input parameter, we can make the 
      literal value or the binding variable as the actual parameter. For output 
      parameter, we only can make the binding variable as the actual parameter to 
      retrieve output value.

3.2 The example to call a SQL stored procedure in dmsql client tool
    Following is the command to call SQL stored procedure SQLSP_NEST3: 
      dmSQL> CALL SQLSP_NEST3(1,?);
      
    Or:
    
      dmSQL> CALL SQLSP_NEST3(?,?);
      dmSQL> 1;
      dmSQL> 2;
      dmSQL> 3;
      dmSQL> END;
    
    NOTE:
      '?' is the parameter placeholder.
      About the 2nd method, SQLSP_NEST3 will be called 3 times, 
      the value 1,2,3 is inputted.
      For output parameter, the placeholder must be used. Dmsql will 
      automatically allocate enough buffer to retrieve output value.

3.3 The example to call SQL stored procedures in C# programs
    Please refer to the sample callsqlsp.cs.

3.4 The example to call SQL stored procedures in JAVA programs
    Please refer to the sample CallSqlSp.java.

3.5 The example to call SQL stored procedures in stored procedures
    Please refer to the samples nest1.sp, nest2.ec, nest3.sp.

3.6 The example to call SQL stored procedures in triggers
    Please refer to the samples updateonduty.sp, doorcardtrigger.sql.
    NOTE: The stored procedure called by a trigger can not return any value.
