Skip to content

APRE*C/C++ New Features & Upgrade Guide#

Overview#

This document explains the new features and changes of APRE*C/C++, as well as the procedure for upgrading from SESC to APRE.

The document is based on APRE*C/C++ for Altibase 7.3.

It is recommended to refer to the following technical documents to understand the contents of this document.

Info

For errors and improvements related to this document, please contact the technical support portal or technical support center.

Info

This document is provided for informational purposes only and is subject to change without prior notice. It may contain errors, and Altibase makes no express or implied warranties of any kind, including but not limited to warranties of merchantability or fitness for a particular purpose.

The development, release, and timing of any features or functionality described for Altibase products in this document are at the sole discretion of Altibase.

Altibase may hold patents, trademarks, copyrights, or other intellectual property rights related to the contents of this document.

APRE*C/C++#

This section describes Altibase's new Precompiler of Embedded SQL. Please refer to Altibase Precompiler Guide for specific details such as usage of the function as a summary form.

Terms#

Precompiler of Embedded SQL

The program that receives source code including embedded SQL and converts the embedded SQL into execution-time library function calls.

*SESC/C++

It is an abbreviation of the Precompiler of Embedded SQL for versions lower than Altibase 5.1.5, and supports C and C++ as source code.

*APREC/C++

It is an abbreviation of the Precompiler of Embedded SQL for versions lower than Altibase 5.3.3, and supports C and C++ as source code. Compared to SES*C/C++, the upgrade level function is improved.

Overview of New Features#

Many restrictions that existed in SES*C/C++ have been greatly improved.

The name was also changed to APRE*C/C++ (Altibase C/C++ Precompiler of Embedded SQL) while applying the upgrade.

The functions newly added to APRE*C/C++ are as follows:

  • Partial C Preprocessor for macro processing
  • C Parser for host variable declaration
  • Function to rewrite the library to alleviate host variable declaration method and usage restrictions
  • DECLARE STATEMENT statement support

In addition, the following improvements were made:

  • Function callable when using WHENEVER statement
  • APRE*C/C++ executable file (apre) command option has changed and added
  • the error message output type has changed
  • Supports the RETURNING INTO clause
  • The FREE statement is no longer supported; use the DISCONNECT statement instead

Details of New Features#

Equipped with Partial C Preprocessor

Most of the macros below can be processed without any restrictions on the declaration area.

#include, #define, #if, #ifdef, #ifndef, #endif, #else, #elif

 #define ALTIBASE
 ...
 EXEC SQL BEGIN DECLARE SECTION;
 ...
 EXEC SQL END DECLARE SECTION;

 EXEC SQL INSERT INTO T1 VALUES
 #ifdef ALTIBASE
 ( :altibase );
 #else
 ( :other_dbms );
 #endif
 ...

Equipped with C Parser

Only when the source code is written in C, the host variable declaration is possible outside the host variable declaration section (DECLARE SECTION).

 int i = 10;
 EXEC SQL BEGIN DECLARE SECTION;
 int j;
 int k;
 EXEC SQL END DECLARE SECTION;
 varchar vc[LEN];
 ...
 EXEC SQL INSERT INTO T1 VALUES (:i, :j, :k, :vc);

Host variable declaration method and ease of using restrictions

Many restrictions related to the use of host variables have been removed. Details are as follows.

  1. The initial value can be assigned at the same time as the host variable declaration

     EXEC SQL BEGIN DECLARE SECTION;
     int i = 10*10;
     char j[10] = "abcd"
     EXEC SQL END DECLARE SECTION;
    
  2. Structure definition available after typedef (reverse also available)

     EXEC SQL BEGIN DECLARE SECTION;
     typedef struct department department;
     struct department
     {
        short dno;
        char dname[30+1];
        dep_location[9+1];
    };
    EXEC SQL END DECLARE SECTION;
    
  3. Array elements can be specified when using array-type host variables in embedded SQL statements.

     EXEC SQL BEGIN DECLARE SECTION;
     struct tagl
     {
        int i1;
        int i2;
     } var1[10];
     EXEC SQL END DECLARE SECTION;
    
     EXEC SQL INSERT INTO T1(I1, I2) VALUES(:var1[0].i1, :var1[0].i2);
    
  4. Data types other than char * and struct * can be used as pointer type host variables.

     struct {
        int i;
        char c;
     } structvar;
     int *i_ptr = &structvar.i;
     char *c_ptr = &structvar.c;
     EXEC SQL SELECT I, C INTO :i_ptr, :c_ptr FROM TMP;
    
  5. The host variable for output can be used without ":" in INTO clause of the SELECT statement

     EXEC SQL BEGIN DECLARE SECTION;
     char name[10];
     EXEC SQL END DECLARE SECTION;
     EXEC SQL SELECT DEP_NAME INTO name FROM DEPT;
    
  6. Can be used even if the input host variable of the embedded SQL including the FOR clause is not an array type

     EXEC SQL BEGIN DECLARE SECTION;
     int cnt = 1;
     int var1 = 10;
     EXEC SQL END DECLARE SECTION;
     ...
     EXEC SQL FOR :cnt INSERT INTO T1 VALUES (:var1);
    
  7. The union type host variable can be used

     EXEC SQL BEGIN DECLARE SECTION;
     union uni {
     int a;
     char s[10];
     } u;
     EXEC SQL END DECLARE SECTION;
     ...
     EXEC SQL INSERT INTO T1 VALUES (:u.s);
    

