Developer Guide PHP SQL Developers Guide · To address this issue, the community that develops PHP has introduced the PHP Data Objects (PDO) extension for accessing a database. PDO

Developer Guide

PHP SQL Developers Guide

All Rights Reserved ii www.faircom.com

Contents

1. c-treeACE PHP for c-treeACE SQL ................................................................... 1

2. Quick Start .......................................................................................................... 3

3. Using PHP 7 with the PDO Extension ............................................................... 6

3.1 Install PHP 7 PDO and Microsoft IIS .................................................................... 6

Install Microsoft IIS .............................................................................................................. 7

Install PHP 7 with the PDO Extension ................................................................................ 9

Configure Microsoft IIS ..................................................................................................... 12

Compile the PHP PDO Extension (Windows) ................................................................... 15

Run the PHP PDO Tutorials with Microsoft IIS ................................................................. 17

3.2 Install PHP 7 PDO on Linux and Unix ................................................................ 18

Configure PHP 7 ............................................................................................................... 19

Compile the PHP PDO Extension (Linux/Unix) ................................................................ 22

Run the sql.php.pdo Tutorials with Linux/Unix Apache .................................................... 23

4. Using PHP with the SQL PHP API ................................................................... 25

4.1 Using the SQL PHP API on Windows ................................................................ 26

Configure the SQL PHP Extension ................................................................................... 27

Compile the SQL PHP Extension ..................................................................................... 30

Run the SQL PHP Tutorials with Microsoft IIS ................................................................. 33

4.2 Using SQL PHP on Linux and Unix .................................................................... 35

Configure PHP .................................................................................................................. 36

Compile the SQL PHP Extension (Linux/Unix) ................................................................. 38

Run the SQL PHP Tutorials with Linux/Unix Apache ....................................................... 40

5. Using PHP with ODBC ..................................................................................... 42

5.1 Using PHP on Windows ..................................................................................... 42

Packages Required for Windows ...................................................................................... 42

Install Microsoft IIS ............................................................................................................ 43

Install PHP ........................................................................................................................ 45

Configure Microsoft IIS ..................................................................................................... 46

5.2 Using PHP on Linux and Unix ............................................................................ 48

Install unixODBC ............................................................................................................... 48

Install PHP ........................................................................................................................ 49

Install the Web Server ....................................................................................................... 49

5.3 Set Up the ODBC Data Source .......................................................................... 51

6. Introductory Tutorial ........................................................................................ 51

c-treeACE PHP for c-treeACE SQL

All Rights Reserved iii www.faircom.com

6.1 Init ...................................................................................................................... 52

6.2 Define ................................................................................................................ 53

6.3 Manage .............................................................................................................. 53

6.4 Done .................................................................................................................. 55

6.5 Additional Resources ......................................................................................... 56

7. Relationships ................................................................................................... 56

7.1 Init ...................................................................................................................... 58

7.2 Define ................................................................................................................ 58

7.3 Manage .............................................................................................................. 61

7.4 Done .................................................................................................................. 64


8. Record/Row Locking ....................................................................................... 65

8.1 Init ...................................................................................................................... 66

8.2 Define ................................................................................................................ 66

8.3 Manage .............................................................................................................. 67

8.4 Done .................................................................................................................. 69


9. Transaction Processing .................................................................................. 70

9.1 Init ...................................................................................................................... 71

9.2 Define ................................................................................................................ 71

9.3 Manage .............................................................................................................. 73

9.4 Done .................................................................................................................. 78


10. Additional Functionality .................................................................................. 80

11. c-treeACE PHP Functions ............................................................................... 81

11.1 Resource Types ................................................................................................. 81

11.2 c-treeACE PHP Example ................................................................................... 82

12. Index ............................................................................................................... 106

All Rights Reserved 1 www.faircom.com

1. c-treeACE PHP for c-treeACE SQL

Today’s progressive business environments demand online availability. The method of choice is

via the web and PHP has become the language of choice for dynamic web scripting.

PHP (Hypertext PreProcessor) is a widely-used general-purpose scripting language that is

especially suited for web development and can be embedded into HTML. c-treeACE SQL is a

powerful database technology offering a wide range of interfaces now including PHP support.

FairCom’s c-treeACE PHP module extends your data access to the world through this popular

web interface.

c-treeACE PHP Interface technology gives the means to access data from c-treeACE SQL.

c-treeACE PHP modules can be installed with either Apache or Microsoft IIS (Windows) web

servers.

Accessing c-treeACE from PHP

The c-treeACE package provides two versions of the c-treeACE PHP drivers, each in its own

directory:

sql.php.pdo

sdk\sql.php.pdo - Notice the folder name is sql.php.pdo

These drivers support PHP 7 and the PDO (PHP Data Object) extension.

This is the preferred way to access c-treeACE from PHP.

sql.php

sdk\sql.php

These drivers support PHP 5. See sdk\sql.php.pdo for PHP 7 support.

Instructions are provided for using the c-treeACE ODBC interface to connect c-treeACE to

PHP. All later versions of PHP (PHP 4, PHP 5, and PHP 7) are compatible with the ODBC

interface.

Note: If you are NOT using ODBC, only PHP 5 is supported. Use the other folder,

c-treeACE PHP for c-treeACE SQL


sql.php.pdo, to connect to c-treeACE using PHP 7.

Each folder contains a ReadMe file for the drivers in that folder.

Documentation about c-treeACE SQL can be found on FairCom’s web site www.faircom.com

