Components

This chapter describes RPC program components and how to use each component through execution examples.

1. Overview

An RPC program consists of three components:

Interface definition files

There are two types of interface definition files: SQL interface file and API definition file.
idlc

Utility that creates the source.
Shared library

Required for applications.

2. Interface Definition Files

The interface definition files are divided into two types: SQL and API.

2.1. SQL Interface Definition File

The SQL interface definition file is used when an application runs through SQL. This file is used to set the DA server and the TP server. Multiple SQL statements can be defined in a single file, and each defined SQL represents a function. A single definition file configures a single TCS server.

The following shows the basic format and describes each field of the SQL interface definition file. '#' indicates the start of a comment.

#comment
function_name:
SQL sentence;

function_name:
SQL sentence;

function_name

Function name to be called by a client that executes SQL statements. The text followed by a colon (:) is recognized as a function name
SQL sentence
- SQL statement, which can be expressed with multiple lines. SELECT, INSERT, UPDATE, and DELETE statements can be defined.
- A word that starts with "$" in an SQL statement is recognized as an input parameter of a function. Each parameter must be a C style char string array.
- Field names between SELECT and FROM are recognized as parameters that store the results of each function.
- If the type of each field is defined in the "[Field Type]" format preceding the field name, the type can be used as is when creating the function. char, int, long, float, double, string, and binary field types can be defined. Use the binary field type to process BLOB type data.

SELECT Statement

The following examples show how to define a SELECT statement named sel_test and how it is converted into a function.

SQL definition

sel_test:
SELECT
        [int] no,
        [double] comm,
        name
FROM sample
WHERE no = $no;

Function conversion

The following shows that $no is changed into char *no. A select query can retrieve multiple rows, so the number of rows can be saved in the tmax_sel_rows variable. The fields between SELECT and FROM are arranged in the order to be saved according to each type.
```
long int sel_test(
    /* [in] */ char *no,
    /* [out] */ long int *tmax_sel_rows,
    /* [out] */ int **outvars_0,
    /* [out] */ double **outvars_1,
    /* [out] */ char ***outvars_2
);
```

INSERT Statement

The following examples show how to define an INSERT statement named int_test and how it is converted into a function.

SQL definition

ins_test:
INSERT INTO sample(no, name) VALUES ($no, '$name');

Function conversion

The definition is converted into a function that receives $no and $name as parameters:
```
long int ins_test(
    /* [in] */ char *no,
    /* [in] */ char *name
);
```

UPDATE Statement

The following shows how to define an UPDATE statement named update_test and how it is converted into a function.

SQL definition

update_test:
UPDATE sample SET name='$name' WHERE no=$no;

Function conversion

The definition is converted into a function that receives $no and $name as parameters:
```
long int update_test(
    /* [in] */ char *name,
    /* [in] */ char *no
);
```

DELETE Statement*

The following shows how to define a DELETE statement named del_test and how it is converted into a function.

SQL definition

del_test:
DELETE FROM sample WHERE no=$no;

Function conversion

The definition is converted into a function that receives $no as a parameter:
```
long int del_test(
    /* [in] */ char *no
);
```

2.2. API Definition File

The API definition file defines APIs used by the TP server and the FS server.

Define the prototype of the function to be executed in the server in the following format. The return type and the parameter types must be C style types. The parameter type can be specified using in/out indicators.

interface Service Name {
        Return Type Function Name (
                [in|out] Parameter Type   Parameter Name
        );
}

The following shows how to define and return a function with a service name of TSTEST.

Function definition

interface TSTEST {
        long trans_select (
                [out]   long    sel_rows,
                [out]   int     empno[sel_rows],
                [out]   char    ename[][]);

        long trans_insert (
                [in]    int     dummy
            );

        long trans_clear (
                [in]    int     dummy
            );
}

Function conversion

long int trans_select(
    /* [out] */ long int *sel_rows,
    /* [out] */ int **empno,
    /* [out] */ char ***ename
);
long int trans_insert(
    /* [in] */ int dummy
);
long int trans_clear(
    /* [in] */ int dummy
);

3. idlc

idlc is a utility that converts a definition file into a programmable source.

The following shows the options available in idlc and descriptions of the options.

idlc -inf  Interface Name
     -sql  SQL Interface Name
     -dbtype  ora | tbr | syb
     -clang  c | delphi | vbasic | pbuilder | java | delphi6
     -xa
     -header  File Name
     -sstub   File Name
     -cstub   File Name

Option	Description
-inf Interface Name	Interface name when the DA server is used.
-sql SQL Interface Name	Interface file name when the DA server and the TP server are used.
-dbtype	DB type when the DA server is used. For more information about operating systems and databases that support RPC, refer to Constraints. ora : Oracle syb : Sybase tbr : Tibero
-clang	Language of the client source stub file. c delphi vbasic pbuilder java delphi6 delphixe
-xa	Required when creating a XA server.
-header File Name	Name of the header file to be created.
-sstub File Name	Name of the server stub file to be created.
-cstub File Name	Name of the client stub file to be created.

Option

Description

-inf Interface Name

Interface name when the DA server is used.

-sql SQL Interface Name

Interface file name when the DA server and the TP server are used.

-dbtype

DB type when the DA server is used. For more information about operating systems and databases that support RPC, refer to Constraints.

ora : Oracle
syb : Sybase
tbr : Tibero

-clang

Language of the client source stub file.

c
delphi
vbasic
pbuilder
java
delphi6
delphixe

-xa

Required when creating a XA server.

-header File Name

Name of the header file to be created.

-sstub File Name

Name of the server stub file to be created.

-cstub File Name

Name of the client stub file to be created.

The following are usage examples according to the server type.

DA Server

On an Oracle database, if dstest.sql is used in an application and the client uses C, set the following options:
```
idlc -inf dstest
     -sql dstest.sql
     -dbtype ora
     -clang c
```
TS Server
- When a .def file is used.
  
  If the TP server uses a .def file, set the following options:
  idlc -xa -clang c tstest.def
- When a DA server is used.
  
  If the DA server called by the TP server is used, set the following options:
  idlc -inf db1 -sql db1.sql -dbtype ora -clang c -xa -tps
FS Server

For the FS server, set the options the same as for the TP server.
```
idlc -xa
     -clang c fstest.def
```

4. Shared Library

For the TCS type server and regular clients, a library for RPC, in addition to the server and client libraries, which are provided by default, are required.

The following describes the required shared libraries.

Library for servers
- Server library provided by default for the TCS type server.
- Uses libsvr and makes the actual functions executable.
- Provided with the name 'librpcsvr.*' in UNIX.
Library for clients
- Client library provided for regular clients.
- Uses libcli and supports communication.
- Provided with the name 'librpccli.*' in UNIX and 'tmaxrpccli.dll' in Windows.
Library for DB access
- DBs have different features so the libraries used vary according the DB.
- Use 'librpcsql.*' for Oracle, 'librpctbr.*' for Tibero, and 'librpcsyb.*' for Sysbase.