Additional support for DECLARE STATEMENT

The DECLARE STATEMENT is supported as a standard embedded SQL statement.

Identifiers for SQL statements or PL/SQL blocks can be declared so that they can be used in other embedded SQL statements.

 EXEC SQL DECLARE my_statement STATEMENT;
 EXEC SQL DECLARE emp_cursore CURSOR FOR my_statement;
 EXEC SQL PREPARE my_statement FROM :my_string;

Function callable when using WHENEVER statement

This has been improved so that a specific function can be called when using the WHENEVER statement in the form of WHENEVER DO .

 EXEC SQL WHENEVER SQLERROR DO sql_error_occur();

*APREC/C++ executable file (apre) command option has been changed

  1. -I
    The name has been changed to -I as an option provided as -include option in the existing SES*C/C++.
    This specifies the path of the source code file included during precompiling.
    This option operates like EXEC SQL OPTION (INCLUDE=library_path) in code

     $ apre -t cpp -I$APP_HOME/include/main tmp.sc
    

*Command options added to the APREC/C++ executable (apre)

  1. -D
    Declares macros to be used during preprocessing. This option functions the same as #define within the code.

     $ apre –DALTIBASE –DOTHER_DBMS -t cpp tmp.sc
    
  2. -keyword
    This shows reserved keywords.

    $ apre -keyword
    

-parse parsing_mode

a. By specifying the parsing mode, the precompile range for the source file is determined.

b. The parsing mode and processing range of the -parse option are as follows.

c. If the -parse option itself is omitted, the parsing mode is operated as partial.

Parsing mode Internal SQL A Macro B External declaration part/
host variable
C
Remarks
none O X X Operates the same as SES*C/C++ #include format header file is not processed
partial O O X Additional operation of Partial C Preprocessor Process even header files in #include format APRE*C/C++ default parsing mode
full O O O Additional operation of C Parser Process even header files in #include format However, source code written in C++ style cannot recognize host variables outside the declaration section