(http://www.faircom.com/).

http://www.faircom.com/


2. Quick Start

This Quick Start comprises four simple tutorials designed to guide you through the basic use of

the c-treeACE PHP Interface technology.

This guide presents the following ways to use c-treeACE with PHP:

Using PHP 7 with the PDO Extension (page 6) - This is the preferred method of

connecting c-treeACE with PHP. It supports PHP 7.

Using PHP with the sql.php API (page 25) - This method uses the native c-treeACE

sql.php driver to connect to PHP 5.x.x. It does not support later versions of PHP.

Using PHP with ODBC (page 42) - This method is an alternative to connecting to PHP using

the native sql.php driver or the PDO extension.

Overview of the Tutorials

Like all other tutorials in the c-tree series, each example simplifies the concepts of database

programming into four simple steps: Initialize(), Define(), Manage(), and You're Done() !

No matter what c-treeACE Interface language you are using, FairCom follows this same

high-level flow in all tutorials. This makes it easy for developers to "cross-over" from one

language interface to another as these basic concepts apply to all.

Initialize()

Every language requires some form of initial "logon" or "connection" procedure to establish a session with the database. This is done in the Initialize() stage of the program.

Define()

Database definitions (DDL), Table/File schema definitions, Index definitions, Table/File creation, and Table/File open operations are all addressed in the Define() stage of the program.

Manage()

This stage of the program is where the database is operated on, as in managing your data. Adding/Reading/Updating/Deleting records/rows are handled in this stage of the program.

Done()

When the program ends, the database session should be closed. This stage handles the necessities to "de-init", by closing Tables/Files and issuing any required "logoff" or "disconnect" type procedures.

Presented here are tutorials that follow the "Initialize(), Define(), Manage(), and You're Done() ! "

approach.

The source code is located in the sdk\sql.php\tutorials directory.

Quick Start


Overview of the Tutorials

Here is a conceptual overview of what these tutorials do:

Tutorial #1: Introductory - Simple Single Table

We wanted to keep this program as simple as possible. This program does the following:

Initialize() - Connects to the c-treeACE database engine.

Define() - Defines and creates a "customer master" (custmast) file/table.

Manage() - Adds a few records/rows; Reads the records/rows back from the database and

displays their content; and then deletes the records/rows.

Done() - Disconnects from c-treeACE Database Engine.

Tutorial #2: Relational Model and Indexing

Here we now add a bit more complexity, introducing multiple tables, with related indices in order

to form a simple "relational" database simulating an Order Entry system. Here is an overview of

what will be created:


Define() - Defines and creates the "custmast", "custordr", "ordritem" and the "itemmast"

files/tables with related indices.

Manage() - Adds some related records/rows to all files/tables. Then queries this order

database.


Tutorial #3: Locking

Here we demonstrate the enforcement of data integrity by introducing record/row "locking".


Define() - Defines and creates a "customer master" (custmast) file/table.

Manage() - Adds a few records/rows; Reads the records/rows back from the database and

displays their content. Then demonstrates an update operation under locking control, and a

scenario that shows a locking conflict.

Quick Start


Done() - Disconnects from c-treeACE database engine.

Tutorial #4: Transaction Processing

Here we demonstrate transaction control.


Define() - Defines and creates our four file/tables.

Manage() - Adds records/rows to multiple tables under transaction control.


Use the help file navigation arrows at the top of your browser and the end of each topic (labeled

NEXT and PREV) to progress through the tutorials.

Feel free to use these projects as a starting point for your next c-treeACE project!


3. Using PHP 7 with the PDO Extension

PHP is typically used to create database-driven web pages and websites. Originally, it used

conventional SQL to access an underlying database to retrieve data, which determined many

aspects of the pages it served up to the user. Developers have long recognized one drawback to

this useful functionality: many databases use variations on "standard" SQL, which can make your

application difficult to port to a different database.

To address this issue, the community that develops PHP has introduced the PHP Data Objects

(PDO) extension for accessing a database. PDO gives you an abstraction layer so that your

applications use the same functions to issue queries regardless of the underlying database. The

goal of PDO is to allow an application to be independent of the database it uses. This should

allow a developer to change databases with no change in application coding or logic.

FairCom c-treeACE PHP offers native support for this extension using a database-specific PDO

driver to access the c-treeACE Server.

Developers who are interested in taking advantage of this interface for accessing the

c-treeACE database using the latest PHP standard will want to use this interface.

Developers who have an existing PHP application that uses PDO are able to upgrade their

application to use c-treeACE by simply installing the driver—no re-coding should be required.

The PHP community does not intend PDO to be a complete database abstraction layer. Instead,

it is focused on implementing the functions used to issue queries and fetch data. See the PHP

website for a detailed definition of what the PDO extension provides and what it does not provide:

https://secure.php.net/manual/en/book.pdo.php (https://secure.php.net/manual/en/book.pdo.php)

In this chapter you will find instructions for Windows and Unix/Linux platforms:

Install PHP 7 PDO and Microsoft IIS (page 6)

Install PHP 7 PDO on Linux and Unix (page 18)

3.1 Install PHP 7 PDO and Microsoft IIS

To install PHP 7 with the PDO extension for use with Microsoft IIS, follow these steps:

Install Microsoft IIS (page 7)

Install PHP with the PDO Extension (page 9)

Configure Microsoft IIS (page 12)

Compile the sql.php Extension (page 15)

Run the sql.php.pdo Tutorials with Microsoft IIS (page 17)

https://secure.php.net/manual/en/book.pdo.php

Using PHP 7 with the PDO Extension


Install Microsoft IIS

To install Internet Information Service (IIS) web server on Microsoft Windows, follow these

instructions:

Note: This section shows typical procedures using Windows 7 as an example. Some of the dialog and labels may look different in other versions of Windows.

1. Open the Windows Control Panel (Usually Start Menu > Control Panel) and select Programs:

2. In the program menu, select Turn Windows features on and off:



3. Wait for the content of the Windows Features window to appear and check Internet Information Services.

4. Expand Internet Information Services > World Wide Web Services > Application Development Features and check CGI:

5. Click OK to begin the installation of IIS.



Install PHP 7 with the PDO Extension

This section explains how to install the PHP extensions for IIS. These procedures can be used

with all recent versions of PHP: PHP 4, PHP 5, and PHP 7.

Note: In some releases, it will be necessary to compile the extension, as described in Compile the sql.php.pdo Extension (page 15).

1. Open your web browser and go to http://www.php.net/downloads.php http://www.php.net/downloads.php and download the Windows Binaries zip package for the latest PHP version:

http://www.php.net/downloads.php



2. Once you have downloaded the file, right-click it and extract all files.

3. Enter C:\php as the destination, and click Extract:

4. Open an Administrator Command Prompt, move to C:\php and copy php.ini-production (or php.ini-development) to C:\Windows\php.ini.

5. Open C:\Windows\php.ini with a text editor such as Notepad and uncomment the

extension_dir = "ext" entry:



6. Search for the extension list (you can search for ";extension"), add

extension=php_pdo_ctsql.dll to the end of the list, and save and close php.ini.



7. Now return to your Administrator Command Prompt (if you closed it, open a new one), move to C:\php\ext and copy php_pdo_ctsql.dll.

Configure Microsoft IIS

To configure IIS for PHP, follow these steps:

Note: This section shows typical procedures using Windows 7 as an example. Some of the dialog

and labels may look different in other versions of Windows.

1. Open the Start Menu, select Run, and execute InetMgr.exe:



2. In the InetMgr main window, double-click Handler Mappings:

3. In the Handler Mappings window, click Add Module Mapping... on the right-side Actions menu:



4. Complete the dialog window with the following: Request Path: *.php Module: FastCgiModule Executable: C:\php\php-cgi.exe Name: PHP

5. Click OK and then Yes on the "Add Script Map" message box that appears. Finally, close the InetMgr dialog.

6. Restart your computer to ensure everything is configured.



Note: It is not mandatory to restart your computer at this time, however, it is advised to ensure IIS is properly configured.

Compile the PHP PDO Extension (Windows)

c-treeACE includes pre-built drivers for a variety of platforms. If you need a driver that is not supplied (e.g., if you need a platform that is not provided or a different version of PHP), use the procedures in this section to compile the driver.

To compile and install the c-treeACE PHP PDO extension on Windows, follow the steps in this

section.

Step 1: Build PHP

To build PHP 5 from the source code, follow the Build your own PHP on Windows

https://wiki.php.net/internals/windows/stepbystepbuild page.

When you reach the Compile section, you will need to modify the steps as shown below:

1. If necessary, copy these .h files from the c-tree include folder, <basedir>\include, to the c-tree include folder sql.embedded <basedir>\include\sdk\sql.embedded:

ct_oem.h, ctsql_lib.h, ctsqlall.h, ctsqlray.h, ctvers.h, dh_custom.h, dh_literals.h

Where <basedir> is the full path of your c-treeACE, c-treeRTG or c-treeEDGE installation

directory.

2. Open a command prompt and enter the build directory:

cd C:\php-sdk\

3. Set up the build environment variables:

bin\phpsdk_setvars.bat

Change directory to the location of your PHP source code, e.g.:

cd C:\php-sdk\phpdev\vc12\x86\php-5.6.22-src

4. Run the following based on the FairCom product you are using (where <basedir> is the full path of your c-treeACE installation directory):

• c-treeACE

buildconf --force --add-modules-dir=<basedir>\sdk\sql.php.pdo

• c-treeRTG

buildconf --force --add-modules-dir=<basedir>\Driver\sql.php.pdo

• c-treeEDGE

buildconf --force --add-modules-dir=<basedir>\drivers\<your-API-folder>

5. Enable the c-treeACE PHP extension by using the --add-modules-dir switch as follows:

configure --disable-all --enable-pdo --enable-cli --enable-cgi --ena

ble-object-out-dir=.. --disable-ipv6 --with-pdo-ctsql=shared,<basedi

r>

Where <basedir> is the full path of your c-treeACE or c-treeRTG installation directory.

6. To build PHP, run:

nmake clean (in case you need to recompile)

nmake

https://wiki.php.net/internals/windows/stepbystepbuild



7. Ensure that ctsqlapi.dll is in the Windows path variable with the following command: set path=%path%; C:\FairCom\V11.x.x\win32\bin\sql.direct

8. You can now test the results as follows:

php -c php.ini -f C:\inetpub\wwwroot\PHP_Tutorial1.php >> out.html

Step 2: Install the Extension

The compilation run in step 1 will also build the c-treeACE PHP extension. You can find the

extension compiled into your work\Debug_TS or work\Release_TS directory.

To install the extension, you can drag and drop the content into your installed PHP folder, e.g

C:\php, (The PHP folder must be cleared so the entire content can be copied and take effect.)



Run the PHP PDO Tutorials with Microsoft IIS

c-treeACE PHP includes a set of tutorials intended for use with the PHP 7 PDO extension. To

install and execute these tutorials with Microsoft Internet Information Service (IIS), be sure to

install IIS and PHP 5.x.x as described in the previous sections. Next, you will need to copy the

tutorials files into the IIS root directory as shown in this section.

Configure the c-treeACE PHP Extension

1. Open an Administrator Command Prompt, move to C:\inetpub\wwwroot, and copy the contents of <your-API-folder>\tutorials in your installation directory.

2. Open your favorite web browser and connect to http://localhost. You should see the index.htm page with hyperlinks to the three tutorials to be executed:



3. Click on the tutorial hyperlinks to execute the tutorials:

3.2 Install PHP 7 PDO on Linux and Unix

To install and execute c-treeACE PHP tutorials on Linux/Unix, please consider using the package

manager of the platform to avoid system settings errors.

In this section we list the commands using the Linux Ubuntu as an example. The commands

described here may vary depending on your environment.

You will need to configure PHP 7, compile it, and run the tutorials as described in the following

sections:

Configure PHP 7 (page 19)

Compile the sql.php.pdo Extension (Linux/Unix) (page 22)

Run the sql.php.pdo Tutorials with Linux/Unix Apache (page 23)



Configure PHP 7

PHP is included in many common Linux and Unix distributions. The latest version of PHP can be

downloaded from the PHP website http://www.php.net/downloads.php.

To configure PHP to run c-treeACE SQL PHP follow these steps:

Note: These instructions are not valid for CentOS versions 6, 7, and 8. If followed, they with render PHP non-operational on those systems. If you are installing on one of those CentOS versions, see Instructions for CentOS (page 21).

1. Open php.ini with your favorite text editor. In most installations you will find php.ini in /etc/php/apache2/php.ini.

2. Search for extension_dir.

• If this line is commented out (; on the beginning of the line) un-comment this line and

replace the contents of the quotes with your c-treeACE SQL PHP extensions directory.

• If this line is not commented, it's better to mve ctsql.so into your default PHP extensions

directory.

3. Search for extensions area and add extension=pdo_ctsql.so to configure the c-treeACE

SQL PHP module into your PHP:




4. Save the changes to php.ini and close your text editor.

5. From the root shell restart your web server with the following command: /etc/init.d/apache2 restart



Instructions for CentOS

The instructions for installing and configuring PHP on CentOS 6, 7, 8, are slightly different than

the instructions for most flavors of Linux/Unix. Be sure to use these procedures if you are

installing on one of these CentOS versions.

These instructions assume you are using a version of PHP 7 from remirepo (https://rpms.remirepo.net).

Make sure your installed version of php-devel is exactly the same version as your PHP 7: First

install the version of PHP 7 you desire using the following:

yum-config-manager --enable remi-php__

yum install php.....

Then execute:

yum install php-devel.

For these procedures, the php.ini file should not be changed. Do not add FairCom entries to

extension_dir and the extensions area of that file. Instead, perform the following steps:

To install on CentOS 6, 7, 8, follow the instructions below:

1. Create file /etc/php.d/30-pdo_ctsql.ini with a single line, which must end in .so:

extension=pdo_ctsql.so

Make sure this file has the same permissions as the other files in that directory.

2. Some builds of CentOS do NOT include the static version of libc, which is needed for building the pdo_ctsql.so library. If the following build instructions give a link error "cannot find -lstdc+", you need to install the static version of libc, as follows:

sudo yum install glibc-static libstdc+-static

3. Build pdo_ctsql.so under your version of PHP (following these instructions: Compile the PHP PDO Extension (page 22)) and the copy it into this folder. Be sure it has the same permissions as the other .so files in that folder: /usr/lib64/php/modules/

4. Note that if you change versions of PHP, you should do a make clean first, before doing

make.

5. Copy the FairCom lib/sql.direct/libctsqlapi.so file to the shared library folder (/usr/lib64), and set its permissions to "755", as follows:

cp libctsqlapi.so /usr/lib64

chmod 755 /usr/lib64/libctsqlapi.so

6. Restart your web server. For example, with Apache you would use the following command:

sudo systemctl restart httpd

Test your work by running PHP tutorial #1 from the command line:

php -f /whatever_path_you_are_using/<your-API-folder>/tutorials/PHP_Tutorial1.php

Testing from the command line allows you to see the error messages, even if PHP fails to launch

(because it is misconfigured). The tutorial files do not need to be copied to the web server's

documents directory.

https://rpms.remirepo.net/



Compile the PHP PDO Extension (Linux/Unix)

c-treeACE includes pre-built drivers for a variety of platforms. If you need a driver that is not supplied (e.g., if you need a platform that is not provided or a different version of PHP), use the procedures in this section to compile the driver.

Requirements:

PHP 7 development package

Perl

Autoconf

Automake

GNU m4

C++ Compiler

Step 1: Create Configuration Script

Move to the <your-API-folder>/src directory under your installation directory.

Run the phpize command to create configuration script:

phpize

Step 2: Configure and Build

Run the configure script to create the makefile containing the instructions to build the c-treeACE

PHP extension:

./configure

Build c-treeACE PHP extension using make:

make

Step 3: Install (Optional)

If you want to install the c-treeACE PHP extension into your PHP installation extensions directory,

run make install as root user.

Switch to root user:

su

[Enter your root password]

Run the installer:

make install

Note: If you install using make install, be sure php.ini is configured to load extensions from the PHP installation extensions directory.



Note: If you have a configure script with installed Autotools, follow these steps: > libtoolize > aclocal > autoreconf -i > phpize > ./configure --make-ctsql

Run the sql.php.pdo Tutorials with Linux/Unix Apache

c-treeACE PHP includes a set of tutorials intended for use with the PHP 7 PDO extension. To

execute these tutorials, copy the tutorials files into a directory accessible to your web server (here

we use the web server root directory) as shown below:

1. Open a root shell and move to /var/www/ and copy the contents of the <your-API-folder>/tutorials/ directory under your installation directory:

debian:~# cd /var/www/

debian:/var/www# cp -v <FairCom-Folder>/<your-API-folder>/tutorials/* .

(You will need to adjust the path based on your installation directory.)



2. Make sure c-treeACE SQL is running.

3. Open your favorite web browser and connect to http://localhost/index.htm (make sure you are using a proper URL if you did not use the web server root directory). You should see the index.htm page with hyperlinks to the three tutorials to be executed:

4. Click the tutorials hyperlinks to execute the tutorials:


4. Using PHP with the SQL PHP API

The SQL PHP API supplied with c-treeACE is a native PHP API designed specifically for

interfacing c-treeACE with PHP 5.x.x. It does not support later versions of PHP.

The SQL PHP API is provided primarily for environments that cannot use the PDO extension or

ODBC (e.g., Unix/Linux systems running PHP 5.x.x. where you are unable to install an ODBC

driver).

The preferred method of interfacing c-treeACE with PHP is to use the PDO extension, which

supports all recent versions of PHP. See Using PHP 7 with the PDO Extension (page 6).

If you want to interface PHP 5.x.x. with c-treeACE using the sql.php API, follow the procedures in

the appropriate part of this chapter:

Using the SQL PHP API on Windows (page 26)

Using the SQL PHP API on Linux and Unix (page 35)

Like all other tutorials in the c-tree series, each example simplifies the concepts of database

programming into four simple steps: Initialize(), Define(), Manage(), and You're Done() !

No matter what c-treeACE Interface language you are using, FairCom follows this same

high-level flow in all tutorials. This makes it easy for developers to "cross-over" from one

language interface to another as these basic concepts apply to all.

Initialize()

Every language requires some form of initial "logon" or "connection" procedure to establish a session with the database. This is done in the Initialize() stage of the program.

Define()

Database definitions (DDL), Table/File schema definitions, Index definitions, Table/File creation, and Table/File open operations are all addressed in the Define() stage of the program.

Manage()

This stage of the program is where the database is operated on, as in managing your data. Adding/Reading/Updating/Deleting records/rows are handled in this stage of the program.

Done()

When the program ends, the database session should be closed. This stage handles the necessities to "de-init", by closing Tables/Files and issuing any required "logoff" or "disconnect" type procedures.

Presented here are tutorials that follow the "Initialize(), Define(), Manage(), and You're Done() ! "

approach.


4.1 Using the SQL PHP API on Windows

To install and execute the SQL PHP tutorials with Microsoft IIS, you will need to set up the SQL

PHP extension as described in the following sections:

Configure the SQL PHP Extension (page 27)

Compile the SQL PHP Extension (page 30)

Run the SQL PHP API IIS Tutorials (page 33)


Configure the SQL PHP Extension

To configure the c-treeACE SQL PHP extension, follow these steps:

1. Open an Administrator Command Prompt, move to C:\php and copy php.ini-dist to C:\Windows\php.ini

2. Open C:\Windows\php.ini with a text editor such as Notepad and search for

extension_dir= "./" and change "./" to "C:\php\ext":

Using PHP with the SQL PHP API


3. Search for the extension list (you can search for ";extension"), add

extension=php_ctsql.dll to the end of the list, and save and close php.ini



4. Now return to your Administrator Command Prompt (if you closed it open a new one), move to C:\php\ext and copy php_ctsql.dll.


Compile the SQL PHP Extension

To compile and install the SQL PHP extension on Windows, follow the steps in this section.

Step 1: Build PHP

To build PHP 5 from source code, follow the Build your own PHP on Windows

https://wiki.php.net/internals/windows/stepbystepbuild page.

When you reach the Compile section, you will need to modify the steps as shown below:

1. Copy these .h files from the c-tree <your-API-folder>\src\sql.embedded\include folder to your project's include folder:

ct_oem.h, ctsql_lib.h, ctsqlall.h, ctsqlray.h, ctvers.h, dh_custom.h, dh_literals.h

2. Open a command prompt and enter the build directory:

cd C:\php-sdk\

3. Set up build environment variables:

bin\phpsdk_setvars.bat

Change directory to the location of your PHP source code, e.g.:

cd C:\php-sdk\phpdev\vc12\x86\php-5.6.22-src

4. Run the following based on the FairCom product you are using (where <basedir> is the full path of your c-treeACE installation directory):

• c-treeACE

buildconf --force --add-modules-dir=<basedir>\sdk\sql.php

• c-treeRTG

buildconf --force --add-modules-dir=<basedir>\Driver\sql.php

• c-treeEDGE

buildconf --force --add-modules-dir=<basedir>\drivers\<your-API-folder>

5. Enable the c-treeACE PHP extension by using the --add-modules-dir switch as follows:

configure --disable-all --enable-cli --enable-cgi --enable-object-ou

t-dir=.. --disable-ipv6 --disable-zts --with-ctsql=shared,<basedir>

Where <basedir> is the full path of your c-treeACE or c-treeRTG installation directory.

6. c-treeACE ONLY: Copy the OpenSSL libraries:

copy <basedir>\lib\License.Lib\openssl\"Microsoft Visual Studio

2012"\libeay32.lib <basedir>\sdk\sql.php\src\ctlibeay32.lib

copy <basedir>\lib\License.Lib\openssl\"Microsoft Visual Studio

2012"\ssleay32.lib <basedir>\sdk\sql.php\src\ctssleay32.lib

7. To build PHP, run:

nmake clean (in case you need to recompile)

nmake

8. You can now test the results as follows:

php -c php.ini -f C:\inetpub\wwwroot\PHP_Tutorial1.php >> out.html

https://wiki.php.net/internals/windows/stepbystepbuild



Step 2: Install the Extension

The compilation run in step 1 will also build the c-treeACE PHP extension. You can find the

extension compiled into your work\Debug_TS or work\Release_TS directory.

To install the extension, you can drag and drop the content into your installed PHP folder, e.g

C:\php, (The PHP folder must be cleared so the entire content can be copied and take effect.)




Run the SQL PHP Tutorials with Microsoft IIS

To install and execute the SQL PHP tutorials with Microsoft Internet Information Service (IIS), be

sure to install IIS and PHP 5.x.x as described in the previous sections. Next, you will need to copy

the tutorials files into the IIS root directory as shown in this section.

Configure the c-treeACE PHP Extension

1. Open an Administrator Command Prompt, move to C:\inetpub\wwwroot, and copy the contents of sdk\sql.php\tutorials under your installation directory.

2. Open your favorite web browser and connect to http://localhost. You should see the index.htm page with hyperlinks to the three tutorials to be executed:



3. Click on the tutorial hyperlinks to execute the tutorials:


4.2 Using SQL PHP on Linux and Unix

To install and execute the SQL PHP tutorials with Apache on Unix/Linux systems, you will need

to set up PHP 5.x.x as described in the following sections:

Configure PHP (page 36)

Compile the SQL PHP Extension (page 38)

Run the SQL PHP Tutorials with Linux/Unix Apache (page 40)


Configure PHP

PHP is included in many common Linux and Unix distributions. The latest version of PHP can be

downloaded from the PHP website http://www.php.net/downloads.php.

To configure PHP to run c-treeACE SQL PHP follow these steps:

1. Open php.ini with your favorite text editor. In most installations you will find php.ini in /etc/php5/apache2/php.ini.

2. Search for extension_dir.

• If this line is commented (; on the beginning of the line) un-comment and replace the

contents of the quotes with your c-treeACE SQL PHP extensions directory.

• If this line is not commented, it's better to copy ctsql.so into your default PHP extensions

directory.

3. Search for extensions area and add extension=ctsql.so to configure the c-treeACE SQL

PHP module into your PHP:




4. Save changes to php.ini and close your text editor.

5. From the root shell restart your web server with the following command: /etc/init.d/apache2 restart


Compile the SQL PHP Extension (Linux/Unix)

Requrements:

PHP4 or PHP5 development package

Perl

Autoconf

Automake

GNU m4

C++ Compiler

Step 1: Create Configuration Script

Move to the sdk/sql.php/src directory under your installation directory.

Run the phpize command to create configuration script:

phpize

Step 2: Configure and Build

Run the configure script to create the makefile containing the instructions to build the c-treeACE

PHP extension:

./configure --with-pdo-ctsql

For the original PHP driver support

./configure --with-ctsql

Build c-treeACE PHP extension using make:

make

Step 3: Install (Optional)

If you want to install the c-treeACE PHP extension into your PHP installation extensions directory,

run make install as root user.

Switch to root user:

su

[Enter your root password]

Run the installer:

make install

Note: If you install using make install make sure php.ini is configured to load extensions from the PHP installation extensions directory.



Note: If you have a configure script with installed Autotools, follow these steps: > libtoolize > aclocal > autoreconf -i > phpize > ./configure --with-ctsql or --with-pdo-ctsql


Run the SQL PHP Tutorials with Linux/Unix Apache

To execute the SQL PHP tutorials, copy the tutorials files into a directory accessible to your web

server (here we use the web server root directory) as shown below:

1. Open a root shell and move to /var/www/ and copy the contents of the <your-API-folder>/tutorials/ directory in your installation directory:

debian:~# cd /var/www/

debian:/var/www# cp -v

<FairCom-Folder>\drivers/<your-API-folder>/tutorials/* .

(You will need to adjust the path based on your installation directory.)



2. Make sure c-treeACE SQL is running.

3. Open your favorite web browser and connect to http://localhost/index.htm (make sure you are using a proper URL if you did not use the web server root directory). You should see the index.htm page with hyperlinks to the three tutorials to be executed:

4. Click the tutorials hyperlinks to execute the tutorials:


5. Using PHP with ODBC

Note: This chapter explains how to use the c-treeACE ODBC to access PHP. If you prefer native PHP access using the PHP PDO (PHP Data Object) extension, see Using PHP 7 with the PDO Extension (page 6).

c-treeACE PHP can be installed and run under both IIS on Microsoft Windows and Apache on

Linux/Unix. Follow one of the links below for your platform of choice.

Using PHP on Windows (page 42)

Using PHP on Linux and Unix (page 48)

Also in this chapter:

Set Up the ODBC Data Source (page 51)

5.1 Using PHP on Windows

To use the PHP IIS server extensions, install PHP on your computer and use the c-treeACE

ODBC interface to connect PHP to c-tree.

c-treeACE PHP PDO supports PHP 7 and later using PDO objects.

Note: The original c-treeACE PHP API only supports PHP 5 and is not compatible with PHP.

Packages Required for Windows

To install and execute the c-treeACE PHP tutorials with Microsoft IIS, you will need to install

Internet Information Service (IIS) and PHP, as described in the following sections:

Install IIS (page 7)

Install PHP (page 45)

Configure IIS (page 12)

Note: c-treeACE SQL PHP PDO is only supported in PHP 7.

Using PHP with ODBC


Install Microsoft IIS

To install Internet Information Service (IIS) web server on Microsoft Windows, follow these

instructions:

Note: This section shows typical procedures using Windows 7 as an example. Some of the dialog and labels may look different in other versions of Windows.

1. Open the Windows Control Panel (Usually Start Menu > Control Panel) and select Programs:

2. In the program menu, select Turn Windows features on and off:

Using PHP with ODBC


3. Wait for the content of the Windows Features window to appear and check Internet Information Services.

4. Expand Internet Information Services > World Wide Web Services > Application Development Features and check CGI:

5. Click OK to begin the installation of IIS.

Using PHP with ODBC


Install PHP

This section explains how to install the PHP extensions for IIS. These procedures can be used

with all recent versions of PHP: PHP 4, PHP 5, and PHP 7.

1. Open your web browser and go to http://www.php.net/downloads.php http://www.php.net/downloads.php and download the Windows Binaries zip package for the latest PHP version:

2. Once you have downloaded the file, right-click it, select Extract All, enter C:\php as the destination, and click Extract:


Using PHP with ODBC


Configure Microsoft IIS

To configure IIS for PHP, follow these steps:

Note: This section shows typical procedures using Windows 7 as an example. Some of the dialog

and labels may look different in other versions of Windows.

1. Open the Start Menu, select Run, and execute InetMgr.exe:

2. In the InetMgr main window, double-click Handler Mappings:

3. In the Handler Mappings window, click Add Module Mapping... on the right-side Actions menu:

Using PHP with ODBC


4. Complete the dialog window with the following: Request Path: *.php Module: FastCgiModule Executable: C:\php\php-cgi.exe Name: PHP

5. Click OK and then Yes on the "Add Script Map" message box that appears. Finally, close the InetMgr dialog.

6. Restart your computer to ensure everything is configured.

Using PHP with ODBC


Note: It is not mandatory to restart your computer at this time, however, it is advised to ensure IIS is properly configured.

5.2 Using PHP on Linux and Unix

To install and execute c-treeACE PHP tutorials on Linux/Unix, please consider using the package

manager of the platform to avoid system settings errors.

In this section we list the commands using the Linux Ubuntu as an example. The commands

described here may vary depending on your environment.

You will need to install ODBC, PHP 7.x.x, and the Apache web server as described in the

following sections:

Install PHP (page 49)

Install the Web Server (page 49)

Install unixODBC

To install the ODBC on Linux you must use your package manager on Linux:

sudo apt install unixodbc

Once you complete the installation on your environment, set the c-treeACE ODBC Driver as

described in the FairCom ODBC Driver Guide in the topic titled Unix/Linux ODBC Managers

http://docs.faircom.com/doc/odbc/59603.htm.

In our example the odbcinst.ini is:

[ctreeSQL]

Driver=/usr/lib/odbc/libctodbc.so

Description=ODBC for ctreeSQL

Host=localhost

Database=ctreeSQL

The odbc.ini is:

[c-treeACE ODBC Driver]

Driver=ctreeSQL

Host=localhost

Database=ctreeSQL

User ID=ADMIN

Password=ADMIN

Service=6597

Description=ODBC for ctreeSQL

To allow the unixODBC install the odbcinst and odcini you must execute the following commands:

odbcinst -i -d -f /etc/odbcinst.ini

odbcinst -i -s -l -f /etc/odbc.ini

You can test if your DSN is installed by executing:

odbcinst -s –q

Result: [c-treeACE ODBC Driver]

http://docs.faircom.com/doc/odbc/59603.htm

Using PHP with ODBC


Please consider to set ODBCINI on environment variables:

export ODBCINI=/etc/odbc.ini

Now you can check if you unixODBC is configured for c-tree by running a tool connected to a

unixODBC data source. For example, you can execute the Interactive SQL (isql) from /usr/bin as

shown below:

Install PHP

PHP is included in many common Linux and Unix distributions. If it is not installed, it is best to

install PHP on your system using the package manager, for example:

sudo apt install php php-odbc

sudo apt install php-fpm

To configure FastCGI, type the following command (this example uses the nano text editor):

sudo nano /etc/php/7.0/fpm/php.ini

Edit the php.ini file to find:

cgi.fix_pathinfo

And set it to:

cgi.fix_pathinfo=0

To restart the service:

sudo service php7.0-fpm restart

Note: PHP 4, PHP 5, or PHP 7 will work with the c-treeACE ODBC interface. The c-treeACE PHP interface that is integrated with c-tree only supports PHP 5.

Install the Web Server

You must install the web server you wish to use with PHP. For example, to install the NGINX web

server:

sudo apt install nginx

Copy the FairCom tutorials to the folder: /var/www/html

Configure the web server to run PHP fastCGI:

sudo nano /etc/nginx/sites-available/default

In the text editor, find the following:

location ~ \.php$ {

Using PHP with ODBC


The lines below it provide examples of fastCGI configurations. Delete comment character “#”

from the appropriate line to allow fastcgi_pass to be used, as shown below:

Restart the web server as follows:

sudo service nginx restart

Introductory Tutorial


5.3 Set Up the ODBC Data Source

To execute the c-treeACE PHP tutorials with ODBC, be sure to have installed and configured the

c-treeACE ODBC driver. Below is an example of a configured driver on the Windows platform:

6. Introductory Tutorial

<your-API-folder>\tutorials\PHP_Tutorial1.php

This tutorial will take you through the basic use of the c-treeACE PHP Interface.

Like all other examples in the c-tree tutorial series, this tutorial simplifies the creation and use of a

database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() !

Note: The code shown in this section is found in the version of the tutorial that uses the c-treeACE sql.php API. If you are using the c-treeACE ODBC API to interface with PHP, the general flow of the tutorial will be the same, but the specifics will differ in some places due to the differences between sql.php and ODBC. Consult the source code for the specific version of the tutorial you are using for the exact coding techniques.



Tutorial #1: Introductory - Simple Single Table

We wanted to keep this program as simple as possible. This program does the following:

Initialize() - Connects to the c-treeACE Database Engine.

Define() - Defines and creates a "customer master" (custmast) table/file.

Manage() - Adds a few rows/records; Reads the rows/records back from the database;

displays the column/field content; and then deletes the rows/records.


Note our simple PHP script:

<?php

print("<html>\n");

print("<head>\n");

print("\t<title>PHP Tutorial 1</title>\n");

print("</head>\n");

print("<body>\n");

//

// Implementation of the concept of "init, define, manage and you're done..."

//

$session = Initialize();

Defines($session);

Manage($session);

Done($session);

We suggest opening the source code with your own editor.

Continue now to review these four steps.

6.1 Init

First we need to open a connection to a database by providing the c-treeACE Database Engine

with a user name, password and the database name.

Below is the code for Initialize():

//

// Initialize()

//

// Perform the minimum requirement of logging onto the c-tree Server

//

function Initialize() {

print("\t<h4>INIT</h4>\n");

// connect to server

print("\t\tLogon to server...<br>\n");

$ses = ctsql_connect("localhost:ctreeSQL", "admin", "ADMIN");

if (!$ses)

Handle_Error("ctsql_connect()");



return ($ses);

}

6.2 Define

The define step is where specific data definitions are established by your application and/or

process. This involves defining columns/fields and creating the tables/files with optional indices.

Below is the code for Define():

//

// Define()

//

// Create the table for containing a list of existing customers

//

function Defines($ses) {

print("\t<h4>DEFINE</h4>\n");

// create table

print("\t\tCreate table...<br>\n");

$qry = ctsql_query(

"CREATE TABLE custmast (

cm_custnumb CHAR(4),

cm_custzipc CHAR(9),

cm_custstat CHAR(2),

cm_custrtng CHAR(1),

cm_custname VARCHAR(47),

cm_custaddr VARCHAR(47),

cm_custcity VARCHAR(47))",

$ses);

if (!$qry)

Handle_Error("ctsql_query(CREATE TABLE)");

if (!ctsql_commit($ses))

Handle_Error("ctsql_commit()");

}

6.3 Manage

The manage step provides data management functionality for your application and/or process.

Below is the code for Manage():

//

// Manage()

//



// This function performs simple record functions of add, delete and gets

//

function Manage($ses) {

print("\t<h4>MANAGE</h4>\n");

// delete any existing records

Delete_Records($ses);

// populate the table with data

Add_Records($ses);

// display contents of table

Display_Records($ses);

}

//

// Delete_Records()

//

// This function deletes all the records in the table

//

function Delete_Records ($ses) {

print("\t\tDelete records...<br>\n");

$qry = ctsql_query("DELETE FROM custmast", $ses);

if (!$qry)

if (100 == ctsql_errno())

return;

else

Handle_Error("ctsql_query(DELETE)");



}

//

// Add_Records()

//

// This function adds records to a table in the database from an

// array of strings

//

function Add_Records ($ses) {

print("\t\tAdd records...<br>\n");

$data = array(

"('1000','92867','CA','1','Bryan Williams','2999 Regency','Orange')",

"('1001','61434','CT','1','Michael Jordan','13 Main','Harford')",

"('1002','73677','GA','1','Joshua Brown','4356 Cambridge','Atlanta')",

"('1003','10034','MO','1','Keyon Dooling','19771 Park Avenue','Columbia')"

);

foreach ($data as $values) {

$qry = ctsql_query("INSERT INTO custmast VALUES $values", $ses);

if (!$qry)

Handle_Error("ctsql_query(INSERT)");

}





}

//

// Display_Records()

//

// This function displays the contents of a table.

//

function Display_Records ($ses) {

print("\t\tDisplay records...<br>\n");

$qry = ctsql_query("SELECT cm_custnumb \"Number\", cm_custname \"Name\" FROM custmast",

$ses);

if (!is_resource($qry))

Handle_Error("ctsql_query(SELECT)");

else {

print("\t\t<TABLE border=1>\n\t\t\t<TR><TH>Number</TH><TH>Name</TH></TR>\n");

while ($values = ctsql_fetch_row($qry)) {

print("\t\t\t<TR>");

foreach ($values as $content) {

if (is_null($content))

print ("<TD>NULL</TD>");

else

print ("<TD>$content</TD>");

}

print("</TR>\n");

}

print("\t\t</TABLE>\n");

if (ctsql_errno())

Handle_Error("ctsql_fetch_row()");

ctsql_free_result($qry);

}

}

6.4 Done

When an application and/or process has completed operations with the database, it must release

resources by disconnecting from the database engine.

Below is the code for Done():

//

// Done()

//

// This function handles the housekeeping of closing, freeing,

// disconnecting and logging out of the database

//

function Done ($ses) {

print("\t<h4>DONE</h4>\n");

Relationships


// logout

print("\t\tLogout...<br>\n");

ctsql_close($ses);

}

6.5 Additional Resources

We encourage you to explore the additional resources listed here:

Complete source code for this tutorial can be found in PHP_Tutorial1.php in your installation

directory, within the <Your-API-Folder>\tutorials directory for your platform.

Additional documentation may be found on the FairCom Web site at: www.faircom.com

7. Relationships



Now we will build some table/file relationships using the c-treeACE PHP Interface.

This tutorial will advance the concepts introduced in the first tutorial by expanding the number of

tables. We will define key columns/fields and create specific indices for each table to form a

relational model database.


database into four simple steps: Initialize(), Define(), Manage(), and You’re Done() !

Relationships


Tutorial #2: Relational Model and Indexing

Here we add a bit more complexity, introducing multiple tables, with related indices in order to

form a simple "relational" database simulating an Order Entry system. Here is an overview of

what will be created:


Define() - Defines and creates the "custmast", "custordr", "ordritem" and the

"itemmast" tables/files with related indices.

Manage() - Adds some related rows/records to all tables/files. Then queries the

database.



<?php

print("<html>\n");

print("<head>\n");


print("</head>\n");

print("<body>\n");

//


//


Defines($session);

Manage($session);

Done($session);



Relationships


7.1 Init




//

// Initialize()

//


//






if (!$ses)


return ($ses);

}

7.2 Define




//

// Define()

//

// Create the tables

//



Create_CustomerMaster_Table($ses);

Create_CustomerOrders_Table($ses);

Create_OrderItems_Table($ses);

Create_ItemMaster_Table($ses);



}

Relationships


//

// Create_CustomerMaster_Table()

//

// Create the table CustomerMaster

//

function Create_CustomerMaster_Table ($ses) {

print("\t\ttable CustomerMaster<br>\n");

$qry = ctsql_query(









$ses);

if (!$qry)


$qry = ctsql_query(

"CREATE UNIQUE INDEX cm_custnumb_idx ON custmast (cm_custnumb)",

$ses);

if (!$qry)

Handle_Error("ctsql_query(CREATE INDEX)");

}

//

// Create_CustomerOrders_Table()

//

// Create the table CustomerOrders

//

function Create_CustomerOrders_Table ($ses) {

print("\t\ttable CustomerOrders<br>\n");

$qry = ctsql_query(

"CREATE TABLE custordr (

co_ordrdate DATE,

co_promdate DATE,

co_ordrnumb CHAR(6),

co_custnumb CHAR(4))",

$ses);

if (!$qry)


$qry = ctsql_query(

"CREATE UNIQUE INDEX co_ordrnumb_idx ON custordr (co_ordrnumb)",

$ses);

if (!$qry)


$qry = ctsql_query(

"CREATE INDEX co_custnumb_idx ON custordr (co_custnumb)",

$ses);

if (!$qry)


}

Relationships


//

// Create_OrderItems_Table()

//

// Create the table OrderItems

//

function Create_OrderItems_Table ($ses) {

print("\t\ttable OrderItems<br>\n");

$qry = ctsql_query(

"CREATE TABLE ordritem (

oi_sequnumb SMALLINT,

oi_quantity SMALLINT,

oi_ordrnumb CHAR(6),

oi_itemnumb CHAR(5))",

$ses);

if (!$qry)


$qry = ctsql_query(

"CREATE UNIQUE INDEX oi_ordrnumb_idx ON ordritem (oi_ordrnumb, oi_sequnumb)",

$ses);

if (!$qry)


$qry = ctsql_query(

"CREATE INDEX oi_itemnumb_idx ON ordritem (oi_itemnumb)",

$ses);

if (!$qry)


}

//

// Create_ItemMaster_Table()

//

// Create the table ItemMaster

//

function Create_ItemMaster_Table ($ses) {

print("\t\ttable ItemMaster<br>\n");

$qry = ctsql_query(

"CREATE TABLE itemmast (

im_itemwght INTEGER,

im_itempric MONEY,

im_itemnumb CHAR(5),

im_itemdesc VARCHAR(47))",

$ses);

if (!$qry)


$qry = ctsql_query(

"CREATE UNIQUE INDEX im_itemnumb_idx ON itemmast (im_itemnumb)",

$ses);

if (!$qry)


}

Relationships


7.3 Manage



//

// Manage()

//

// Populates table and performs a simple query

//



// populate the tables with data

Add_CustomerMaster_Records($ses);

Add_CustomerOrders_Records($ses);

Add_OrderItems_Records($ses);

Add_ItemMaster_Records($ses);



// perform a query:

// list customer name and total amount per order

// name total

// @@@@@@@@@@@@@ $xx.xx

// for each order in the CustomerOrders table

// fetch order number

// fetch customer number

// fetch name from CustomerMaster table based on customer number

// for each order item in OrderItems table

// fetch item quantity

// fetch item number

// fetch item price from ItemMaster table based on item number

// next

// next

$qry = ctsql_query(

"SELECT cm_custname \"Name\", SUM(im_itempric * oi_quantity) \"Total\"" .

"FROM custmast, custordr, ordritem, itemmast " .

"WHERE co_custnumb = cm_custnumb AND co_ordrnumb = oi_ordrnumb AND oi_itemnumb =

im_itemnumb " .

"GROUP BY cm_custnumb, cm_custname",

$ses);



else {

print("\t\t<TABLE border=1>\n\t\t\t<TR><TH>Name</TH><TH>Total</TH></TR>\n");




Relationships




else


}

print("</TR>\n");

}


if (ctsql_errno())



}

}

//

// Add_CustomerMaster_Records()

//

// This function adds records to table CustomerMaster from an

// array of strings

//

function Add_CustomerMaster_Records ($ses) {

print("\t\tAdd records in table CustomerMaster...<br>\n");

$data = array(





);

Delete_Records($ses, "custmast");



if (!$qry)


}



}

//

// Add_CustomerOrders_Records()

//

// This function adds records to table CustomerOrders from an

// array of strings

//

function Add_CustomerOrders_Records ($ses) {

print("\t\tAdd records in table CustomerOrders...<br>\n");

$data = array(

"('09/01/2002','09/05/2002','1','1001')",

"('09/02/2002','09/06/2002','2','1002')"

);

Delete_Records($ses, "custordr");

Relationships



$qry = ctsql_query("INSERT INTO custordr VALUES $values", $ses);

if (!$qry)


}



}

//

// Add_OrderItems_Records()

//

// This function adds records to table OrderItems from an

// array of strings

//

function Add_OrderItems_Records ($ses) {

print("\t\tAdd records in table OrderItems...<br>\n");

$data = array(

"(1,2,'1','1')",

"(2,1,'1','2')",

"(3,1,'1','3')",

"(1,3,'2','3')"

);

Delete_Records($ses, "ordritem");


$qry = ctsql_query("INSERT INTO ordritem VALUES $values", $ses);

if (!$qry)


}



}

//

// Add_ItemMaster_Records()

//

// This function adds records to table ItemMaster from an

// array of strings

//

function Add_ItemMaster_Records ($ses) {

print("\t\tAdd records in table ItemMaster...<br>\n");

$data = array(

"(10,19.95,'1','Hammer')",

"(3, 9.99,'2','Wrench')",

"(4, 16.59,'3','Saw')",

"(1, 3.98,'4','Pliers')"

);

Delete_Records($ses, "itemmast");


$qry = ctsql_query("INSERT INTO itemmast VALUES $values", $ses);

Relationships


if (!$qry)


}



}

//

// Delete_Records()

//

// This function deletes all the records in a tables

//

function Delete_Records ($ses, $table) {


$qry = ctsql_query("DELETE FROM $table", $ses);

if (!$qry)


return;

else




}

7.4 Done




//

// Done()

//



//



// logout


ctsql_close($ses);

}



Record/Row Locking





8. Record/Row Locking



Now we will explore row/record locks using the c-treeACE PHP Interface.

The functionality for this tutorial focuses on inserting/adding rows/records, then updating a single

row/record in the customer master table under locking control. The application will pause after a

LOCK is placed on a row/record. Another instance of this application should then be launched,

which will block, waiting on the lock held by the first instance. Pressing the <Enter> key will

enable the first instance to proceed. This will result in removing the lock thereby allowing the

second instance to continue execution. Launching two processes provides a visual demonstration

of the effects of locking and a basis for experimentation on your own.


database into four simple steps: Initialize(), Define(), Manage(), and you’re Done() !

Tutorial #3: Locking

Here we demonstrate the enforcement of data integrity by introducing record/row "locking".


Define() - Defines and creates a "customer master" (custmast) table/file.

Manage() - Adds a few rows/records; Reads the rows/records back from the database;

displays the column/field content. Then demonstrates an update operation under locking

control, and a scenario that shows a locking conflict.



<?php

print("<html>\n");

print("<head>\n");


print("</head>\n");

print("<body>\n");

//


Record/Row Locking


//


Defines($session);

Manage($session);

Done($session);



8.1 Init




//

// Initialize()

//


//


echo "<h4>INIT</h4>\n";



if (!$ses)


return ($ses);

}

8.2 Define




//

// Define()

//

// Create the table for containing a list of existing customers

//

Record/Row Locking



echo "<h4>DEFINE</h4>\n";

$qry = ctsql_query(









$ses);

if (!$qry)


$qry = ctsql_query(

"CREATE UNIQUE INDEX cm_custnumb_idx ON custmast (cm_custnumb)",

$ses);

if (!$qry)




}

8.3 Manage



//

// Manage()

//

// This function performs simple record functions of add, delete and gets

//


echo "<h4>MANAGE</h4>\n";

// delete any existing records

Delete_Records($ses);

// populate the table with data


// display contents of table


// update a record under locking control

Update_CustomerMaster_Record($ses);

// display again after update and effects of lock


Record/Row Locking


}

//

// Delete_Records()

//

// This function deletes all the records in the table

//

function Delete_Records ($ses) {

echo "Delete records...<br>\n";

$qry = ctsql_query("DELETE FROM custmast", $ses);

if (!$qry)


return;

else




}

//


//


// array of strings

//


echo "Add records...<br>\n";

$data = array(





);



if (!$qry)


}



}

//

// Display_Records()

//

// This function displays the contents of a table.

//

function Display_Records ($ses) {

echo "Display records...<br>\n";

$qry = ctsql_query("SELECT cm_custnumb \"Number\", cm_custname \"Name\" FROM custmast",

$ses);


Record/Row Locking



else {

print("<TABLE border=1><TR><TH>Number</TH><TH>Name</TH></TR>\n");


print("<TR>");




else


}

print("</TR>\n");

}

print("</TABLE>\n");

if (ctsql_errno())



}

}

//

// Update_CustomerMaster_Records()

//

// Update one record under locking control to demonstrate the effects

// of locking

//

function Update_CustomerMaster_Records ($ses) {

echo "Display records...<br>\n";

}

8.4 Done




//

// Done()

//



//


echo "<h4>DONE</h4>\n";

// logout

ctsql_close($ses);

}

Transaction Processing







9. Transaction Processing



Now we will discuss transaction processing as it relates to the c-treeACE PHP Interface.

Transaction processing provides a safe method by which multiple database operations spread

across separate tables/files are guaranteed to be atomic. By atomic, we mean that, within a

transaction, either all of the operations succeed or none of the operations succeed. This "either

all or none" atomicity ensures that the integrity of the data in related tables/files is secure.


database into four simple steps: Initialize(), Define(), Manage(), and You’re Done()!

Tutorial #4: Transaction Processing

Here we demonstrate transaction control.


Define() - Defines and creates our four tables/files.

Manage() - Adds rows/records to multiple tables/files under transaction control.



<?php

print("<html>\n");

print("<head>\n");


print("</head>\n");

print("<body>\n");

//


//




Defines($session);

Manage($session);

Done($session);



9.1 Init




//

// Initialize()

//


//






if (!$ses)


return ($ses);

}

9.2 Define




//

// Define()

//

// Create the tables

//





// delete tables ...

Delete_Tables($ses);

// ...and re-create them with constraints

Create_CustomerMaster_Table($ses);

Create_CustomerOrders_Table($ses);

Create_OrderItems_Table($ses);

Create_ItemMaster_Table($ses);



}

//

// Create_CustomerMaster_Table()

//

// Create the table CustomerMaster

//

function Create_CustomerMaster_Table ($ses) {

print("\t\ttable CustomerMaster<br>\n");

$qry = ctsql_query(


cm_custnumb CHAR(4) PRIMARY KEY,







$ses);

if (!$qry)


}

//

// Create_CustomerOrders_Table()

//

// Create the table CustomerOrders

//

function Create_CustomerOrders_Table ($ses) {

print("\t\ttable CustomerOrders<br>\n");

$qry = ctsql_query(

"CREATE TABLE custordr (

co_ordrdate DATE,

co_promdate DATE,

co_ordrnumb CHAR(6) PRIMARY KEY,

co_custnumb CHAR(4),

FOREIGN KEY (co_custnumb) REFERENCES custmast)",

$ses);

if (!$qry)


}

//

// Create_OrderItems_Table()



//

// Create the table OrderItems

//

function Create_OrderItems_Table ($ses) {

print("\t\ttable OrderItems<br>\n");

$qry = ctsql_query(

"CREATE TABLE ordritem (

oi_sequnumb SMALLINT,

oi_quantity SMALLINT,

oi_ordrnumb CHAR(6),

oi_itemnumb CHAR(5),

FOREIGN KEY (oi_itemnumb) REFERENCES itemmast,

FOREIGN KEY (oi_ordrnumb) REFERENCES custordr)",

$ses);

if (!$qry)


}

//

// Create_ItemMaster_Table()

//

// Create the table ItemMaster

//

function Create_ItemMaster_Table ($ses) {

print("\t\ttable ItemMaster<br>\n");

$qry = ctsql_query(

"CREATE TABLE itemmast (

im_itemwght INTEGER,

im_itempric MONEY,

im_itemnumb CHAR(5) PRIMARY KEY,

im_itemdesc VARCHAR(47))",

$ses);

if (!$qry)


}

9.3 Manage



//

// Manage()

//

// Populates table and perform a simple query

//



// populate the tables with data




Add_ItemMaster_Records($ses);

Add_Transactions($ses);

// display the orders and their items

Display_CustomerOrders($ses);

Display_OrderItems($ses);

}

//

// Delete_Tables()

//

// This function removes all existing tables

//

function Delete_Tables ($ses) {

$qry = ctsql_query("DROP TABLE ordritem", $ses);

if (!$qry)

Handle_Error("ctsql_query(DROP TABLE)");

$qry = ctsql_query("DROP TABLE custordr", $ses);

if (!$qry)


$qry = ctsql_query("DROP TABLE custmast", $ses);

if (!$qry)


$qry = ctsql_query("DROP TABLE itemmast", $ses);

if (!$qry)


}

//


//


// array of strings

//


print("\t\tAdd records in table CustomerMaster...<br>\n");

$data = array(





);



if (!$qry)


}



}



//

// Add_ItemMaster_Records()

//

// This function adds records to table ItemMaster from an

// array of strings

//

function Add_ItemMaster_Records ($ses) {

print("\t\tAdd records in table ItemMaster...<br>\n");

$data = array(

"(10,19.95,'1','Hammer')",

"(3, 9.99,'2','Wrench')",

"(4, 16.59,'3','Saw')",

"(1, 3.98,'4','Pliers')"

);


$qry = ctsql_query("INSERT INTO itemmast VALUES $values", $ses);

if (!$qry)


}



}

//

// Add_Transactions()

//

// Add an Order and associated Items "as a transaction" to their

// respective tables. A transaction is committed or aborted if the

// customer number on the order is confirmed valid. Likewise each

// item in the order is verified to be a valid item.

//

function Add_Transactions ($ses) {

print("\t\tAdd transaction records...<br>\n");

$orders = array(

array(

'ordrdate' => '09/01/2002',

'promdate' => '09/05/2002',

'ordrnumb' => '1',

'custnumb' => '1001'

),

array(

'ordrdate' => '09/02/2002',

'promdate' => '09/06/2002',

'ordrnumb' => '2',

'custnumb' => '9999' // bad customer number

),

array(

'ordrdate' => '09/22/2002',

'promdate' => '09/26/2002',

'ordrnumb' => '3',

'custnumb' => '1003'

)

);

$items = array(

array(



'ordrnumb' => '1',

'sequnumb' => '1',

'quantity' => '2',

'itemnumb' => '1'

),

array(

'ordrnumb' => '1',

'sequnumb' => '2',

'quantity' => '1',

'itemnumb' => '2'

),

array(

'ordrnumb' => '2',

'sequnumb' => '1',

'quantity' => '1',

'itemnumb' => '3'

),

array(

'ordrnumb' => '2',

'sequnumb' => '2',

'quantity' => '3',

'itemnumb' => '4'

),

array(

'ordrnumb' => '3',

'sequnumb' => '1',

'quantity' => '2',

'itemnumb' => '3'

),

array(

'ordrnumb' => '3',

'sequnumb' => '2',

'quantity' => '2',

'itemnumb' => '99' // bad item number

)

);

foreach ($orders as $order) {

// add order record

$qry = ctsql_query("INSERT INTO custordr VALUES (

'$order[ordrdate]',

'$order[promdate]',

'$order[ordrnumb]',

'$order[custnumb]')",

$ses);

if (!$qry)


foreach ($items as $item) {

// process order items

if ($item[ordrnumb] == $order[ordrnumb]) {

$qr2 = ctsql_query("INSERT INTO ordritem VALUES (

$item[sequnumb],

$item[quantity],

'$item[ordrnumb]',

'$item[itemnumb]')",

$ses);

if (!$qr2)


}

}



}



}

//

// Delete_Records()

//

// This function deletes all the records in a tables

//

function Delete_Records ($ses, $table) {


$qry = ctsql_query("DELETE FROM $table", $ses);

if (!$qry)


return;

else




}

//

// Display_CustomerOrders()

//

// This function displays the contents of CustomerOrders table.

//

function Display_CustomerOrders ($ses) {

print("\t\tCustomerOrders Table...<br>\n");

$qry = ctsql_query("SELECT co_ordrnumb \"Order\", co_custnumb \"Customer\" FROM custordr",

$ses);



else {

print("\t\t<TABLE border=1>\n\t\t\t<TR><TH>Order</TH><TH>Customer</TH></TR>\n");






else


}

print("</TR>\n");

}


if (ctsql_errno())



}

}



//

// Display_OrderItems()

//

// This function displays the contents of OrderItems table.

//

function Display_OrderItems ($ses) {

print("\t\tOrderItems Table...<br>\n");

$qry = ctsql_query("SELECT oi_ordrnumb \"Order\", oi_itemnumb \"Item\" FROM ordritem",

$ses);



else {

print("\t\t<TABLE border=1>\n\t\t\t<TR><TH>Order</TH><TH>Item</TH></TR>\n");






else


}

print("</TR>\n");

}


if (ctsql_errno())



}

}

9.4 Done




//

// Done()

//



//



Delete_Tables($ses);





// logout


ctsql_close($ses);

}







10. Additional Functionality

The introductory c-treeACE tutorials have offered a glimpse into the ease and flexibility c-treeACE

provides using only a few basic functions. The c-treeACE interfaces include a rich array of

features for nearly any data management need, such as:

String handling

Currency handling

Date and Time handling

Index and Segment handling

...and many, many more.

FairCom c-treeACE provides a variety of APIs. To learn more about these APIs, see c-treeACE

Interfaces (https://docs.faircom.com/readme/v11_5/sdk/).

https://docs.faircom.com/readme/v11_5/sdk/


11. c-treeACE PHP Functions

In this section, we will be listing the c-treeACE PHP functions in alphabetical order. The function

descriptions include some or all of the following sections:

Declaration

Function and parameter declarations.

Description

A detailed description of the function and parameters.

Parameter [in/out] detail.

Returns

Explanation of the common return values.

Example

A simple programming example.

See also

A list of related functions and other information.

11.1 Resource Types

There are two resource types used in the c-treeACE PHP module. The first is the connection

identifier for a c-treeACE SQL connection. The second resource holds the result of a query.

For example, the following code demonstrates how to connect to c-treeACE SQL, execute a

query, print resulting rows and disconnect from a c-treeACE SQL database:

c-treePHP Example

<?php

/* Connecting, selecting database */

$ses = ctsql_connect("ctreeSQL","ADMIN","ADMIN")

or die("Could not successfully connect to c-treeACE SQL: " . ctsql_error());

echo "Successfully connected to c-treeACE SQL!";

/* Performing SQL query */

$query = "SELECT * FROM my_table";

$result = ctsql_query($query) or die("Query failed : " . ctsql_error());

/* Printing results in HTML */

echo "<table>\n";

while ($line = ctsql_fetch_assoc($result)) {

echo "\t<tr>\n";

c-treeACE PHP Functions


foreach ($line as $col_value) {

echo "\t\t<td>$col_value</td>\n";

}

echo "\t</tr>\n";

}

echo "</table>\n";

/* Free resultset */

ctsql_free_result($result);

/* Closing connection */

ctsql_close($ses);

?>

11.2 c-treeACE PHP Example

<?php

/* Connecting, selecting database */

$ses = ctsql_connect("ctreeSQL","ADMIN","ADMIN")

or die("Could not successfully connect to c-treeACE SQL: " . ctsql_error());

echo "Successfully connected to c-treeACE SQL!";

/* Performing SQL query */

$query = "SELECT * FROM my_table";

$result = ctsql_query($query) or die("Query failed : " . ctsql_error());

/* Printing results in HTML */

echo "<table>\n";

while ($line = ctsql_fetch_assoc($result)) {

echo "\t<tr>\n";

foreach ($line as $col_value) {

echo "\t\t<td>$col_value</td>\n";

}

echo "\t</tr>\n";

}

echo "</table>\n";

/* Free resultset */


/* Closing connection */

ctsql_close($ses);

?>



ctsql_affected_rows

Returns the number of affected rows from the previous c-treePHP operation.

Declaration int ctsql_affected_rows ( [resource connectionID])

Description

ctsql_affected_rows() returns the number of rows affected by the last INSERT, UPDATE or

DELETE query. This will also work with the SELECT statement but only after fetching the rows.

Returns

ctsql_affected_rows() returns the number of rows affected by the last INSERT, UPDATE or

DELETE query associated with connectionID.

Example

<?php

/* connect to database */

$link = ctsql_connect('ctreeSQL', 'admin', 'ADMIN');

if (!$link) {

die('Failed to connect to c-treeACE SQL: ' . ctsql_error());

}

/* this should return the correct numbers of deleted records */

ctsql_query('DELETE FROM mytable WHERE age < 50');

printf("Records deleted: %d\n", ctsql_affected_rows());

/* with a where clause that is never true, it should return 0 */

ctsql_query('DELETE FROM mytable WHERE 0');


?>

The above example would produce the following output:

Records deleted: 10

Records deleted: 0



ctsql_close

Close a c-treePHP connection.

Declaration bool ctsql_close ( [resource connectionID])

Description

ctsql_close() closes the connection to c-treeACE SQL that is associated with the specified

connection identifier.

ctsql_close() is not usually necessary, as non-persistent open links are automatically closed at

the end of the script’s execution. Additional details on freeing resources can be found in the PHP

documentation.

Returns

Returns TRUE on success or FALSE on failure.

Example

<?php


if (!$link) {


}

echo 'Successfully connected to c-treeACE SQL';

ctsql_close($link);

?>

See also

ctsql_connect(), ctsql_pconnect().



ctsql_commit

Commit the current c-treePHP transaction.

Declaration bool ctsql_commit ([resource connectionID])

Description

Commits the current transaction for the database connection specified by the connectionID.

Returns




ctsql_connect

Open a connection to c-treeACE SQL

Declaration resource ctsql_connect ( [string dbname [, string username [, string password]]])

Description

ctsql_connect() establishes a connection to c-treeACE SQL.

The dbname parameter is formatted as one of the usual c-treeACE database names shown

below:

port#@hostname:database

port#@hostname

hostname:database

database (e.g. “6597@localhost:ctreeSQL”)

The link to the server will be closed as soon as the execution of the script ends, unless it’s closed

earlier by explicitly calling ctsql_close().

Returns

Returns a c-treePHP connection identifier on success, or FALSE on failure.

Example <?php


if (!$link) {


}

echo 'Successfully connected to c-treeACE SQL';

ctsql_close($link);

?>

See also

ctsql_pconnect(), ctsql_close().



ctsql_end_of_fetch

Returns if there are more rows to fetch.

Declaration bool ctsql_end_of_fetch ( resource QueryID )

Description

ctsql_end_of_fetch() indicates if there are more rows to fetch.

Returns

True if this is the last fetch; otherwise false.

Example

<?php

/* connect to database */


if (!$link) {


}

/* this should return the correct numbers of deleted records */

ctsql_query('DELETE FROM mytable WHERE age < 50');


/* with a where clause that is never true, it should return 0 */

ctsql_query('DELETE FROM mytable WHERE 0');


?>


Records deleted: 10

Records deleted: 0



ctsql_errno

Returns the numerical value of the error message from previous c-treePHP operation

Declaration int ctsql_errno ()

Returns

Returns the error number from the most recently executed c-treePHP function (not including

ctsql_error() and ctsql_errno()), or 0 (zero) if no error occurred.

Example

<?php

$link = ctsql_connect("ctreeSQL", "admin", "ADMIN");

if (!$link) {

echo ctsql_errno() . ": " . ctsql_error(). "\n";

}

if (!ctsql_query("SELECT * FROM nonexistenttable", $link)) {

echo ctsql_errno() . ": " . ctsql_error() . "\n";

}

?>

The above example would produce the following output if nonexistenttable does not exist:

-20005: Table/View/Synonym not found

See also

ctsql_error()



ctsql_error

Returns the text of the error message from previous c-treePHP operation.

Declaration string ctsql_error ()

Returns

Returns the error text from the most recently executed c-treePHP function, not including

ctsql_error() and ctsql_errno(). An empty string is returned if no error occurred.

Example

<?php

$link = ctsql_connect("ctreeSQL", "admin", "ADMIN");

if (!$link) {

echo ctsql_errno() . ": " . ctsql_error(). "\n";

}

if (!ctsql_query("SELECT * FROM nonexistenttable", $link)) {

echo ctsql_errno() . ": " . ctsql_error() . "\n";

}

?>


-20005: Table/View/Synonym not found

See also

ctsql_errno()



ctsql_fetch_array

Fetches a result row as both an associative array and a numeric array.

Declaration array ctsql_fetch_array ( resource queryID)

Description

ctsql_fetch_array() is an extended version of ctsql_fetch_row(). In addition to storing the data

in the numeric indexes of the result array, it also stores the data in associative indexes, using the

field names as keys.

If two or more columns of the result have the same field names, the last column will take

precedence. To access the other column(s) of the same name, you must use the numeric index

of the column or make an alias for the column. For aliased columns, you cannot access the

contents with the original column name (by using ‘field’ in the example given below).

This SELECT query demonstrates aliased duplicate field names:

SELECT table1.field AS foo, table2.field AS bar FROM table1, table2

It is important to note that while ctsql_fetch_row() may be slightly faster, ctsql_fetch_array()

provides a significant added benefit for the performance difference.

Note: Field names returned by this function are case-sensitive.

Returns

Returns an array that corresponds to the fetched row, or FALSE if there are no more rows.

Example

<?php

ctsql_connect("localhost:ctreeSQL") or


$result = ctsql_query("SELECT id, name FROM mytable");

while ($row = ctsql_fetch_array($result)) {

printf ("ID: %s Name: %s", $row[0], $row["name"]);

}


?>

See also

ctsql_fetch_row(), ctsql_fetch_assoc().



ctsql_fetch_assoc

Fetches a result row as an associative array.

Declaration array ctsql_fetch_assoc (resource queryID)

Description

ctsql_fetch_assoc() stores the data in associative indexes, using the field names as keys.

If two or more columns of the result have the same field names, the last column will take

precedence. To access the other column(s) of the same name, you either need to access the

result with numeric indexes by using ctsql_fetch_row() or add alias names. For aliased columns,

you cannot access the contents with the original column name (by using ‘field’ in this example).

This SELECT statement demonstrates a query with aliased duplicate field names

SELECT table1.field AS foo, table2.field AS bar FROM table1, table2


Returns


Example

<?php

ctsql_connect("localhost:ctreeSQL") or

die("Failed to connect to c-treeACE SQL: " . ctsql_error());

$result = ctsql_query("SELECT id, name FROM mytable");

while ($row = ctsql_fetch_assoc($result)) {

printf ("ID: %s Name: %s", $row["id"],$row["name"]);

}


?>

See also

ctsql_fetch_row(), ctsql_fetch_array().



ctsql_fetch_object

Fetches a result row as an object.

Declaration object ctsql_fetch_object ( resource queryID)

Description

ctsql_fetch_object() is similar to ctsql_fetch_array(), with one difference; an object is returned

instead of an array. Indirectly, this means you may only access the data by the field names, and

not with the offsets (a number is an illegal property name).


Comparing performance, this function is identical to ctsql_fetch_array(), and is approximately as

fast as ctsql_fetch_row().

Returns

Returns an object with properties that correspond to the fetched row, or FALSE if there are no

more rows.

Example

<?php

ctsql_connect("localhost:ctreeSQL");

$result = ctsql_query("select * from mytable");

while ($row = ctsql_fetch_object($result)) {

echo $row->user_id;

echo $row->fullname;

}


?>

See also

ctsql_fetch_array(), ctsql_fetch_assoc(), ctsql_fetch_row().



ctsql_fetch_row

Returns a result row as an enumerated array.

Declaration array ctsql_fetch_row ( resource queryID)

Description

ctsql_fetch_row() will fetch one row of data from the result associated with the specified query

identifier. The row is returned as an array. Each result column is stored in an array offset, starting

at offset 0.

Subsequent calls to ctsql_fetch_row() return the next row in the result set, or FALSE if there are

no more rows.

Returns


See also

ctsql_fetch_array(), ctsql_fetch_assoc(), ctsql_fetch_object().



ctsql_field_len

Returns the length of the specified field.

Declaration int ctsql_field_len ( resource queryID , int field_offset )

Returns

Returns the length of the specified field.



ctsql_field_name

Returns the name of the specified field in a result.

Declaration string ctsql_field_name ( resource queryID , int field_offset )

Description

field_index starts at 0. For example, the index of the third field is 2, the index of the fourth field is

3, etc.


Returns

ctsql_field_name() returns the name of the specified field index. queryID must be a valid query

identifier and field_index is the numerical offset of the field.



ctsql_field_table

Returns the name of the table containing the specified field.

Declaration string ctsql_field_table ( resource queryID , int field_offset )

Returns

Returns the name of the table containing the specified field.

Example

<?php



printf ("Table containing field ID is:", ctsql_field_table($result, 1));


?>



ctsql_field_type

Returns the type of the specified field in a result.

Declaration string ctsql_field_type ( resource queryID , int field_offset )

Description

ctsql_field_type() is similar to ctsql_field_name(). The arguments are identical, but the field

type is returned instead. The field type will be one of “int”, “real”, “string”, and others as detailed in

c-treeACE SQL documentation.

Example

<?php



printf ("Field ID has type: ", ctsql_field_type($result, 1));


?>



ctsql_free_result

Frees the result memory for a query.

Declaration bool ctsql_free_result ( resource queryID)

Description

ctsql_free_result() is only necessary if you are concerned about how much memory is used for

queries that return large result sets. All associated result memory is automatically freed at the end

of the script’s execution.

ctsql_free_result() will free all memory associated with the result identifier queryID.

Returns




ctsql_num_fields

Returns the number of fields in result.

Declaration int ctsql_num_fields (resource queryID)

Returns

ctsql_num_fields() returns the number of fields in the result set queryID.

See also

ctsql_query()



ctsql_pconnect

Opens a permanent connection to c-treeACE SQL

Declaration resource ctsql_pconnect ( [string dbname [, string username [, string password]]])

Returns

Returns a c-treePHP connection identifier on success, or FALSE on failure.

Note: Currently, this functionality is not available in c-treePHP and this function behaves exactly as ctsql_connect().



ctsql_query

Sends a query to c-treeACE SQL.

Declaration resource ctsql_query ( string query [, resource connectionID])

Description

ctsql_query() sends a query to the currently active database on the server that’s associated with

the specified connection identifier. If connectionID isn’t specified, the last used link is assumed.

The query result is buffered. The buffer size is controlled trough the ctsql.rowsperfetch runtime

configuration value. The rows in the buffer are updated when one of the ctsql_fetch..() functions

reaches the end of the buffer.

Note: The query string should not end with a semicolon.

Only for SELECT statements ctsql_query() returns a queryID or FALSE if the query was not

executed correctly. For other type of c-treeACE SQL statements, ctsql_query() returns TRUE on

success and FALSE on error. A non-FALSE return value means that the query was legal and

could be executed by the server. It does not indicate anything about the number of rows affected

or returned. It is perfectly possible for a query to succeed but affect no rows or return no rows.

Assuming the query succeeds, you can call ctsql_affected_rows() to find out how many rows

were affected by a DELETE, INSERT, REPLACE, or UPDATE statement.

Only for SELECT, ctsql_query() returns a new result identifier which you then pass to

ctsql_fetch_array() and other functions dealing with result tables. When you are finished with the

result set, you then free the resources associated with it by calling ctsql_free_result(). This

memory is also automatically freed at the end of the script’s execution.

See also

ctsql_affected_rows(), ctsql_free_result(), ctsql_fetch_array(), ctsql_fetch_row(),

ctsql_fetch_assoc(), ctsql_connect().



ctsql_rollback

Rolls back the current open transaction.

Declaration bool ctsql_rollback ( [resource connectionID])

Description

Rolls back the current transaction for the database specified by the connectionID parameter.

Returns


See also

ctsql_commit()

FairCom Typographical Conventions

Before you begin using this guide, be sure to review the relevant terms and typographical

conventions used in the documentation.

The following formatted items identify special information.

Formatting convention Type of Information

Bold Used to emphasize a point or for variable expressions such as parameters

CAPITALS Names of keys on the keyboard. For example, SHIFT, CTRL, or ALT+F4

FairCom Terminology FairCom technology term

FunctionName() c-treeACE Function name

Parameter c-treeACE Function Parameter

Code Example Code example or Command line usage

utility c-treeACE executable or utility

filename c-treeACE file or path name

CONFIGURATION KEYWORD c-treeACE Configuration Keyword

CTREE_ERR c-treeACE Error Code

All Rights Reserved civ www.faircom.com

Copyright Notice

Copyright © 1992-2020 FairCom USA. All rights reserved.

No part of this publication may be stored in a retrieval system, or transmitted in any form or by any means, electronic,

mechanical, photocopying, recording or otherwise without the prior written permission of FairCom USA. Printed in the

United States of America.

Information in this document is subject to change without notice.

Trademarks

c-treeACE, c-treeRTG, c-treeEDGE, c-treeAMS, c-tree Plus, c-tree, r-tree, FairCom, and FairCom’s circular disc logo are

trademarks of FairCom USA, registered in the United States and other countries.

The following are third-party trademarks: AMD and AMD Opteron are trademarks of Advanced Micro Devices, Inc.

Macintosh, Mac, Mac OS, and Xcode are trademarks of Apple Inc., registered in the U.S. and other countries.

Embarcadero, the Embarcadero Technologies logos and all other Embarcadero Technologies product or service names

are trademarks, service marks, and/or registered trademarks of Embarcadero Technologies, Inc. and are protected by the

laws of the United States and other countries. Business Objects and the Business Objects logo, BusinessObjects, Crystal

Reports, Crystal Decisions, Web Intelligence, Xcelsius, and other Business Objects products and services mentioned

herein as well as their respective logos are trademarks or registered trademarks of Business Objects Software Ltd.

Business Objects is an SAP company. HP and HP-UX are registered trademarks of the Hewlett-Packard Company. AIX,

IBM, POWER6, POWER7, and pSeries are trademarks or registered trademarks of International Business Machines

Corporation in the United States, other countries, or both. Intel, Intel Core, Itanium, Pentium and Xeon are trademarks or

registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Microsoft, the .NET

logo, the Windows logo, Access, Excel, SQL Server, Visual Basic, Visual C++, Visual C#, Visual Studio, Windows,

Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the

United States and/or other countries. Novell and SUSE are registered trademarks of Novell, Inc. in the United States and

other countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. QNX and Neutrino are

registered trademarks of QNX Software Systems Ltd. in certain jurisdictions. CentOS, Red Hat, and the Shadow Man logo

are registered trademarks of Red Hat, Inc. in the United States and other countries, used with permission. UNIX and

UnixWare are registered trademarks of The Open Group in the United States and other countries. Linux is a trademark of

Linus Torvalds in the United States, other countries, or both. Python and PyCon are trademarks or registered trademarks

of the Python Software Foundation. OpenServer is a trademark or registered trademark of Xinuos, Inc. in the U.S.A. and

other countries. Unicode and the Unicode Logo are registered trademarks of Unicode, Inc. in the United States and other

countries.

Btrieve is a registered trademark of Actian Corporation.

ACUCOBOL-GT, Micro Focus, RM/COBOL, and Visual COBOL are trademarks or registered trademarks of Micro Focus

(IP) Limited or its subsidiaries in the United Kingdom, United States and other countries.

isCOBOL and Veryant are trademarks or registered trademarks of Veryant in the United States and other countries.

All other trademarks, trade names, company names, product names, and registered trademarks are the property of their

respective holders.

Portions Copyright © 1991-2016 Unicode, Inc. All rights reserved.

Portions Copyright © 1998-2016 The OpenSSL Project. All rights reserved. This product includes software developed by

the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).

Portions Copyright © 1995-1998 Eric Young ([email protected]). All rights reserved. This product includes cryptographic

software written by Eric Young ([email protected]). This product includes software written by Tim Hudson

([email protected]).

Portions © 1987-2020 Dharma Systems, Inc. All rights reserved. This software or web site utilizes or contains material

that is © 1994-2007 DUNDAS DATA VISUALIZATION, INC. and its licensors, all rights reserved.

Portions Copyright © 1995-2013 Jean-loup Gailly and Mark Adler.

5/29/2020


12. Index

A Additional Functionality ........................................... 82 Additional Resources ............................58, 66, 72, 81

C Compile the PHP PDO Extension (Linux/Unix) ...... 22 Compile the PHP PDO Extension (Windows) ........ 15 Compile the SQL PHP Extension ........................... 31 Compile the SQL PHP Extension (Linux/Unix) ....... 39 Configure Microsoft IIS ..................................... 12, 48 Configure PHP ........................................................ 37 Configure PHP 7 ..................................................... 19 Configure the SQL PHP Extension ......................... 28 Copyright Notice ................................................... cvii c-treeACE PHP Example ........................................ 84 c-treeACE PHP for c-treeACE SQL .......................... 1 c-treeACE PHP Functions ...................................... 83 ctsql_affected_rows ................................................ 85 ctsql_close .............................................................. 86 ctsql_commit ........................................................... 87 ctsql_connect .......................................................... 88 ctsql_end_of_fetch.................................................. 89 ctsql_errno .............................................................. 90 ctsql_error ............................................................... 91 ctsql_fetch_array .................................................... 92 ctsql_fetch_assoc ................................................... 93 ctsql_fetch_object ................................................... 94 ctsql_fetch_row ....................................................... 95 ctsql_field_len ......................................................... 96 ctsql_field_name ..................................................... 97 ctsql_field_table ...................................................... 98 ctsql_field_type ....................................................... 99 ctsql_free_result ................................................... 100 ctsql_num_fields ................................................... 101 ctsql_pconnect ...................................................... 102 ctsql_query ........................................................... 103 ctsql_rollback ........................................................ 104

D Define ...................................................55, 60, 68, 73 Done .....................................................57, 66, 71, 80

E Error

function, ctsql_errno ........................................... 90 function, ctsql_error ............................................ 91

F FairCom Typographical Conventions ..................... cv Functions

ctsql_close .......................................................... 86 ctsql_commit ....................................................... 87

ctsql_connect ..................................................... 88 ctsql_errno ......................................................... 90 ctsql_error .......................................................... 91 ctsql_fetch_array ................................................ 92 ctsql_fetch_assoc .............................................. 93 ctsql_fetch_object .............................................. 94 ctsql_fetch_row .................................................. 95 ctsql_field_len .................................................... 96 ctsql_field_name ................................................ 97 ctsql_field_table ................................................. 98 ctsql_field_type .................................................. 99 ctsql_free_result ............................................... 100 ctsql_num_fields .............................................. 101 ctsql_pconnect ................................................. 102 ctsql_query ....................................................... 103 ctsql_rollback ................................................... 104 Functions............................................................ 83

I IIS ..............................................................................6 Init ........................................................ 54, 60, 68, 73 Install Microsoft IIS............................................. 7, 45 Install PHP ....................................................... 47, 51 Install PHP 7 PDO and Microsoft IIS ........................6 Install PHP 7 PDO on Linux and Unix ................... 18 Install PHP 7 with the PDO Extension ......................9 Install the Web Server ........................................... 51 Install unixODBC.................................................... 50 Instructions for CentOS ......................................... 21 Introductory Tutorial ............................................... 53

L Linux, Unix installation ........................................... 18

M Manage ................................................ 55, 63, 69, 75 Microsoft IIS ..............................................................6

O ODBC ..................................................................... 44

P Packages Required for Windows ........................... 44 PDO Extension .........................................................6

Q Quick Start ................................................................3

R Record/Row Locking .............................................. 67 Relationships ......................................................... 58 Resource types ...................................................... 83 Resource Types ..................................................... 83 Run the PHP PDO Tutorials with Microsoft IIS ...... 17 Run the SQL PHP Tutorials with Linux/Unix

Apache ............................................................... 41 Run the SQL PHP Tutorials with Microsoft IIS ...... 34

Index


Run the sql.php.pdo Tutorials with Linux/Unix Apache ................................................................ 23

S Set Up the ODBC Data Source .............................. 53

T Transaction Processing .......................................... 72

U Unix, Linux .............................................................. 18 Using PHP 7 with the PDO Extension ...................... 6 Using PHP on Linux and Unix ................................ 50 Using PHP on Windows ......................................... 44 Using PHP with ODBC ........................................... 44 Using PHP with the SQL PHP API ......................... 26 Using SQL PHP on Linux and Unix ........................ 36 Using the SQL PHP API on Windows .................... 27

W Windows ................................................................... 6

Developer Guide PHP SQL Developers Guide · To address this issue, the community that develops PHP has introduced the PHP Data Objects (PDO) extension for accessing a database. PDO

Documents