In the case of [Processing up to #include type header file], even another header file declared as #include type in the corresponding header file is processed.

For example, after changing the query in the example above to an optional query using macros as shown below.

EXEC SQL select * into n from t1
#ifdef ALTIBASE
where i1=:i and i > 'A';
#else
where i1=:i;
#endif

When the parsing option is omitted and precompile with partial (the default parsing mode)

$ apre -t c main.sc

The actual created codes remain only in the stage that the macro processing is completed as follows. (After the macro processing, the removed part is replaced with a blank space).

...
/*  select * from       t1

where i1=:i and il> 'A'; */
{
    struct ulpSqlstmt ulpSqlstmt;
    ulpHostVar ulpHostVar[2];
    ulpSqlstmt.hostvalue = ulpHostVar;
    ulpSqlstmt.stmttype = 4;
    ulpSqlstmt.stmtname = NULL;
    ulpSqlstmt.ismt = 0;
...

If -parse none is specified to precompile in the same way as the existing SES*C/C++, a variable duplicate declaration error occurs because the macro processing function does not operate.

 $ apre -t c -parse none main.sc
 -----------------------------------------------------------------
    Altibase C/C++ Precompiler.
     Release Version 7.3.0.1.1
     Copyright 2000, ALTIBASE Corporation or its subsidiaries.
     All Rights Reserved.
 -----------------------------------------------------------------
 [ERR-51011 : redefinition of 'i'.]

 [ERR-204E : The symbol name [i] can't be added on the symbol table.]
 File  : main.sc
 Line  : 13
 Offset: 24-24
 Error_token:;

Precautions#

Syntax improvement

In order for existing SESC/C++ to describe EXEC SQL BEGIN/END DECLARE/ARGUMENT SECTION in the code, it is irrelevant even if the terminator ";" is omitted, but APREC/C++ must have ";".

This precaution applies the same as other DBMS precompilers.

The following is an error when the terminator is not specified in the END DECLARE SECTION.

 [ERR-302L : EXEC SQL END DECLARE SECTION is not exist.]

Source code precompile of C++ style

To use a host variable outside the host variable declaration section, the mode of the parse option must be set to full.

However, if the parsing mode is set to full, the C parser operates, so the source code of C++ style may cause various parsing errors during preprocessing.

In other words, source code written in C++ style should declare host variables only in the host variable declaration section such as SES*C/C++, and if the -parse option is used, the parsing mode should be partial or none.

-D, -I Options

If the -D and -I options are used in the C/C++ compilation stage, in most cases, correct precompile is possible only when the same option is given in the precompile stage with APRE*C/C++.

Notes#

-I Option

It is fine to use -include, but it is recommended to change to a new option in consideration of future maintenance.

Binary data type change

The name of the previously used SES_CLOB, SES_BLOB, SES_BINARY, SES_BYTES, and SES_NIBBLE types have changed to APRE_CLOB, APRE_BLOB, APRE_BINARY, APRE_BYTES, and APRE_NIBBLE.

Since backward compatibility is considered, it is okay to use an existing name.

Changes#

This section describes considerations and procedures when upgrading from SESC/C++ environment to the APREC/C++ environment.

As the name was changed from SESC/C++ to APREC/C++, the name of execution file, header file, library file, link option, and execution file command options were partially changed as follows.

Classification SES*C/C++ APRE*C/C++ Related file path Remarks
Execution file sesc apre $ALTIBASE_HOME/bin Changed
Header file ses.h ulpLibInterface.h $ALTIBASE_HOME/include Changed
Library files libsesc.a libapre.a $ALTIBASE_HOME/lib Changed
libsesc_sl.so libapre_sl.so $ALTIBASE_HOME/lib Changed
Link option -lsesc -lapre - Changed
Execution file command option -include -include or -I - Added

There are no other measures to be taken since the above changes are backward compatible, but it is recommended to change the execution file name and link option to APRE*C/C++ style for future maintenance. In addition, although it is not essential, it is recommended to change the -include option to -I.

Upgrade procedures#

The procedure for upgrading from SESC/C++ to APREC/C++ development environment is as follows:

Refer to the table in the Changes section, execute the relevant statements, and modify options in compilation files such as link options and the makefile.

  • Change the execution file name

    $ apre -t cpp connect1.sc
    
    - Change the link option

    $ g++ -Wl,-relax -L. -O3 -L/home/altibase/altibase_home/lib -o connect1
    connect1.o -lapre -lodbccli -ldl -lpthread -lcrypt -lrt
    
    - makefile

    %.cpp : %.sc
        apre -t cpp $<
    ...
    connect1: connect1.$(OBJEXT) connect1.cpp
        $(LD) $(LFLAGS) $(LDOUT)connect1$(BINEXT) connect1.$(OBJEXT) $(LIBOPT)apre$(LIBAFT) $(LIBOPT)odbccli$(LIBAFT) $(LIBS)
    

If the file related to a change is not easily identified or cannot be changed due to the large amount, the procedure in the example above can be omitted, but it is recommended to do a normal upgrade by changing the related name as much as possible.

Considerations#

  • Adding parse none option

APREC/C++ -> [Notes] -> Although the syntax is not mentioned in the section, the source that was precompiled without any problems in SESC/C++ may cause an error in APREC/C++. In this case, since the parsing mode of APREC/C++ is partial, it is likely an error that occurs while macro processing up to the header file included in the #include method.

Therefore, if the cause of the error is not easily specified, it is necessary to check by adding the -parse none option to precompile the same as SES*C/C++.

  • Error due to use of the precompiler library

If the existing source code is written to use the SES*C/C++ library directly, compilation may not be possible due to the change of the precompiler library interface. In this case, all related codes must be removed from the existing source code.

The library interface of the precompiler is an internal element that is frequently changed, and used directly by the user is prohibited. Therefore, Altibase is not responsible for any errors that occur in the future while analyzing the precompiled source code and using the related macros, structures, and functions in the source code arbitrarily.