SQLBase API : SQL/API Function Reference

SQL/API Function Reference
This chapter is organized alphabetically by SQL/API function name, and contains the syntax, a detailed description, and an example for each function.
Extension Functions
These functions were added in order to facilitate the widening/lengthening of columns. The new functions are extensions of the functions of the same name minus the "2" at the end.
In most cases, at least one parameter points to a 2 byte column width or size, rather than a one byte value. A few functions have a new parameter. The "_L" parameter suffix is the "large" version of the parameter.
The extension functions, their syntax, and links to the full documentation of the original functions are found below. These function prototypes are included in sqlbase.h.
There are two ways to take advantage of the extended column support at the API level:
1.
2.
Define SQLBASE_API_COMPAT=0 before including "sqlbase.h" in your C/C++ project files. This will cause the C preprocessor to reference the new functions and expanded types. You may have to fix some compiler warnings and errors, as well as expand other data types in your application. By default SQLBASE_API_COMPAT is set to 1 for maximum backwards compatibility. With this setting, you should not have to make any program changes and all the old API functions will work as before.
sqlbld2
Extension of sqlbld - Bind Long Data by name.
SQLTAPI sqlbld2(SQLTCUR cur, SQLTBNP bnp, SQLTBNL bnl, SQLTPDT pdt);
sqlbln2
Extension of sqlbln - Bind Long data by Number.
SQLTAPI sqlbln2(SQLTCUR cur, SQLTBNN_L bnn, SQLTPDT pdt);
sqlbnn2
Extension of sqlbnn - BiNd data by Number.
SQLTAPI sqlbnn2(SQLTCUR cur, SQLTBNN_L bnn, SQLTDAP dap, SQLTDAL dal, SQLTSCA sca, SQLTPDT pdt);
sqlbnu2
Extension of sqlbnu - Bind data by NUmber.
SQLTAPI sqlbnu2(SQLTCUR cur, SQLTBNN_L bnn, SQLTDAP dap, SQLTDAL dal, SQLTSCA sca, SQLTPDT pdt, SQLTNUL nli);
sqldes2
Extension of sqldes - DEScribe items in a SELECT list.
SQLTAPI sqldes2(SQLTCUR cur, SQLTSLC_L slc, SQLTDDT *ddt, SQLTDDL_L *ddl, SQLTCHP chp, SQLTCHL_L *chlp, SQLTPRE *prep, SQLTSCA *scap);
sqldii2
Extension of sqldii - Describe Into variable.
SQLTAPI sqldii2(SQLTCUR cur, SQLTSLC_L ivn, SQLTDAP inp, SQLTCHL_L *inlp);
sqldsc2
Extension of sqldsc - DeSCribe item in a SELECT command.
SQLTAPI sqldsc2(SQLTCUR cur, SQLTSLC_L slc, SQLTDDT *edt, SQLTDDL_L *edl, SQLTCHP chp, SQLTCHL_L *chlp, SQLTPRE *prep, SQLTSCA *scap);
sqlgdi2
Extension of sqlgdi - Get Describe Information.
SQLTAPI sqlgdi2(SQLTCUR cur, SQLTPGD2 gdi);
sqlgfi2
Extension of sqlgfi - Get Fetch Information.
SQLTAPI sqlgfi2(SQLTCUR cur, SQLTSLC_L slc, SQLTCDL_L *cvl, SQLTFSC *fsc);
sqlgls2
Extension of sqlgls - Get Long Size.
SQLTAPI sqlgls2(SQLTCUR cur, SQLTSLC_L slc, SQLTLSI *size);
sqllab2
Exrension of sqllab - LABel information.
SQLTAPI sqllab2(SQLTCUR cur, SQLTSLC_L slc, SQLTCHP lbp, SQLTCHL_L *lblp);
sqllsk2
Extension of sqllsk - Long SeeK.
SQLTAPI sqllsk2(SQLTCUR cur, SQLTSLC_L slc, SQLTLSI pos);
sqlnbv2
Extension of sqlnbv - Number of Bind Variables.
SQLTAPI sqlnbv2(SQLTCUR cur, SQLTNBV_L *nbv);
sqlnii2
Extension of sqlnii - get the Number of Into variables.
SQLTAPI sqlnii2(SQLTCUR cur, SQLTNSI_L *nii);
sqlnsi2
Extension of sqlnsi - Number of Select Items.
SQLTAPI sqlnsi2(SQLTCUR cur, SQLTNSI_L *nsi);
sqlrlo2
Extension of sqlrlo - Read LOng.
SQLTAPI sqlrlo2(SQLTCUR cur, SQLTSLC_L slc, SQLTDAP bufp, SQLTDAL bufl, SQLTDAL *readl, SQLTPDT pdt);
sqlssb2
Extension of sqlssb - Set SELECT Buffer.
SQLTAPI sqlssb2(SQLTCUR cur, SQLTSLC_L slc, SQLTPDT pdt, SQLTDAP pbp, SQLTPDL_L pdl, SQLTSCA sca, SQLTCDL_L *pcv, SQLTFSC *pfc);
sqlbbr - Bulk execute Return
Syntax
#include <sql.h>
 
SQLTAPI sqlbbr (cur, rcd, errbuf, buflen, errrow, rbf, errseq)
 
SQLTCUR cur; /* Cursor handle */
SQLTXER PTR rcd; /* Return code */
SQLTDAP err buf; /* Ptr to receiving buffer */
SQLTDAL PTR buflen; /* Length of receiving buffer */
SQLTBIR PTR errrow; /* Error row number */
SQLTRBF PTR rbf; /* Roll back flag */
SQLTBIR errseq; /* Error sequence number */
 
Description
This function returns the error return code of the previous bulk execute operation that took place against a non-SQLBase database server.
This function is like sqlber, but it also returns the error message text from the non-SQLBase database server.
You can also call sqlbbr when processing against SQLBase databases. This means that you can use sqlbbr for database-independent applications.
In bulk execute mode, several rows are processed in one call to sqlexe. If sqlexe returns an error, use sqlbbr to find the row that caused the error. Rows that are processed are numbered consecutively. When you call sqlbbr, you specify the error sequence number (errseq) and sqlbbr returns the row number in errrow.
For example, if you INSERT 6 rows, they are numbered 1, 2, 3, 4, 5, and 6. If the rows numbered 2, 4, and 6 caused an error, you would call sqlbbr and specify 1 in errseq and sqlbbr would return 2 in errrow (meaning row 2 caused an error). Continue to call sqlbbr, incrementing the number in errseq each time. When sqlbbr returns 0 in rcd, there are no more errors. This is shown in the table below.
First sqlbbr call
Second sqlbbr call
Third sqlbbr call
Fourth sqlbbr call
Parameters
cur
The cursor handle associated with this function.
rcd
A pointer to the variable where this function returns the status code for the row that caused the error.
Some database servers may return zero value when the operation was not successful, so you should also check to see if errrow is greater than zero.
errbuf
A pointer to the buffer where this function copies the error message text.
buflen
A pointer to the variable where this function returns the number of bytes in the retrieved error message text.
errrow
A pointer to the variable where this function returns the row number that was in error.
rbf
A pointer to the variable where this function returns the rollback status indicator:
errseq
The sequence number of the error to retrieve. Set the errseq parameter to 1 to get the first error, 2 to get the second error, and so on. If the errseq parameter exceeds the number of error messages returned for the last bulk execute, rcd is set to zero to show there are no more error messages.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Related functions
 
sqlbef sqlber sqlblk
sqlbdb - Backup DataBase
Syntax
include <sql.h>
 
SQLTAPI sqlbdb (shandle, dbname, dbnamel, bkpdir, bkpdirl,
local, over)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel; /* Length of database name */
SQLTFNP bkpdir; /* Backup directory */
SQLTFNL bkpdirl; /* Backup directory length */
SQLTBOO local; /* True: backup directory on local (client)
node */
SQLTBOO over; /* True: overwrite existing file */
 
Description
This function copies a database to the specified directory. The database is backed up to a file with the name:
database-name.BKP
If this function finds a control file in the backup directory, the function performs a segmented backup based on the contents of the control file. For details, read the Database Administrator’s Guide.
Transactions that are committed when the backup starts are included in the backup. Active transactions are not included.
Before you can use sqlbdb, you must turn on log backup mode using the SQLPLBM parameter and the sqlset function. You only need to do this once for a database (such as just after it has been created), and the setting stays on until you turn it off.
Once a database file is backed up to a directory, you can transfer the backup to archival media; then delete the backup files from the hard disk.
Parameters
shandle
The server handle returned by sqlcsv.
dbname
A pointer to the string that contains the database name.
dbnamel
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
bkpdir
A pointer to the string that contains the backup directory name.
bkpdirl
The length of the string pointed to by bkpdir. If the string pointed to by bkpdir is null-terminated, specify 0 and the system will compute the length.
local
Destination of backup:
over
Overwrite indicator:
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTSVH shandle;
char* svrname;
char* password;
SQLTDPV lbmset;
SQLTFNP bkpdir;
SQLTFNL bkpdirl;
SQLTRFM mode=SQLMEOL;
SQLTLNG lognum;
SQLTBOO local,over;
SQLTCUR cur1;
 
static char dbname1[] = "omed";
strcpy(svrname,”SERVER1”);
password = 0;
 
bkpdir = "\\BACKUP\\OMED";
bkpdirl = strlen(bkpdir);
 
printf("value of bkpdir = %s \n",bkpdir);
 
local=1;
over=1;
 
/* CONNECT TO OMED */
 
if (rcd = sqlcnc(&cur1,dbname1,0))
apierr("SQLCNC");
else
printf("Connected to OMED \n");
 
/* SET LOGBACKUP MODE ON */
 
lbmset=1;
if (rcd = sqlset(cur1,SQLPLBM,(ubyte1p)&lbmset,0))
apierr("SQLSET");
else
printf("Logbackupmode is set to %d \n", lbmset);
 
/* MAKE BACKUP DIRECTORIES */
 
system("mkdir \\backup");
system("mkdir \\backup\\omed");
 
/* CONNECT TO SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
/* BACKUP DATABASE */
 
if (rcd = sqlbdb(shandle,dbname1,0,bkpdir,bkpdirl,local,over))
apierr("SQLBDB");
else
printf("Backed Up Database \n");
 
/* RELEASE LOG */
 
if (rcd = sqlrel(cur1))
apierr("SQLREL");
else
printf("Released Logs \n");
 
/* BACKUP LOGS */
 
if (rcd = sqlblf(shandle,dbname1,0,bkpdir,bkpdirl,local,over))
apierr("SQLBLF");
else
printf("Backed Up Logs \n");
 
Related functions
 
sqlblf sqlenr sqlrlf
sqlbss sqlgnl sqlrof
sqlcrf sqlrdb sqlrss
sqlcsv sqlrel
sqlbef - Bulk Execute Flush
Syntax
#include <sql.h>
SQLTAPI sqlbef (cur)
SQLTCUR cur; /* Cursor handle */
 
Description
This function flushes the data (if any) in the bulk execute buffer to the server for processing.
Parameters
cur
The cursor handle associated with this function.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
/* Set bulk execute mode on */
if (sqlblk(cur, 1))
goto cleanup;
 
/* Compile the insert statement */
 
if (sqlcom(cur, "insert into test values (:1)"))
goto cleanup;
/* Bind the data and insert the row */
 
for (i = 0; i < N; i++)
{
if (sqlbnn(cur, 1, &data[i], 0, 0, SQLPBUF))
goto cleanup;
if (sqlexe(cur))
{
 
/* Error occurred on the execution of the bulk execute,
retrieve the error messages by calling sqlber() */
 
for (j = 1; ; j++)
{
 
/* Retrieve the next error message */
 
if (sqlber(cur, &rcd, &rownum, &rbf, j))
goto cleanup;
 
/* Break out of loop, if no more error messages */
 
if (!rcd)
break;
 
/* Report the error */
 
printf("error on row #%d, rcd = %d0, rownum, rcd);
}
}
}
 
/* Flush out the unprocessed bulk execute buffer to the server */
 
if (sqlbef(cur))
{
for (j = 1; ; j++)
{
if (sqlber(cur, &rcd, &rownum, &rbf, j))
goto cleanup;
if (!rcd)
break;
printf("error on row #%d, rcd = %d0, rownum, rcd);
}
}
 
/* Reset bulk execute mode */
 
if (sqlblk(cur, 0))
goto cleanup;
 
Related functions
 
sqlbbr sqlber sqlblk
sqlber - Bulk Execute Return
Syntax
#include <sql.h>
 
SQLTAPI sqlber (cur, rcd, errrow, rbf, errseq)
 
SQLTCUR cur; /* Cursor handle */
SQLTRCD PTR rcd; /* Return code */
SQLTBIR PTR errrow; /* Error row number */
SQLTRBF PTR rbf; /* Roll back flag */
SQLTBIR errseq; /* Error sequence number */
 
Description
This function returns the error return code for the previous bulk execute operation.
In bulk execute mode, several rows are processed in one call to sqlexe. If sqlexe returns an error, use sqlber to find the row that caused the error. Rows that are processed are numbered consecutively. When you call sqlber, you specify the error sequence number (errseq) and sqlber returns the row number in errrow.
For example, if you INSERT 6 rows, they are numbered 1, 2, 3, 4, 5, and 6. If the rows numbered 2, 4, and 6 caused an error, you would call sqlber and specify 1 in errseq and sqlber would return 2 in errrow (meaning row 2 caused an error). Continue to call sqlber, incrementing the number in errseq each time. When sqlber returns 0 in rcd, there are no more errors. This is shown in the table below.
First sqlber call
Second sqlber call
Third sqlber call
Fourth sqlber call
Parameters
cur
The cursor handle associated with this function.
rcd
A pointer to the variable where this function returns the status code for the row that caused the error.
errrow
A pointer to the variable where this function returns the row number that was in error.
rbf
A pointer to the variable where this function returns the rollback status indicator:
errseq
The sequence number of the error to retrieve. Set the errseq parameter to 1 to get the first error, 2 to get the second error, and so on. If the errseq parameter exceeds the number of error messages returned for the last bulk execute, rcd is set to zero to show there are no more error messages.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
The following example shows how to use the sqlber function when errors happen during a bulk execute operation.
/* Set bulk execute mode on */
 
if (sqlblk(cur, 1))
goto cleanup;
 
/* Compile the insert statement */
 
if (sqlcom(cur, "insert into test values (:1)"))
goto cleanup;
 
/* Binding the data and insert the row */
 
for (i = 0; i < N; i++)
{
if (sqlbnn(cur, 1, &data[i], 0, 0, SQLPBUF))
goto cleanup;
if (sqlexe(cur))
{
 
/* Error occurred on the execution of the bulk execute,
retrieve the error messages by calling sqlber() */
 
for (j = 1; ; j++)
{
 
/* Retrieve the next error message */
 
if (sqlber(cur, &rcd, &rownum, &rbf, j))
goto cleanup;
/* Break out of loop, if no more error messages */
 
if (!rcd)
break;
/* Report the error */
 
printf("error on row #%d, rcd = %d0, rownum, rcd);
}
}
}
 
/* Flush out the unprocessed bulk execute buffer to the server */
 
if (sqlbef(cur))
{
for (j = 1; ; j++)
{
if (sqlber(cur, &rcd, &rownum, &rbf, j))
goto cleanup;
if (!rcd)
break;
printf("error on row #%d, rcd = %d0, rownum, rcd);
}
}
 
/* Reset bulk execute mode */
 
if (sqlblk(cur, 0))
goto cleanup;
 
Related functions
 
sqlbbr, sqlbef, sqlblk
sqlbld - Bind Long Data by name
Syntax
#include <sql.h>
 
SQLTAPI sqlbld (cur, bnp, bnl)
SQLTCUR cur; /* Cursor handle */
SQLTBNP bnp; /* Name of variable */
SQLTBNL bnl; /* Length of variable name */
 
Description
This function associates an alphanumeric bind variable (such as: comments) for a LONG VARCHAR column with a variable defined in the program.
The function is called after the sqlcom function and before the sqlwlo function. Note that sqlwlo (not sqlbld) specifies the variable that stores the data.
Only one LONG VARCHAR column can be processed at a time. The complete sequence of functions which bind, write, and end the operation must be completed before the next bind for a LONG VARCHAR.
Parameters
cur
The cursor handle associated with this function.
bnp
A pointer to a string that contains the bind variable name.
bnl
The length of the string pointed to by bnp. If the string pointed to by bnp is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
static char ins[] = /* sql statement */
"insert into mytable values (:id, :comm)";
short ret; /* return code */
 
ret = sqlbld (cur, "comm", 0);
 
Related functions
 
sqlbln sqlcbv sqlrlo
sqlbna sqlelo sqlwlo
sqlbnu sqlnbv sqlbld2
sqlblf - Backup Log Files
Syntax
#include <sql.h>
 
SQLTAPI sqlblf (shandle, dbname, dbnamel, bkpdir, bkpdirl,
local, over)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel; /* Length of database name */
SQLTFNP bkpdir; /* Backup directory */
SQLTFNL bkpdirl; /* Backup directory length */
SQLTBOO local; /* True: backup directory on local
(client) node */
SQLTBOO over; /* True: overwrite existing file */
 
Description
This function copies unpinned log files to the specified directory. When this command completes successfully, SQLBase deletes the log files that were backed up from the current log directory.
Before you can use sqlblf, you must set log backup mode to ON using the SQLPLBM parameter and the sqlset function. You only need to do this once for a database (such as just after it has been created), and the setting stays on until you turn it off.
Once the log files are backed up to a directory, the backup files can be transferred to archival media and then deleted from the hard disk.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Parameters
shandle
The server handle returned by sqlcsv.
dbname
A pointer to the string that contains the database name.
dbnamel
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
bkpdir
A pointer to the string that contains the backup directory name.
bkpdirl
The length of the string pointed to by bkpdir. If the string pointed to by bkpdir is null-terminated, specify zero and the system will compute the length.
local
Destination of backup:
over
Overwrite indicator:
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTSVH shandle;
char* svrname;
char* password;
SQLTDPV lbmset;
SQLTFNP bkpdir;
SQLTFNL bkpdirl;
SQLTRFM mode=SQLMEOL;
SQLTLNG lognum;
SQLTBOO local,over;
SQLTCUR cur1;
 
static char dbname1[] = "omed";
strcpy(svrname,”SERVER1”);
password = 0;
 
bkpdir = "\\BACKUP\\OMED";
bkpdirl = strlen(bkpdir);
 
printf("value of bkpdir = %s \n",bkpdir);
 
local=1;
over=1;
 
/* CONNECT TO OMED */
 
if (rcd = sqlcnc(&cur1,dbname1,0))
apierr("SQLCNC");
else
printf("Connected to OMED \n");
 
/* SET LOGBACKUP MODE ON */
 
lbmset=1;
if (rcd = sqlset(cur1,SQLPLBM,(ubyte1p)&lbmset,0))
apierr("SQLSET");
else
printf("Logbackupmode is set to %d \n", lbmset);
 
/* MAKE BACKUP DIRECTORIES */
 
system("mkdir \\backup");
system("mkdir \\backup\\omed");
 
/* CONNECT TO SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
/* BACKUP DATABASE */
 
if (rcd = sqlbdb(shandle,dbname1,0,bkpdir,bkpdirl,local,over))
apierr("SQLBDB");
else
printf("Backed Up Database \n");
 
/* RELEASE LOG */
 
if (rcd = sqlrel(cur1))
apierr("SQLREL");
else
printf("Released Logs \n");
 
/* BACKUP LOGS */
 
if (rcd = sqlblf(shandle,dbname1,0,bkpdir,bkpdirl,local,over))
apierr("SQLBLF");
else
printf("Backed Up Logs \n");
 
Related functions
 
sqlbdb sqlenr sqlrlf
sqlbss sqlgnl sqlrof
sqlcrf sqlrdb sqlrss
sqlcsv sqlrel
sqlblk - BuLK execute
Syntax
#include <sql.h>
 
SQLTAPI sqlblk (cur, blkflg)
 
SQLTCUR cur; /* Cursor handle */
SQLTFLG blkflg; /* 0 = off; 1 = on */
 
Description
This function turns on bulk execute mode.
In bulk execute mode, rows are buffered so that many rows can be sent to the server in one message. This improves the performance of bulk operations on a table, particularly across a network.
The number of rows per message depends upon the size of the output message buffer which can be set with the sqloms function.
After performing the operations, use the sqlbef function to physically complete the INSERT, UPDATE, or DELETE.
You can use the bulk execute feature with chained commands if they do not contain SELECT commands.
The bulk execute feature cannot be turned on at the same time that the autocommit feature is turned on.
Bulk execute mode is a cursor-specific setting.
Parameters
cur
The cursor handle associated with this function.
blkflg
Bulk execute mode setting:
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
/* Set bulk execute mode on */
 
if (sqlblk(cur, 1))
goto cleanup;
 
/* Compile the insert statement */
 
if (sqlcom(cur, "insert into test values (:1)"))
goto cleanup;
 
/* Binding the data and insert the row */
 
for (i = 0; i < N; i++)
{
if (sqlbnn(cur, 1, &data[i], 0, 0, SQLPBUF))
goto cleanup;
if (sqlexe(cur))
{
 
/* Error occurred on the execution of the bulk execute,
retrieve the error messages by calling sqlber() */
 
for (j = 1; ; j++)
{
 
/* Retrieve the next error message */
 
if (sqlber(cur, &rcd, &rownum, &rbf, j))
goto cleanup;
 
/* Break out of loop, if no more error messages */
 
if (!rcd)
break;
 
/* Report the error */
 
printf("error on row #%d, rcd = %d0, rownum, rcd);
}
}
}
 
/* Flush out the unprocessed bulk execute buffer to the
server */
 
if (sqlbef(cur))
{
for (j = 1; ; j++)
{
if (sqlber(cur, &rcd, &rownum, &rbf, j))
goto cleanup;
if (!rcd)
break;
printf("error on row #%d, rcd = %d0, rownum, rcd);
}
}
 
/* Reset bulk execute mode */
 
if (sqlblk(cur, 0))
goto cleanup;
 
Related functions
 
sqlbbr, sqlber, sqloms, sqlbef
sqlbln - Bind Long data by Number
Syntax
#include <sql.h>
 
SQLTAPI sqlbln (cur, bnn);
 
SQLTCUR cur; /* Cursor handle */
SQLTBNN bnn; /* Bind variable number */
 
Description
This function associates a numeric bind variable (such as :3) for a LONG VARCHAR column with a variable defined in the program.
The function is called after the sqlcom function and before the sqlwlo function. Note that sqlwlo (not sqlbln) specifies the variable that stores the data.
Only one LONG VARCHAR column can be processed at a time. The sequence of binding, writing, and ending the operation must be completed before the next bind for a LONG VARCHAR.
Parameters
cur
The cursor handle associated with this function.
bnn
The number of the bind variable in the SQL command. Bind variable numbers must be unique in SQL commands.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
static char ins[] = "insert into mytable values (:1, :2)";
short ret; /* return code */
 
ret = sqlbln(cur, 2);
 
Related functions
 
sqlbld sqlcbv sqlrlo
sqlbna sqlelo sqlwlo
sqlbnu sqlnbv sqlbln2
sqlbna - Bind data by NAme (with null indicator)
Syntax
#include <sql.h>
 
SQLTAPI sqlbna (cur, bnp, bnl, dap, dal, sca, pdt, nli);
 
SQLTCUR cur; /* Cursor handle */
SQLTBNP bnp; /* Name of bind variable */
SQLTBNL bnl; /* Length of bind variable name */
SQLTDAP dap; /* Bind data buffer */
SQLTDAL dal; /* Bind data length */
SQLTSCA sca; /* Scale of packed decimal data */
SQLTPDT pdt; /* Bind program data type */
SQLTNUL nli /* Null indicator */
 
Description
This function associates an alphanumeric bind variable (such as :comments) for a column with a variable defined in the program.
The sqlbna function is identical to sqlbnd with one exception: sqlbna has an additional argument for the null indicator. This function is used with SQLNetwork routers and gateways to bind null values for non-SQLBase databases. You can use this function with SQLBase databases, but SQLBase ignores the nli argument.
Call this function after sqlcom and before sqlexe.
Parameters
cur
The cursor handle associated with this function.
bnp
A pointer to the string that contains the bind variable name. Bind variable names must be unique in SQL commands.
bnl
The length of the string pointed to by bnp. If the string pointed to by bnp is null-terminated, specify zero and the system will compute the length.
dap
A pointer to the variable that will be associated to the bind variable.
dal
The length of the value pointed to by dap.
If the value pointed to by dap is a string and null-terminated, specify zero and the system will compute the length.
In all other cases, a calculated length of zero or a specified length of zero causes the column to contain a null value.
sca
The scale (number of decimal places) for a packed-decimal data type. This argument is ignored for other data types. If you are not using a packed-decimal data type, specify zero.
pdt
The program data type of the program variable being bound. Data is converted to the program data type if the SQL data is compatible.
The program data types are shown below. These are defined in sql.h.
nli
Null indicator. Before calling sqlbna, set this argument to indicate whether or not the value being bound is null:
The data being bound is null. The SQLNetwork router or gateway will generate the native null character for the database server.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Related functions
 
sqlbld sqlbnn sqlcbv
sqlbln sqlbnu sqlnbv
sqlbnd
sqlbnd - BiNd Data by name
Syntax
#include <sql.h>
 
SQLTAPI sqlbnd (cur, bnp, bnl, dap, dal, sca, pdt);
 
SQLTCUR cur; /* Cursor handle */
SQLTBNP bnp; /* Name of bind variable */
SQLTBNL bnl; /* Length of bind variable name */
SQLTDAP dap; /* Bind data buffer */
SQLTDAL dal; /* Bind data length */
SQLTSCA sca; /* Scale of packed decimal data */
SQLTPDT pdt; /* Bind program data type */
 
Description
This function associates an alphanumeric bind variable (such as :comments) for a column with a variable defined in the program.
Call this function after sqlcom and before sqlexe.
Parameters
cur
The cursor handle associated with this function.
bnp
A pointer to the string that contains the bind variable name. Bind variable names must be unique in SQL commands.
bnl
The length of the string pointed to by bnp. If the string pointed to by bnp is null-terminated, specify zero and the system will compute the length.
dap
A pointer to the variable that will be associated to the bind variable.
dal
The length of the value pointed to by dap.
If the value pointed to by dap is a string and null-terminated, specify zero and the system will compute the length.
In all other cases, a calculated length of zero or a specified length of zero causes the column to contain a null value.
sca
The scale (number of decimal places) for a packed-decimal data type. This argument is ignored for other data types. If you are not using a packed-decimal data type, specify zero.
pdt
The program data type of the program variable being bound. Data is converted to the program data type if the SQL data is compatible.
The program data types are shown below. These are defined in sql.h.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
static char insitem = /* SQL insert statement */
"insert into item values (:item, :name)";
 
int item; /* item number */
char name[25]; /* item name */
short ret; /* return code */
/* Bind integer data */
 
ret = sqlbnd(cur,"item",0,&item,sizeof(item),0,SQLPUIN);
 
/* Use defaults for pdt and bnl */
 
ret = sqlbnd(cur,"name",0,name,25,0,SQLPBUF);
 
Related functions
 
sqlbld sqlbnn sqlcbv
sqlbln sqlbnu sqlnbv
sqlbna
sqlbnn - BiNd data by Number
Syntax
#include <sql.h>
 
SQLTAPI sqlbnn (cur, bnn, dap, dal, sca, pdt);
 
SQLTCUR cur; /* Cursor handle */
SQLTBNN bnn; /* Bind variable number */
SQLTDAP dap; /* Bind data buffer */
SQLTDAL dal; /* Bind data length */
SQLTSCA sca; /* Scale of packed decimal data */
SQLTPDT pdt; /* Bind program data type */
 
Description
This function associates a numeric bind variable (such as :3) for a column with a variable defined in the program.
You must call this function after sqlcom and before sqlexe.
Parameters
cur
The cursor handle associated with this function.
bnn
The number of the bind variable in the SQL command. Bind variable numbers must be unique in SQL commands.
dap
A pointer to the program variable that will be associated to the bind variable.
dal
The length of the value pointed to by dap.
If the value pointed to by dap is a string and null-terminated, specify zero and the system will compute the length.
In all other cases, a calculated length of zero or a specified length of zero causes the column to contain a null value.
sca
The scale (number of decimal places) for a packed-decimal data type. This argument is ignored for other data types. If you are not using a packed-decimal data type, specify zero.
pdt
The program data type of the program variable being bound. Data is converted to the program data type if the SQL data is compatible.
The program data types are shown below. These are defined in sql.h.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
char len = 7; /* length of phone number */
short ret; /* API return code */
char pnum[8]; /* phone number */
 
static char updt[] = /* SQL statement */
"UPDATE CUST SET PHONE = :1 WHERE CURRENT OF CURSOR";
 
ret = sqlbnn(cur, 1, pnum, sizeof(pnum) ,0, SQLPBUF);
 
Related functions
 
sqlbld sqlbnd sqlcbv
sqlbln sqlbnu sqlnbv
sqlbna sqlbnn2
sqlbnu - Bind data by NUmber
Syntax
#include <sql.h>
 
SQLTAPI sqlbnu (cur, bnn, dap, dal, sca, pdt, nli);
 
SQLTCUR cur; /* Cursor handle */
SQLTBNN bnn; /* Bind variable number */
SQLTDAP dap; /* Bind data buffer */
SQLTDAL dal; /* Bind data length */
SQLTSCA sca; /* Scale of packed decimal data */
SQLTPDT pdt; /* Bind program data type */
SQLTNUL nli /* Null indicator */
 
Description
This function associates a numeric bind variable (such as :3) for a column with a variable defined in the program.
The sqlbnu function is identical to sqlbnn with one exception: sqlbnu has an additional argument for the null indicator. This function is used with SQLNetwork routers and gateways to bind null values for non-SQLBase databases. You can use this function with SQLBase databases, but SQLBase ignores the nli argument.
Call this function after sqlcom and before sqlexe.
Parameters
cur
The cursor handle associated with this function.
bnn
The number of the bind variable in the SQL command. Bind variable numbers must be unique in SQL commands.
dap
A pointer to the program variable that will be associated to the bind variable.
dal
The length of the value pointed to by dap.
If the value pointed to by dap is a string and null-terminated, specify zero and the system will compute the length.
In all other cases, a calculated length of zero or a specified length of zero causes the column to contain a null value.
sca
The scale (number of decimal places) for a packed-decimal data type. This argument is ignored for other data types. If you are not using a packed-decimal data type, specify zero.
pdt
The program data type of the program variable being bound. Data is converted to the program data type if the SQL data is compatible.
The program data types are shown below. These are defined in sql.h.
nli
Null indicator. Before calling sqlbnu, set this argument to indicate whether or not the value being bound is null:
The data being bound is null. The SQLNetwork router or gateway will generate the native null character for the database server.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Related functions
 
sqlbld sqlbnd sqlcbv
sqlbln sqlbnn sqlnbv
sqlbna sqlbnu2
sqlbss - Backup SnapShot
Syntax
#include <sql.h>
 
SQLTAPI sqlbss (shandle, dbname, dbnamel, bkpdir, bkpdirl,
local, over)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel; /* Database name length */
SQLTFNP bkpdir; /* Backup directory */
SQLTFNL bkpdirl; /* Backup directory length */
SQLTBOO local; /* True: backup directory on local
(client) node */
SQLTBOO over; /* True: overwrite existing file */
 
Description
This function copies a database and its associated transaction log files to the specified directory.
The sqlbss function is the recommended way to backup a database and its log files because there is only one step (sqlrss) needed to bring a database and its log files to a consistent state.
Transactions that are committed when the backup is started are included in the backup. Active transactions are not included.
This function call forces a log rollover (sqlrlf) automatically.
Once a database and its transaction log files are backed up to a directory, you can transfer the copies to archival media and then delete them from the hard disk.
You cannot call sqlbss while in Read-Only (RO) isolation level.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Parameters
shandle
The server handle returned by sqlcsv.
dbname
A pointer to the string that contains the database name.
dbnamel
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
bkpdir
A pointer to the string that contains the backup directory name.
bkpdirl
The length of the string pointed to by bkpdir. If the string pointed to by bkpdir is null-terminated, specify zero and the system will compute the length.
local
Destination of backup:
over
Overwrite indicator:
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTSVH shandle;
char* password;
SQLTDPV lbmset;
SQLTFNP bkpdir;
SQLTFNL bkpdirl;
SQLTRFM mode=SQLMEOL;
SQLTLNG lognum;
SQLTBOO local,over;
 
static char dbname1[] = "island"; /* default database
/* name */
static char srvname[] = "SERVER1”; /* server name */
 
password = 0;
local=1;
over=1;
 
/* CONNECT TO SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
 
/* MAKE BACKUP DIRECTORIES */
 
system("mkdir \\backup\\snapshot");
 
bkpdir = "\\BACKUP\\SNAPSHOT";
bkpdirl = strlen(bkpdir);
 
/* BACKUP SNAPSHOT */
 
if (rcd = sqlbss(shandle,dbname1,0,bkpdir,bkpdirl,local,over))
apierr("SQLBSS");
else
printf("Backup Snapshot Database \n");
 
Related functions
 
sqlbdb sqlenr sqlrlf
sqlblf sqlgnl sqlrof
sqlcrf sqlrdb sqlrss
sqlcsv sqlrel
sqlcbv - Clear Bind Variables
Syntax
#include <sql.h>
 
SQLTAPI sqlcbv(cur)
 
SQLTCUR cur; /* Cursor handle */
 
Description
This function clears all information stored for bind variables for a cursor.
When a program variable is bound, information about the variable is saved. This includes pointers to the data and the name of the bind variable (if bound by name). This function clears this information and frees the memory that stores it.
Parameters
cur
The cursor handle associated with this function.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
if (rcd = sqlcbv(cur))
apierr("SQLCBV");
else
printf("Cleared Bind Variables \n");
 
Related functions
 
sqlbld sqlbnd sqlbnu
sqlbln sqlbnn sqlnbv
sqlbna
sqlcch - Create Connection Handle
Syntax
#include <sql.h>
 
SQLTAPI sqlcch(hConp, dbnamp, dbnaml, flag)
 
SQLTCON PTR hConp; /* Connection handle */
SQLTDAP dbnamp; /* Pointer to identification string */
SQLTDAL dbnaml; /* Identification string length */
SQLTMOD flag; /* future flag */
 
Description
This function establishes a new connection to the specified database. It issues a connection handle to identify the database. There can be a maximum of 256 connection handles.
Parameters
hConp
A pointer to a connection handle where this function returns a new connection handle.
dbnamp
A pointer to an identification string that contains the database name, username, and password, separated by forward slashes:
databasename/username/password
If the database name, username, or password is not specified, then the system uses the current default. For example, you can specify the following connect string in which case the default database name and username are used:
//password
These rules are used:
The default database name, username, and password are determined by:
dbnaml
The length of the string pointed to by dbnamp. If the string pointed to by the dbnamp is null-terminated, you can specify zero for the dbnaml and the system will compute the length.
flag
Future flag. Currently not defined. You can specify zero for this parameter.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTCON hCon; /* Connection Handle*/
SQLTCUR cur; /* Cursor */
SQLTRCD rcd; /* return code */

if (rcd = sqlcch(&hCon, “PAYROLL/BOSS/SECRET”,0,0))
{
printf(“Failure establihsing a connection (rcd =%d)\n”,rcd);
exit(0);
}
else printf(“New connection established\n”);

if(rcd = sqlopc(&cur, hCon, 0))
{
printf(“Failure on cursor open (rcd = %d)\n”, rcd);
exit(0);
}
else printf(“New cursor opened\n”);
.
.
.
if(rcd = sqldis(cur))
{
printf(“Failure closing cursor (rcd = %d)\n”, rcd);
exit(0);
}
else printf(“Cursor closed\n”);

if (rcd = sqldch(hCon))
{
printf(“Failure terminating connection (rcd = %d)\n”, rcd);
exit(0);
}
else printf(“Connection terminated\n”);
Related functions
 
sqldch sqldis sqlopc
sqlcdr - Cancel Database Request
Syntax
#include <sql.h>
 
SQLTAPI sqlcdr (shandle, cur)
 
SQLTSVH shandle; /* Server Handle */
SQLTDAP cur; /* Cursor Handle */
 
Description
This function cancels a SQL command.
When a database request is in progress and taking too long, sqlcdr can be invoked from another process to send a cancel message to the server. If the server is processing a request, it stops processing it and rollbacks the transaction and the process that started the request returns an error code.
If the server receives the cancel message before or after processing a request, the message is ignored.
Parameters
shandle
The server handle returned by sqlcsv.
cur
The cursor handle associated with the request that you want to cancel.
Return value
This function returns zero if the cancel message was received by the server while processing a request. If this function returns a non-zero value, it was unsuccessful.
Related functions
 
sqlsab sqlsdn sqlstm
sqlcex - Compile and EXecute
Syntax
#include <sql.h>
 
SQLTAPI sqlcex (cur,dap,dal);
 
SQLTCUR cur; /* Cursor handle */
SQLTDAP dap; /* Command buffer */
SQLTDAL dal; /* Length of SQL command */
 
Description
This function takes a SQL command or non-stored procedure as input, generates the compiled version of the command/procedure, and executes it. No data is bound.
Use this function to compile and execute a SQL command or procedure that contains no bind variables and only needs to be executed once; examples are data definition and data control commands (CREATE, DROP, GRANT, REVOKE) and data manipulation commands which meet these criteria.
This function also enables server-level commands to create, delete, or alter database areas and storage groups.
All compiled commands for all cursors that the program has connected to the database are destroyed by:
Note: You cannot compile and execute a procedure as static before storing it with the sqlsto function.
Parameters
cur
The cursor handle associated with this function.
For these SQL commands, use the server handle returned by sqlcsv instead:
ALTER DATABASE
ALTER DBAREA
ALTER STOGROUP
CREATE DATABASE
CREATE DBAREA
CREATE STOGROUP
DEINSTALL DATABASE
DROP DATABASE
DROP DBAREA
DROP STOGROUP
INSTALL DATABASE
SET DEFAULT STOGROUP
dap
A pointer to the variable that contains the command or procedure to compile and execute.
dal
The length of the variable pointed to by dap. If the value pointed to by dap is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
char * name; /* name */
char *pswd; /* password */
shor t ret; /* return code */
char errmsg [SQLMERR];
 
static char grant[] =
"GRANT CONNECT TO %s IDENTIFIED BY %s";
 
char buf[100]
sprintf (buf, grant, name, pswd);
if (sqlcex(cur, buf, 0)) /* Compile and execute */
{
sqlrcd(cur, &ret); /* Get return code */
sqlerr(ret, &errmsg); /* Get error text */
printf("%s\n", errmsg);
}
Related functions
 
sqlcom sqlcsv sqlexe
sqlclf - Change process activity Log File
Syntax
#include <sql.h>
 
SQLTAPI sqlclf (shandle, logfile, startflag)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP logfile; /* Log file name to open */
SQLTFMD startflag; /* Start activity log flag */
 
Description
This function opens a new process activity log file for the database server. Use this function to write the messages that appear on the Process Activity server display to a file. This function is useful for multi-user servers.
Instead of using the sqlclf function, you could use the sqlset function and the SQLPALG parameter.
To turn on logging, specify a file name and set startflag to 1. To turn off logging, specify a null filename or set startflag to 0.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Parameters
shandle
The server handle returned by sqlcsv.
logfile
A pointer to the null-terminated string that contains the name of the log file. If null, logging is turned off.
startflag
Indicates whether to start or stop writing to the log file:
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
SQLTSVH shandle;
SQLTDAP srvname;
char *password;
char *logfile;
int startflag;
 
srvname = "SERVER1";
password = 0;
startflag = 1;
logfile = "ACTIVITY.LOG";
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* CHANGE ACTIVITY LOG FILE */
 
printf("change activity log file to %s\n", logfile);
if (rcd = sqlclf(shandle,logfile,startflag))
apierr("SQLCLF");
else
printf("Successful change and start of server activity log
file\n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(shandle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
}
Related functions
 
sqlcsv sqlset
sqlcmt - CoMmiT
Syntax
#include <sql.h>
 
SQLTAPI sqlcmt(cur);
 
SQLTCUR cur; /* Cursor handle */
 
Description
This function commits a database transaction and starts a new transaction. All changes to the database since the last commit are made permanent and cannot be undone.
Before a commit, all changes made since the start of the transaction can be rolled back.
A commit releases all locks held by a transaction except when cursor-context preservation is on.
This function commits the work of all cursors that an application has connected to the database or connection handle.
Connecting to a database or connection handle causes an implicit commit of a transaction. After establishing this connection to the database, SQLBase issues a COMMIT to establish the starting point of the first transaction in the logging system. However, subsequent connections to other cursors are not specifically database connections, and do not cause SQLBase to issue a COMMIT or activate any transaction control devices. Also, they do not alter the flow of the current transaction and destroy compiled commands.
This function destroys all compiled commands for all cursors and connection handles connected to the database except when cursor-context preservation is on.
The database can also be committed by executing a SQL COMMIT command.
Parameters
cur
The cursor handle associated with this function.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
ret = sqlcmt(cur);
 
Related functions
 
sqlrbk
sqlcnc - CoNnect Cursor
Syntax
#include <sql.h>
 
SQLTAPI sqlcnc (curp, dbnamp, dbnaml)
 
SQLTCUR PTR curp; /* Cursor handle */
SQLTDAP dbnamp; /* Connect string */
SQLTDAL dbnaml; /* Connect string length */
 
Description
This function applies to applications in which you are connecting cursors to a specific database that belong to a single transaction.
This function connects to a database and issues a cursor handle that identifies an implicit connection to a specific database. All cursors that you connect to this database belong to a single transaction and to the same implicit connection handle.
This function can connect to a new database or connect a new cursor to the current database.
Note: To create multiple, independent connections, SQLBase allows you to explicitly create multiple connection handles. You can use connection handles for multiple transactions to the same database within an application, or for creating multi-threaded Win32 applications. For details on creating connection handles, read the section on connection handles in Chapter 3.
Parameters
curp
A pointer to the variable where this function returns the cursor handle.
dbnamp
A pointer to the connect string that contains the database name, username, and password separated by forward slashes:
database/username/password
These rules are used:
If the database name, username, or password is not specified, then the system uses the current default. For example, you can specify the following connect string in which the default database name and username are used:
//password
The default database name, username, and password are determined by:
The defaultdatabase, defaultuser, and defaultpassword keywords in sql.ini.
dbnaml
The length of the string pointed to by dbnamp. If the string pointed to by dbnamp is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTCUR cur; /* Cursor handle */
SQLTRCD rcd; /* Return code */
 
if (rcd = sqlcnc(&cur, "PAYROLL/BOSS/SECRET", 0))
{
printf("Failure on connect (rcd = %d)\n",rcd);
exit(0);
}
else
printf("Connection established\n");
 
Related functions
 
sqlcnr sqldis
sqlcnr - Connect with No Recovery
Syntax
#include <sql.h>
 
SQLTAPI sqlcnr(curp, dbnamp, dbnaml)
 
SQLTCUR PTR curp; /* Cursor handle */
SQLTDAP dbnamp; /* Connect string */
SQLTDAL dbnaml; /* Connect string length */
 
Description
This function applies to applications in which you are connecting cursors to a specific database that belong to a single transaction.
Note: To create multiple, independent connections, SQLBase allows you to explicitly create multiple connection handles. You can use connection handles for multiple transactions to the same database within an application, or for creating multi-threaded Win32 applications. For details, read the section on connection handles in Chapter 3.
This function connects to a database with recovery (transaction logging) turned off and issues a cursor handle that is associated with a single, implicit connection to a database. All cursors that you connect to this database belong to a single transaction and to the same implicit connection handle.
You must understand the implications of this function. When recovery is turned off, transaction logging is not performed and transaction rollbacks are not possible.
This function can connect to a new database or connect a new cursor to the current database.
Turning off recovery has an effect only when it is the first connect to the database. All subsequent connects to this database by any user must be done with sqlcnr. If a user tries a subsequent connect with sqlcnc, they will get an error.
Parameters
curp
A pointer to the variable where this function returns the cursor handle.
dbnamp
A pointer to the connect string that contains the database name, username, and password separated by forward slashes:
database/username/password
These rules are used:
If the database name, username, or password is not specified, then the system uses the current default. For example, you can specify the following connect string in which the default database name and username are used:
//password
The default database name, username, and password are determined by:
The defaultdatabase, defaultuser, and defaultpassword keywords in sql.ini.
dbnaml
The length of the string pointed to by dbnamp. If the string pointed to by dbnamp is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTCUR cur; /* Cursor handle */
SQLTRCD rcd; /* Return code */
 
if (rcd = sqlcnr(&cur, "PAYROLL/BOSS/SECRET", 0))
{
printf("Failure on connect (rcd = %d)\n",rcd);
exit(0);
}
else
printf("Connection with recovery turned off\n");
 
Related functions
 
sqlcnc sqldis
sqlcom - COMpile a SQL command/procedure
Syntax
#include <sql.h>
 
SQLTAPI sqlcom (cur,cmdp,cmdl);
 
SQLTCUR cur; /* Cursor handle */
SQLTDAP cmdp; /* SQL command or procedure*/
SQLTDAL cmdl; /* Length of SQL command */
 
Description
This function compiles a SQL command or non-stored procedure and stores it in the work space associated with the cursor. No data is bound. After a SQL command or procedure has been compiled, it can be executed or stored.
There are 3 steps in compiling:
1.
2.
3.
All compiled commands for all cursors that the program has connected to the database are destroyed by:
Note: You cannot compile a procedure as static before storing it with the sqlsto function.
Parameters
cur
The cursor handle associated with this function.
For these SQL commands, use the server handle returned by sqlcsv instead:
ALTER DATABASE
ALTER DBAREA
ALTER STOGROUP
CREATE DATABASE
CREATE DBAREA
CREATE STOGROUP
DEINSTALL DATABASE
DROP DATABASE
DROP DBAREA
DROP STOGROUP
INSTALL DATABASE
SET DEFAULT STOGROUP
cmdp
A pointer to the string that contains the SQL command.
cmdl
The length of the string pointed to by cmdp. If the string pointed to by cmdp is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
static char sqlcmd[] =
"SELECT A, B FROM TAB WHERE C = :1";
ret = sqlcom(cur, sqlcmd, 0);
 
Related functions
 
sqlcex sqlexe sqlsto
sqlcsv
sqlcpy - CoPY data from one table to another
Syntax
#include <sql.h>
 
SQLTAPI sqlcpy (fcur, selp, sell, tcur, isrtp, isrtl)
 
SQLTCUR fcur; /* Cursor handle for SELECT */
SQLTDAP selp; /* SELECT command */
SQLTDAL sell; /* Length of SELECT command */
SQLTCUR tcur; /* Cursor handle for INSERT */
SQLTDAP isrtp; /* INSERT command */
SQLTDAL isrtl; /* Length of INSERT command */
 
Description
This function copies data from one table to another. The destination table must exist and the data type of the destination columns must be compatible with the data in the corresponding source columns. For example, you cannot copy alphabetic data to a numeric column. The source table and the destination table can be in different databases.
This function needs two cursors: one for the SELECT command that retrieves the data from the source table, and one for an INSERT command that adds rows to the target table.
The application must issue COMMITs following a transaction that uses this function to ensure that changes are made permanent.
Each item in the SELECT statement must correspond on a one-to-one basis with each bind variable in the INSERT command. For example, bind variable :1 corresponds to the first SELECT list item and bind variable :2 corresponds to the second SELECT list item.
Parameters
fcur
The cursor handle associated with the SELECT command.
selp
A pointer to the string that contains the SELECT command that retrieves data from the source table.
sell
The length of the string pointed to by selp. If the string pointed to by selp is null-terminated, specify zero and the system will compute the length.
tcur
The cursor handle associated with the INSERT command.
isrtp
A pointer to the string that contains the INSERT command that adds the selected data to the target table.
isrtl
The length of the string pointed to by isrtp. If the string pointed to by isrtp is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
The error returned by this function does not indicate the cursor that caused the error. Check the return code for each cursor to establish the source of the error.
Example
SQLTCUR cur1 = 0; /* select cursor */
SQLTCUR cur2 = 0; /* insert cursor */
SQLTRCD rcd1 = 0; /* return code (cur1) */
SQLTRCD rcd2 = 0; /* return code (cur2) */
 
main()
{
static char select[] = /* SQL select statement */
"SELECT EMP_NO,EMP_NAME FROM EMP";
static char insert[] = /* SQL insert statement */
"INSERT INTO TMP (TMP_NO, TMP_NAME) VALUES (:1, :2)";
 
/* CONNECT TO BOTH CURSORS */
 
if (sqlcnc(&cur1, "DEMO", 0))
failure("SELECT CURSOR CONNECT");
 
if (sqlcnc(&cur2, "DEMO", 0))
failure("INSERT CURSOR CONNECT");
 
/* PERFORM COPY OPERATION */
 
if (sqlcpy(cur1,select,0,cur2,insert,0))
failure("COPY OPERATION");
 
/* COMMIT BOTH CURSORS */
 
if (sqlcmt(cur1) || sqlcmt(cur2))
failure("COMMIT");
 
/* DISCONNECT BOTH CURSORS */
 
if (sqldis(cur1))
failure("DISCONNECT OF SELECT CURSOR");
 
cur1 = 0;
 
if (sqldis(cur2))
failure("DISCONNECT OF INSERT CURSOR");
}
 
failure(ep)
char* ep; /* -> failure msg string */
{
SQLTEPO epo; /* error position */
char errmsg[SQLMERR]; /* error msg text buffer */
 
printf("Failure on %s \n", ep);
sqlrcd(cur1,&rcd1); /* get return codes */
sqlrcd(cur2,&rcd2);
 
if (rcd1) /* error on cursor 1? */
{
sqlerr(rcd1, errmsg);
sqlepo(cur1, &epo);
printf("%s(error: %u, position: %u) \n",errmsg,rcd1,epo);
}
if (rcd2) /* error on cursor 2? */
{
sqlerr(rcd2, errmsg);
sqlepo(cur2, &epo);
printf("%s(error: %u, position: %u) \n",errmsg,rcd1,epo);
}
 
if (cur1) /* cursor 1 exists? */
sqldis(cur1);
 
if (cur2) /* cursor 2 exists? */
sqldis(cur2);
 
exit(1);
}
 
sqlcre - CREate database
Syntax
#include <sql.h>
 
SQLTAPI sqlcre (shandle, dbname, dbnamel)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel; /* Database name length */
 
Description
This function physically creates a database on the specified server, returns an error if the database already exists, and adds the dbname keyword to sql.ini.
In SQLBase, a database contains a database file placed in a sub-directory. The database file must have the extension .dbs, for example, demo.dbs. The name of the sub-directory must be the same as the database file name without the extension, for example, \demo.
Do not specify an extension for a database name (demo.xyz is invalid). SQLBase automatically assigns a database name extension of .dbs.
Usually the database sub-directory is placed in the \Unify directory. This is the default, but it can be set to any location using the dbdir keyword in sql.ini.
The maximum length of the database name is 8 characters.
Parameters
shandle
The server handle returned by sqlcsv.
dbname
A pointer to the string that contains the database name.
dbnamel
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
srvname = "SERVER1";
password = 0;
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&handle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* CREATE DATABASE */
 
if (rcd = sqlcre(handle,"DEMOX",0))
apierr("SQLCRE");
else
printf("Database DEMOX Created \n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(handle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
}
 
Related functions
 
sqlcsv sqldel sqlind
sqlded
sqlcrf - Continue RollForward
Syntax
#include <sql.h>
 
SQLTAPI sqlcrf (shandle, dbname, dbnamel)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel; /* Length of database name */
 
Description
Call this function after a rollforward operation has stopped because it cannot open the next transaction log file.
Ordinarily, the sqlrlf function is used to restore the logs and sqlcrf is used to continue the rollforward. However, you can also restore the logs directly to the log directory using other means such as a tape backup or optical disk. If this is done, you must call this function explicitly to continue the rollforward process.
Parameters
shandle
The server handle returned by sqlcsv.
dbname
A pointer to the string that contains the database name.
dbnamel
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
static char dbname1[]=”omed”;
/* RESTORE DATABASE */
 
if (rcd = sqlrdb(shandle,dbname1,0,bkpdir,bkpdirl,local,over))
apierr("SQLRDB");
else
printf("Restored Database \n");
 
/* ROLLFORWARD TO END */
 
sqlrof(shandle,dbname1,0,mode,0,0);
 
/* RESTORE LOGS USING OPERATING SYSTEM COPY */
 
system("DEL \\Unify\\omed\\*.log");
system("COPY \\backup\\omed\\*.log \\Unify\\omed");
 
/* CONTINUE ROLLFORWARD */
 
sqlcrf(shandle,dbname1,0);
 
/* END ROLLFORWARD */
 
if (rcd = sqlenr(shandle,dbname1,0))
apierr("SQLENR");
else
printf("End Rollforward \n");
 
Related functions
 
sqlbdb sqlenr sqlrlf
sqlblf sqlgnl sqlrof
sqlbss sqlrdb sqlrss
sqlcsv sqlrel
sqlcrs - Close ReStriction and Result Set modes
Syntax
#include <sql.h>
 
SQLTAPI sqlcrs (cur,rsp,rsl);
 
SQLTCUR cur; /* Cursor handle */
SQLTDAP rsp; /* Result set name */
SQLTDAL rsl; /* Result set name length */
 
Description
This functions turns off both result set mode and restriction mode.
This function lets you optionally save the result set by specifying a name in rsp. To use a saved result set later, call the sqlrrs function and specify the saved result set name. The sqlrrs function turns on result set mode and restriction mode.
The sqldrs function drops a saved result set.
Be cautious about using saved result sets. Internally, a saved result set is a list of row identifiers (ROWIDs) that is stored in the SYSROWIDLISTS system catalog table. A ROWID changes whenever the row is updated. If one of the rows is updated after you have saved and closed a result set, you will get an error if you open the result set later and try to fetch the row.
Parameters
cur
The cursor handle associated with this function.
rsp
A pointer to the string that contains the name of the result set. Specify a null string (SQLNPTR) to close the result set without saving it.
rsl
The length of the string pointed to by rsp. If the string pointed to by rsp is null-terminated, specify zero and the system will compute the length. If the result set is not being saved, specify zero.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
/* Save current result set as "saveres" */
 
ret = sqlcrs(cur, "saveres", 0);
Related functions
 
sqlcrs sqlrrs sqlsrs
sqldrs sqlscn sqlstr
sqlprs sqlspr sqlurs
sqlcsv - Connect to SerVer
Syntax
#include <sql.h>
 
SQLTAPI sqlcsv (handlep, serverid, password)
 
SQLTSVH PTR handlep; /* Returned server handle */
SQLTDAP serverid; /* Null-terminated server identifier */
SQLTDAP password; /* Null-terminated server password */
 
Description
This function connects a user to a server to perform administrative operations.
This function returns a server handle that is required for the following administrative operations:
Parameters
handlep
A pointer to the variable where this function returns the server handle.
serverid
A pointer to the null-terminated string that contains the name of the server.
The server name is set by the servername keyword in sql.ini. The maximum length of a server name is 8 characters. The server name must begin with a letter.
password
A pointer to the null-terminated string that contains the server password.
The password keyword in sql.ini sets a password for a server. This keyword follows a server keyword in sql.ini.
If the server password is set, a case-insensitive comparison is performed between the server password and the sqlcsv password.
The maximum length of a server password is 8 characters.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
srvname = "SERVER1";
password = 0;
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&handle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(handle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
 
Related functions
 
All of the functions below require the server handle returned by sqlcsv.
sqlbdb sqldrr sqlmop
sqlblf sqldsv sqlmrd
sqlbss sqlenr sqlmsk
sqlclf sqlfgt sqlmwr
sqlcre sqlfpt sqlrdb
sqlcrf sqlgnl sqlrlf
sqlded sqlgsi sqlrof
sqldel sqlind sqlrss
sqldrc sqlmcl sqlsab
sqldro sqlmdl sqlstm
sqlcty - Command TYpe
Syntax
#include <sql.h>
 
SQLTAPI sqlcty (cur, cty);
 
SQLTCUR cur; /* Cursor handle */
SQLTCTY PTR cty; /* Variable */
 
Description
This function returns the command type of the SQL command currently being processed. The command type is set after sqlcom or sqlexe.
Parameters
cur
The cursor handle associated with this function.
cty
A pointer to the variable where this function returns the command type. For example, if the previously-compiled command was an UPDATE, this function returns 4. The command types are defined in sql.h.
Note that sqlcty returns the SQLTSEL command type for either a SELECT or PROCEDURE command that is compiled and current. Either command can return results to sqlfet. To determine the actual command type, use the sqlget function in conjunction with the SQLPWFC parameter. See the documentation for sqlget for more information.
Value returned in cty
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
int cmnd; /* command type */
short ret; /* return code */
 
ret = sqlcty(cur, &cmnd);
 
Related functions
 
sqlcom sqlexe
sqldbn - DataBase Names
Syntax
#include <sql.h>
 
SQLTAPI sqldbn (serverid, buffer, length)
 
SQLTDAP serverid; /* Server identifier */
SQLTDAP buffer; /* Directory list */
SQLTDAL length; /* Buffer length */
 
Description
This function returns a list of the databases on the specified server.
Use this function instead of sqldir.
Parameters
serverid
A pointer to a null-terminated string that contains the name of the server specified in sql.ini. Specify a null server name to get a directory of local databases.
buffer
A pointer to the variable where this function returns the database names.
Each name is null-terminated. The end of the list is marked by an extra null-terminator. For example, the database names demo, payables, and emp are returned in this format:
demo\0payables\0emp\0\0
length
The length of the area pointed to by buffer.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
srvname="SERVER1";
 
/* DIRECTORY OF DATABASES */
 
if (rcd = sqldbn(srvname,buffer,len))
apierr("SQLDBN");
else
{
j = 0;
printf("Directory of Databases : ");
while ( (buffer[j] != '\n') && (j< 20) )
{
if (buffer[j] == '\0')
{
printf(", ");
}
else
{
printf("%c",buffer[j]);
}
j++;
}
printf("\n");
}
}
 
Related functions
 
sqldir
sqldch - Destroy Connection Handle
Syntax
#include <sql.h>
 
SQLTAPI sqldch (hCon);
 
SQLTCON hCon; /* Connection handle */
 
Description
This function terminates a specific connection. Before terminating a connection, it is good programming practice to commit the transaction and close all open cursors. This function automatically closes any open cursors before destroying the connection handle.
When terminating a connection, this function commits or rolls back the current transaction before terminating the connection. By default, sqldch will COMMIT the transaction for a SQLBase server before terminating the connection. For the default behavior of servers other than SQLBase, read your applicable server documentation.
To modify the default connect closure behavior for both SQLBase and non-SQLBase servers, use the sqlset() function call with the SQLPCCB parameter. For details, read information on the sqlset function in this chapter.
Parameters
hCon
The handle to the connection to be terminated.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
if (rcd = sqldch(hCon))
{
printf(“Failure terminating connection (rcd = %d)\n”, rcd);
exit(0);
}
else printf(“Connection terminated\n”);
 
Related functions
 
sqlcch sqlopc sqldis
sqlded - DEinstall Database
Syntax
#include <sql.h>
SQLTAPI sqlded (shandle, dbname, dbnamel)
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel ; /* Database name length */
 
Description
This function:
Removes the dbname keyword from sql.ini.
This function does not physically delete the database.
You cannot deinstall a database that has a user connected.
Parameters
 
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
srvname = "SERVER1";
password = 0;
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&handle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
if (rcd = sqlcre(handle,"DEMOX",0))
apierr("SQLCRE");
else
printf("Database DEMOX Created \n");
/* DEINSTALL DATABASE */
if (rcd = sqlded(handle,"DEMOX",0))
apierr("SQLDED");
else
printf("Database DEMOX Deinstalled \n");
/* INSTALL DATABASE */
if (rcd = sqlind(handle,"DEMOX",0))
apierr("SQLIND");
else
printf("Database DEMOX Installed \n");
/* DISCONNECT FROM THE SERVER */
if (rcd = sqldsv(handle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
}
 
Related functions
 
sqlcre, sqldel, sqlind, sqlcsv
sqldel - DELete database
Syntax
#include <sql.h>
SQLTAPI sqldel (shandle, dbname, dbnamel)
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel; /* Database name length */
 
Description
This function physically deletes the entire database directory for a database including all associated transaction log files on the server. If the log is redirected, the log directory for the database is also completely removed.
This function removes the dbname keyword from sql.ini.
Parameters
 
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
srvname = "SERVER1";
password = 0;
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&handle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* DELETE DATABASE */
 
if (rcd = sqldel(handle,"DEMOX",0))
apierr("SQLDEL");
else
printf("Database DEMOX Deleted \n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(handle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
}
 
Related functions
 
sqlcre, sqlded, sqlind, sqlcsv
sqldes - DEScribe items in a SELECT list
Syntax
#include <sql.h>
 
SQLTAPI sqldes (cur, slc, ddt, ddl, chp, chlp, prep, scap)
 
SQLTCUR cur; /* Cursor handle */
SQLTSLC slc; /* Select column number */
SQLTDDT PTR ddt; /* Database data type */
SQLTDDL PTR ddl; /* Database data length */
SQLTCHP chp; /* Column heading buffer */
SQLTCHL PTR chlp; /* Column heading length */
SQLTPRE PTR prep; /* Numeric precision */
SQLTSCA PTR scap; /* Numeric scale */
 
Description
This function returns the database data type and length for a column in a SELECT list.
This function differs from sqldsc which returns the external data type and length. The external data type is defined in the SYSCOLUMNS system catalog table. External data types match program data types in sql.h.
The following diagram shows how the value of the SQLPDIS parameter (SQLDELY, SQLDDLD, or SQLDNVR) controls when (and if) describe information for a SELECT statement is available for sending to a client. You can specify the SQLPDIS parameter’s value using the sqlset function.
When describe information is available, given the different SQLPDIS parameter settings.
This table summarizes the information illustrated above:
SQLDELY
early
The server sends describe information after sqlcom; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlexe.
The server also sends describe information after sqlcex; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlfet.
SQLDDLD
delayed
The server sends describe information after sqlexe. Calling sqldes, sqldsc, or sqlgdi after calling sqlexe but before the first sqlfet is legal; calling sqldes, sqldsc, or sqlgdi at any other time is illegal.
The server also sends describe information after sqlcex; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlfet.
Use this setting to reduce message traffic for database servers that do not support compile (sqlcom) operations (like Microsoft’s SQL Server).
SQLDNVR
never
The server never sends describe information; any call to sqldes, sqldsc, or sqlgdi is illegal.
When SQLPDIS is set to SQLDNVR, sqlnsi always returns 0. You must hard code the number of SELECT items so that the application knows how many times to call sqlssb.
Use this setting to reduce message traffic when the application always knows the number and type of columns in a SELECT statement and never makes calls to sqldes, sqldsc, or sqlgdi.
You can pass null pointers (SQLNPTR) for arguments that you do not want.
You can retrieve the number of columns in the SELECT list with the sqlnsi function call.
Parameters
cur
The cursor handle associated with this function.
slc
The column number (starting with 1) in the SELECT list about which to return information.
ddt
A pointer to the variable where this function returns the database data type of the column.
ddl
A pointer to the variable where this function returns the length of the column.
Note that the length returned for numeric and date/time columns are for display and printing. Use the sqldsc function to get the length as stored in SQLBase’s internal format.
chp
A pointer to the variable where this function returns the column heading defined in the SYSCOLUMNS system catalog table.
chlp
A pointer to the variable where this function returns the length of the string pointed to by chp.
prep
A pointer to the variable where this function returns the precision of a numeric column.
scap
A pointer to the variable where this function returns the scale, if any, of a numeric column.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
static char select[] = "SELECT * FROM TEST";
 
char ddt; /* Datatype */
char colnam[50]; /* Column heading buffer */
unsigned char i;
unsigned char ddl; /* Data length */
int prec, scale; /* Precision, scale */
int hdl; /* Heading length */
uchar nsi; /* Number of SELECT items */
 
sqlnsi(cur, &nsi);
for (i = 1; i <= nsi; i++)
{
memset(colnum, '\0', 50);
if sqldes(cur,i,&ddt,&ddl,colnam,&hdl,&prec,&scale))
{
. .. process error
}
printf("%d %d %s %d %d %d\n”, ddt, ddl, colnam, hdl,
prec, scale);
}
 
Related functions
 
sqlcom, sqldsc, sqlexe, sqlgdi, sqlnsi, sqldes2
sqldii - Describe Into variable
Syntax
#include <sql.h>
 
SQLTAPI sqldii (cur, ivn, inp, inl);
 
SQLTCUR cur; /* Cursor handle*/
SQLTSLC ivn; /* INTO variable position number */
SQLTDAP inp; /* INTO variable name */
SQLTCHL PTR inl; /* INTO variable name length*/
 
Description
This function describes an INTO variable.
Parameters
cur
The cursor handle associated with this function.
ivn
The relative position of the INTO variable, starting at 1.
inp
A pointer to the string that contains the name of the INTO variable.
inl
A pointer to the variable where this function returns the length of the INTO variable’s name.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
#include "sql32.h"
#include <memory.h>
#include <stdio.h>
#include <stdlib.h>
 
/*------------------------------------------------------ */
/* */
/* Example of a simple fetch */
/* */
/* Run EMP.SQ L via SQLTALK to initialize tables and data */
/* */
/*-------------------------------------------------------*/
 
SQLTCUR cur; /* SQLBASE cursor number */
SQLTRCD rcd; /* error number */
char errmsg[SQLMERR]; /* error msg text buffer */
void failure(char*); /* error routine */
 
main()
{
char name[20]; /* employee name buffer */
SQLTCHL PTR nii;
SQLTCHL PTR inl;
SQLTSLC ivn;
SQLTDAP inp;
static char selcmd [] = /* SQL SELECT statement */
"SELECT EMP_NAME into :name FROM EMP ";
/*
CONNECT TO THE DATABASE
*/
 
if (rcd = sqlcnc(&cur, "ISLAND", 0))
{
sqlerr(rcd, errmsg); /* get error message text */
printf("%s \n",errmsg);
return(1);
}
 
/*
COMPILE SELECT STATEMENT
*/
 
if (sqlcom(cur, selcmd, 0))
failure("SELECT COMPILE");
 
/*
PERFORM sqldii
*/
 
if (sqldii(cur,1,name,inl))
failure ("SQLDII");
else
printf("The length of the into variable is
%d\n",*inl);
 
/*
SET UP SELECT BUFFER
*/
 
if (sqlssb(cur, 1, SQLPBUF, name, 20, 0, SQLNPTR,
SQLNPTR))
failure("SET SELECT BUFFER");
 
/*
EXECUTE SELECT STATEMENT
*/
 
if (sqlexe(cur))
failure("EXECUTING SELECT");
 
/*
FETCH DATA
*/
for (;;)
{
memset(name,' ',20); /* clear employe name buf */
 
if (rcd = sqlfet(cur)) /* fetch the data */
break;
printf("%s\n", name); /* print employe name */
}
 
if (rcd != 1) /* failure on fetch */
failure("FETCH");
 
/*
DISCONNECT FROM THE DATABASE
*/
 
if (rcd = sqldis(cur))
failure("DISCONNECT");
}
 
void failure(ep)
char* ep; /* failure msg string */
{
SQLTEPO epo; /* error position */
 
printf("Failure on %s \n", ep);
 
sqlrcd(cur, &rcd); /* get the error */
sqlepo(cur, &epo); /* get error position */
sqlerr(rcd, errmsg); /* get error message text */
 
sqldis(cur); /* disconnect cursor */
 
printf("%s (error: %u, position: %u)
\n",errmsg,rcd,epo);
exit(1);
}
 
Related functions
 
sqlnii, sqldii2
sqldir - DIRectory of databases
Syntax
#include <sql.h>
 
SQLTAPI sqldir (svrno, buffer, length)
 
SQLTSVN svrno; /* Server number */
SQLTDAP buffer; /* Database names */
SQLTDAL length; /* Length of buffer */
 
Description
This function returns a list of database names on the specified server.
This function is provided for backwards compatibility with earlier versions of SQLBase. When creating new applications, do not use this function; use the sqldbn function instead.
Parameters
svrno
A numeric literal that specifies the server. The system appends this literal to "server" to form the server name set in sql.ini.
Specify a zero to return a list of local databases.
buffer
A pointer to the variable where this function returns the database names. Each name is null-terminated. The end of the list is marked by an extra null-terminator. For example, the database names demo, payables and emp are returned in this format:
demo\0payables\0emp\0\0
length
The length of the value pointed to by buffer. The list of database names is truncated if buffer is not large enough.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
char buf[100]; /* database directory buffer */
short ret; /* return code */
short srvr; /* server number */
 
srvr = 1;
 
ret = sqldir(srvr, buf, sizeof(buf));
if (ret)
... process error
 
Related functions
 
sqldbn
sqldis - DISconnect from cursor
Syntax
#include <sql.h>
 
SQLTAPI sqldis (cur);
 
SQLTCUR cur; /* Cursor handle */
 
Description
This function disconnects a cursor. If you are closing the final cursor, note the difference in behavior between cursors connected through implicit, or explicit connections. For details, read the section Connection Handles, in Chapter 3, Using the SQL/API.
If you are disconnecting a final cursor that is connected implicitly with the sqlcnc or the sqlcnr function, a COMMIT is performed before the cursor is disconnected. If you are using the sqlcnc() function call, you can use the sqlset() API function call with the SQLPCCB parameter and specify the ROLLBACK option. When this is set, a roll back is performed before the cursor is disconnected.
If you are disconnecting a final cursor that is connected explicitly with the sqlopc function, the cursor remains pending and is not automatically committed. Note that cursors connected with the sqlopc function belong to a specific connection handle. Each connection handle represents a single transaction and its connection to a single database. The transaction is either committed or rolled back only when the connection handle is terminated using the sqldch function call.
You can specify whether a transaction is rolled back or committed by:
using the sqlset() API function call with the SQLPCCB parameter. By default, the setting is server dependent and in the case of SQLBase the DEFAULT is COMMIT.
explicitly executing a COMMIT, ROLLBACK, sqlcmt(), or sqlrbk() when the connection handle is terminated.
Parameters
cur
A cursor handle of cursor to be closed.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
if(rcd = sqldis(cur))
{
printf(“Failure closing cursor (rcd = %d)\n”, rcd);
exit(0);
}
else printf(“Cursor closed\n”);

Related functions
 
sqlcch, sqlopc, sqldch
sqldon - DONe
Syntax
#include <sql.h>
 
SQLTAPI sqldon ( )
 
Description
This function does a rollback and disconnects all open cursors.
This function is often used in conjunction with sqlini. If sqlini was called, sqldon must be called before the program exits to free allocated resources.
See testwin.cpp for an example of how to use this function. This online file is provided with your SQLBase shipment.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
int PASCAL WinMain (hInstance, hPrevInstance, lpszCmdLine,
cmdShow)
 
HANDLE hInstance;
HANDLE hPrevInstance;
LPSTR lpszCmdLine;
int cmdShow;
{
short ret; /* return code */
 
extern int far pascal yieldpgm();
sqlini(MakeProcInstance(yieldpgm,hInstance));
...
if (ret = sqldis(cur)) /* disconnect */
... process error
 
sqldon(); /* Disconnect all cursors */
return;
}
 
Related functions
 
sqlini
sqldox - Directory Open eXtended
Syntax
#include <sql.h>
 
SQLTAPI sqldox (shandle, dirname, attribute)
 
SQLTSVH shandle; /* Server Handle */
SQLTDAP dirname; /* Directory name to open */
SQLTFLG attribute; /* file attribute to use on read */
 
Description
This function opens the file directory specified by dirname on the database server associated with shandle.
After you open a directory, you use sqldrr to read the file names in the directory. Only those file names that match the file attribute (defined in sql.h) will be returned.
Use the sqldrc function to close the directory.
The sqldox function does not return a handle for the directory because a program can only have one directory opened at a time. If you perform sqldox when a directory is already open, the current open directory is automatically closed.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Parameters
shandle
The server handle returned by sqlcsv.
dirname
A pointer to a null-terminated string that contains the name of the directory to open.
attribute
File attribute flags which can be logically ORed to return combinations of files that match the attribute flag.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTSVH shandle;
SQLTDAP srvname;
SQLTFLG fattribute;
char *password;
char *dirname;
int modulo;
char buffer[3000];
 
srvname = "SERVER1";
password = 0;
dirname = "\\Unify";
fattribute = SQLADIR;
/* CONNECT TO SERVER */
 
if (rcd = sqlcsv(&shandle, srvname, password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* directory open, read and close */
printf("Directory open, read and close \n");
 
printf("\nOpen a directory of %s\n", dirname);
if ((rcd = sqldox(shandle, dirname, fattribute)) != 0)
apierr("SQLDOX");
else
{
printf("Directory opened successfully, rcd=%d\n", rcd);
module = 0;
while ((rcd = sqldrr(shandle, buffer)) == 0)
{
if ((modulo++ % 3) == 0)
printf("\n");
printf("%-13s", buffer);
}
printf("\n");
printf("sqldrr() = %u\n", rcd);
if (rcd = sqldrc(shandle))
apierr("SQLDRC");
else
printf("Directory closed successfully, rcd=
%d\n", rcd);
}
 
printf("End of directory open, read, and close\n");
 
/* DISCONNECT FROM SERVER */
 
if (rcd = sqldsv(shandle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
 
Related functions
 
sqlcsv, sqldrc, sqldrr
sqldrc - DiRectory Close
Syntax
#include <sql.h>
 
SQLTAPI sqldrc(shandle)
 
SQLTSVH shandle; /* Server handle */
 
Description
This function closes the directory on the database server associated with shandle that the program opened with the sqldro function.
Call this function after sqldrr has read the last file name in the directory.
A program can only have one directory opened at a time. If you perform a sqldro function when a directory is already open, the current open directory is automatically closed.
Parameters
shandle
The server handle returned by sqlcsv.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTSVH shandle;
SQLTDAP srvname;
char *password;
char *dirname;
int modulo;
char buffer[3000];
 
srvname = "SERVER1";
password = 0;
dirname = "\\Unify";
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* directory open, read and close */
 
printf("Directory open, read, close \n");
 
printf("\nOpen a directory of %s\n", dirname);
if ((rcd = sqldro(shandle, dirname)) != 0)
apierr("SQLDRO");
else
{
printf("Directory opened successfully,
rcd=%d\n",rcd); modulo = 0;
while ((rcd = sqldrr(shandle, buffer)) == 0)
{
if ((modulo++ % 3) == 0)
printf("\n");
printf("%-13s", buffer);
}
printf("\n");
printf("sqldrr() = %u\n", rcd);
 
if (rcd = sqldrc(shandle))
apierr("SQLDRC");
else
printf("Directory closed successfully, rcd=
%d\n",rcd);
 
}
printf("End of directory open, read, and close\n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(shandle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
 
Related functions
 
sqlcsv, sqldro, sqldrr
sqldro - DiRectory Open
Syntax
#include <sql.h>
 
SQLTAPI sqldro (shandle, dirname)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP dirname; /* Directory name to open */
 
Description
This function opens the file directory specified by dirname on the database server associated with shandle.
After you open a directory, you use sqldrr to read the file names in the directory.
Use the sqldrc function to close the directory.
The sqldro function does not return a handle for the directory because a program can only have one directory opened at a time. If you perform sqldro when a directory is already open, the current open directory is automatically closed.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Parameters
shandle
The server handle returned by sqlcsv.
dirname
A pointer to a null-terminated string that contains the name of the directory to open.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTSVH shandle;
SQLTDAP srvname;
char *password;
char *dirname;
int modulo;
char buffer[3000];
 
srvname = "SERVER1";
password = 0;
dirname = "\\GUPTA";
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* directory open, read and close */
printf("Directory open, read, close \n");
 
printf("\nOpen a directory of %s\n", dirname);
if ((rcd = sqldro(shandle, dirname)) != 0)
apierr("SQLDRO");
else
{
printf("Directory opened successfully, rcd=%d\n",rcd);
modulo = 0;
while ((rcd = sqldrr(shandle, buffer)) == 0)
{
if ((modulo++ % 3) == 0)
printf("\n");
printf("%-13s", buffer);
}
printf("\n");
printf("sqldrr() = %u\n", rcd);
if (rcd = sqldrc(shandle))
apierr("SQLDRC");
else
printf("Directory closed successfully, rcd=
%d\n",rcd);
 
}
printf("End of directory open, read, and close\n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(shandle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
 
Related functions
 
sqlcsv, sqldrc, sqldrr
sqldrr - DiRectory Read
Syntax
#include <sql.h>
 
SQLTAPI sqldrr (shandle, filename)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP filename; /* File name buffer */
 
Description
This function reads a file name in the directory on the database server into the variable specified by filename.
This function is called after a sqldro function.
The sqldrr function returns one file name per call. The file name returned is only the base name for the file; the name does not include the directory name prefix.
Parameters
shandle
The server handle returned by sqlcsv.
filename
A pointer to the variable where this function returns the file name. The file name is null-terminated.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
This function returns an error code after the last file name has been read to indicate that the end of the directory has been reached.
Example
SQLTSVH shandle;
SQLTDAP srvname;
char *password;
char *dirname;
int modulo;
char buffer[3000];
 
srvname = "SERVER1";
password = 0;
dirname = "\\GUPTA";
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* directory open, read and close */
printf("Directory open, read, close \n");
 
printf("\nOpen a directory of %s\n", dirname);
if ((rcd = sqldro(shandle, dirname)) != 0)
apierr("SQLDRO");
else
{
printf("Directory opened successfully,
rcd=%d\n",rcd);
modulo = 0;
while ((rcd = sqldrr(shandle, buffer)) == 0)
{
if ((modulo++ % 3) == 0)
printf("\n");
printf("%-13s", buffer);
}
printf("\n");
printf("sqldrr() = %u\n", rcd);
 
if (rcd = sqldrc(shandle))
apierr("SQLDRC");
else
printf("Directory closed successfully,
rcd= %d\n",rcd);
 
}
printf("End of directory open, read, and close\n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(shandle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
 
Related functions
 
sqlcsv, sqldrc, sqldro
sqldrs - Drop Result Set
Syntax
#include <sql.h>
 
SQLTAPI sqldrs (cur,rsp,rsl)
 
SQLTCUR cur; /* Cursor handle */
SQLTDAP rsp; /* Result set name buffer */
SQLTDAL rsl; /* Result set name length */
 
Description
This function drops a saved result set. The result set must have been created by calling sqlcrs and specifying a name.
Parameters
cur
The cursor handle associated with this function.
rsp
A pointer to the string that contains the name of the result set.
rsl
The length of the string pointed to by rsp. If the string pointed to by rsp is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
/* Drop result set "saveres" */
ret = sqldrs(cur, "saveres", 0);
 
Related functions
 
sqlcrs sqlrrs sqlstr
sqldrs sqlspr sqlurs
sqlprs sqlsrs
sqldsc - DeSCribe item in a SELECT command
Syntax
#include <sql.h>
 
SQLTAPI sqldsc (cur, slc, edt, edl, chp, chlp, prep, scap)
 
SQLTCUR cur; /* Cursor handle */
SQLTSLC slc; /* Select column number */
SQLTDDT PTR edt; /* External data type */
SQLTDDL PTR edl; /* External data length */
SQLTCHP chp; /* Column heading buffer */
SQLTPTR PTR chlp; /* Column heading length */
SQLTPRE PTR prep; /* Numeric precision */
SQLTSCA PTR scap; /* Numeric scale */
 
Description
This function returns external data type and length for a column in a SELECT list.
The external data type is defined in the SYSCOLUMNS system catalog table. External data types match program data types in sql.h. This function differs from sqldes which returns the database data type and length.
The following diagram shows how the value of the SQLPDIS parameter (SQLDELY, SQLDDLD, or SQLDNVR) controls when (and if) describe information for a SELECT statement is available for sending to a client. You can specify the SQLPDIS parameter’s value using the sqlset function.
When describe information is available, given the different SQLPDIS parameter settings
This table summarizes the information illustrated above:
SQLDELY
early
The server sends describe information after sqlcom; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlexe.
The server also sends describe information after sqlcex; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlfet.
SQLDDLD
delayed
The server sends describe information after sqlexe. Calling sqldes, sqldsc, or sqlgdi after calling sqlexe but before the first sqlfet is legal; calling sqldes, sqldsc, or sqlgdi at any other time is illegal.
The server also sends describe information after sqlcex; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlfet.
Use this setting to reduce message traffic for database servers that do not support compile (sqlcom) operations (like Microsoft’s SQL Server).
SQLDNVR
never
The server never sends describe information; any call to sqldes, sqldsc, or sqlgdi is illegal.
When SQLPDIS is set to SQLDNVR, sqlnsi always returns 0. You must hard code the number of SELECT items so that the application knows how many times to call sqlssb.
Use this setting to reduce message traffic when the application always knows the number and type of columns in a SELECT statement and never makes calls to sqldes, sqldsc, or sqlgdi.
Specify null pointers (SQLNPTR) for arguments that you do not want.
You can retrieve the number of columns in the SELECT lists with the sqlnsi function.
Parameters
cur
The cursor handle associated with this function.
slc
The column number (starting with 1) in the SELECT list to get information about. You can use the column number to set up a loop and call sqldsc for each column in the SELECT list.
edt
A pointer to the variable where this function returns the external data type of the column.
edl
A pointer to the variable where this function returns the external data length of the column:
Note that the length returned for numeric and datetime columns are as stored in SQLBase's internal format. Use the sqldes function to get the length for printing and display.
chp
A pointer to the variable where this function returns the column heading.
chlp
A pointer to the variable where this function returns the column heading length.
prep
A pointer to the variable where this function returns the precision of a numeric column.
scap
A pointer to the variable where this function returns the scale, if any, of a of a numeric column.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
SQLTNSI nsi; /* number of select items
SQLTSLC i; /* column number to describe
SQLTDDT edt; /* external data type
SQLTDDL edl; /* external data length
char buf[19]; /* buffer for column name
SQLTPTR chl; /* column header length
SQLTPRE prec; /* precision
SQLTSCA scale; /* scale
 
static char dbnam[] = "demox";
static char selcom[] = "SELECT * FROM TEST";
 
...
 
/* COMPILE THE SELECT COMMAND */
 
if (rcd = sqlcom(cur, selcom, 0))
apierr("SQLCOM");
 
if (rcd = sqlnsi(cur,&nsi))
apierr("SQLNSI");
/* DESCRIBE */
 
for (i = 1; i <= nsi; i++)
{
memset(buf, '\0', sizeof(buf)); /* fill the buffer with
nulls */
if (rcd = sqldsc(cur,i,&edt,&edl,buf,&chl,&prec,&scale))
apierr("SQLDSC");
printf("i=%d, edt=%d, edl=%d, colname=%s, chl=%d, prec=%d,
scale=%d\n", i,edt,edl,buf,chl,prec,scale);
}
 
if (rcd = sqldis(cur))
apierr("SQLDIS");
 
}
 
Related functions
 
sqldes sqlgdi sqlnsi
sqldsc2
sqldst - Drop STored command/procedure
Syntax
#include <sql.h>
 
short sqldst (cur, cnp, cnl);
 
SQLTCUR cur; /* Cursor handle */
SQLTDAP cnp; /* Command/procedure name buffer */
SQLTDAL cnl; /* Command/procedure name length */
 
Description
This function drops a stored command or stored procedure.
Parameters
cur
The cursor handle associated with this function.
cnp
A pointer to a string that contains the name of the SQL command or procedure to drop.
cnl
The length of the string pointed to by cnp. If the string pointed to by cnp is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
ret = sqldst(cur, "myquery", 0);
 
Related functions
 
sqlsto
sqldsv - Disconnect from SerVer
Syntax
#include <sql.h>
 
SQLTAPI sqldsv (handle)
 
SQLTSVH handle; /* Server handle */
 
Description
This function disconnects from a server.
After the server connection is broken, you will not be able to perform administrative functions.
Parameters
shandle
The server handle returned by sqlcsv.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
srvname = "SERVER1";
password = 0;
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&handle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(handle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
}
 
Related functions
 
sqlcsv
sqlelo - End Long Operation
Syntax
#include <sql.h>
 
SQLTAPI sqlelo (cur)
 
SQLTCUR cur; /* Cursor handle */
 
Description
This function ends a LONG VARCHAR operation. This function removes the overhead necessary for handling LONG VARCHAR columns.
Parameters
cur
The cursor handle associated with this function.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
ret=sqlelo(cur);
 
Related functions
 
sqlbld sqlgls sqlrlo
sqlbln sqllsk sqlwlo
sqlenr - ENd Rollforward
Syntax
#include <sql.h>
 
SQLTAPI sqlenr (shandle, dbname, dbnamel)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP dbname; /* Database name */
SQLTDAL dbnamel; /* Length of database name */
 
Description
Call this function after a rollforward operation has stopped because it cannot open the next transaction log file. If the next log file is not available, call this function to finish the rollforward recovery based on the logs processed up to that point.
Parameters
shandle
The server handle returned by sqlcsv.
dbname
A pointer to the string that contains the database name.
dbnamel
The length of the string pointed to by dbname. If the string pointed to by dbname is null-terminated, specify zero and the system will compute the length.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTSVH shandle;
char* password;
SQLTDPV lbmset;
SQLTFNP bkpdir;
SQLTFNL bkpdirl;
SQLTRFM mode=SQLMEOL;
SQLTLNG lognum;
SQLTBOO local,over;
 
static char dbname1[] = "omed";
 
password = 0;
bkpdir = "\\BACKUP\\OMED";
bkpdirl = strlen(bkpdir);
printf("value of bkpdir = %s \n",bkpdir);
 
local=1;
over=1;
 
/* CONNECT TO SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
 
/* RESTORE DATABASE */
 
if (rcd = sqlrdb(shandle,dbname1,0,bkpdir,bkpdirl,local,over))
apierr("SQLRDB");
else
printf("Restored Database \n");
 
/* ROLLFORWARD TO END */
 
sqlrof(shandle,dbname1,0,mode,0,0);
 
lognum=0;
 
/* The loop below assumes that all log file backups */
/* are on disk.*/
/* If a log file backup is not on disk, lognum is set */
/*to a */
/* non-zero value which causes the loop to terminate. */
 
while (lognum == 0)
{
/* GET NEXT LOG */
sqlgnl(shandle,dbname1,0,&lognum);
 
/* RESTORE LOG FILES */
sqlrlf(shandle,dbname1,0,bkpdir,bkpdirl,local,over);
}
/* END ROLLFORWARD */
 
if (rcd = sqlenr(shandle,dbname1,0))
apierr("SQLENR");
else
printf("End Rollforward \n");
 
Related functions
 
sqlbdb sqlcsv sqlrlf
sqlblf sqlgnl sqlrof
sqlbss sqlrdb sqlrss
sqlcrf sqlrel
sqlepo - Error POsition
Syntax
#include <sql.h>
 
SQLTAPI sqlepo (cur, epo)
 
SQLTCUR cur; /* Cursor handle */
SQLTEPO PTR epo; /* Error position */
 
Description
This function returns the error position in the SQL command now being processed by the specified cursor. The error position is set after sqlcom or sqlcex.
When a SQL/API function returns an error, the offset of the error in the SQL command is set. The error position is meaningful after a compile or an execute because it points to the position in a SQL command where a syntax error was detected.
Parameters
cur
The cursor handle associated with this function.
epo
A pointer to a variable where this function returns the error position offset. The first character in the SQL command is position zero.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTEPO errpos; /* error position */
short ret; /* return code */
 
if (!sqlcom(cur, sqlcmd, 0))
ret = sqlepo(cur, &errpos);
 
Related functions
 
sqlcom sqlcex
sqlerr - ERRor message
Syntax
#include <sql.h>
 
SQLTAPI sqlerr (error, msg)
 
SQLTRCD error; /* Error code */
SQLTDAP msg; /* Message text */
 
Description
This function returns the text of the error message associated with the error code. The text comes from the file error.sql.
Each SQL/API function returns a code. You can retrieve the most recent code with the function sqlrcd function.
The file error.sql contains message text for every return code. Each entry in error.sql contains the error code, mnemonic, message text, and the message reason and remedy for that code.
When a program detects an error condition, it uses the error code to look up the error message. Use the sqlerr function to retrieve the error message text (without the mnemonic) associated with a return code. Use the sqlfer function to retrieve the error message text and the mnemonic associated with a return code.
Parameters
error
The error code to retrieve the message text for.
msg
A pointer to the variable where this function returns the error message text. The error message text is a null-terminated string. SQLMERR is a constant in sql.h that indicates the size of the error message text buffer. This function always returns error message text.
Return value
This function returns zero if the value specified in error exists in error.sql. If this function returns a non-zero value, it means that the value in error does not exist in error.sql. The text returned in msg will also indicate this.
Example
char errmsg [SQLMERR]; /* buffer for error msg */
short ret; /* return code */
 
if (ret = sqlexe(cur))
{
sqlerr(ret, errmsg); /* get error message */
printf("%s \n", errmsg); /* print error message */
}
 
Related functions
 
sqletx, sqlrcd, sqlxer, sqlfer
sqletx - Error message TeXt
Syntax
#include <sql.h>
 
SQLTAPI sqletx (rcd, msgtyp, bfp, bfl, txtlen)
 
SQLTRCD rcd; /* Error code to get text for */
SQLTPTY msgtyp; /* Message text type */
SQLTDAP bfp; /* Ptr to receiving buffer */
SQLTDAL bfl; /* Length of receiving buffer */
SQLTDAL PTR txtlen; /* Length of retrieved text */
 
Description
This function retrieves one or more of the following from the error.sql file for the specified error code:
Each API function call returns a code. You can retrieve the most recent error code with the sqlrcd function. When an application program detects an error condition, it can use the error code to look up the error message, error reason, and error remedy.
Parameters
rcd
The error code to retrieve information for.
msgtyp
You can specify the following message types individually or together by adding the constants together. For example, a value of seven indicates that you want the error message text, reason, and remedy all returned in the buffer that bfp points to.
Retrieve error message text. The sqlerr function does the same thing.
bfp
A pointer to the buffer where this function copies the error message text, reason, or remedy.
bfl
Length of the buffer pointed at by bfp.
If you are retrieving the error message text, reason, and remedy, you can specify the sql.h constant SQLMETX for this argument. SQLMETX is always set to a value that is large enough to hold the error message text, reason, and remedy.
If you are only retrieving the error message text, you can specify the sql.h constant SQLMERR for this argument. SQLMERR is always set to a value that is large enough to hold the error message text.
txtlen
A pointer to the variable where this function returns the number of bytes retrieved.
For example, if the buffer is 100 bytes and requested text is 500 bytes, this function returns 100 bytes in bfp and a value of 500 in txtlen. The application program could then allocate a larger buffer to retrieve the entire text string.
Specify a null pointer if you do not want the total length of the text.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
This example retrieves the error message text, reason, and remedy after calling sqlcom.
SQLTCUR cur; /* cursor value */
SQLTRCD rcd; /* error code to get text for */
char buf[1000]; /* buffer to receive the text */
SQLTDAL txtlen; /* length of returned text */
 
if (rcd = sqlcom(cur, "CREATE TABLE EMP (LASTNAME
CHAR(20))", 0))
{
sqletx(rcd, SQLXMSG + SQLXREA + SQLXREM, buf,
sizeof(buf), &txtlen)
printf("Error Explanation:\n%s\n", buf);
}
 
If you only wanted the remedy text, you would call the sqletx function as follows:
sqletx(rcd, SQLXREM, buf, sizeof(buf), &txtlen)
 
Related functions
 
sqlerr, sqlrcd, sqlxer, sqlfer
sqlexe - EXEcute a SQL command/procedure
Syntax
#include <sql.h>
 
SQLTAPI sqlexe (cur)
 
SQLTCUR cur; /* Cursor handle */
 
Description
This function executes a previously-compiled command or procedure.
The command or procedure executed can be one compiled earlier in the current application or one that was stored and retrieved.
If the command or procedure contains bind variables, data must be bound before execution.
Parameters
cur
The cursor handle associated with this function.
To execute the following SQL commands, use the server handle returned by sqlcsv instead:
ALTER DATABASE
ALTER DBAREA
ALTER STOGROUP
CREATE DATABASE
CREATE DBAREA
CREATE STOGROUP
DEINSTALL DATABASE
DROP DATABASE
DROP DBAREA
DROP STOGROUP
INSTALL DATABASE
SET DEFAULT STOGROUP
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
if (ret = sqlexe(cur))
{
... process error
}
 
Related functions
 
sqlcex, sqlcom, sqlcsv
sqlexp - EXecution Plan
Syntax
# include <sql.h>
 
SQLTAPI sqlexp (cur, buffer, length)
 
SQLTCUR cur; /* Cursor handle */
SQLTDAP buffer; /* Execution plan buffer */
SQLTDAL length; /* Length of buffer */
 
Description
This function returns the execution plan for a compiled SQL command. The execution plan shows the tables, views, indexes, and optimizations for the SQL command. Each line in the plan represents one table or view needed to process the SQL command.
Table and views for the SQL command are listed in the order in which they will be processed.
The SELECT column contains a number that identifies all the tables or views for a given SELECT.
The TABLE column contains the name of the table or view. System generated temporary tables are identified in the TABLE column as TEMP TABLE. For views and temporary tables, the table identifier is followed by the number of the SELECT which will be processed to produce the rows for the table or view.
The INDEX column contains the name of the index to use for the table. TEMP INDEX indicates a system-generated temporary index.
OPTIONS shows the processing options which have been selected.
INDEX MERGE
IN optimization. When doing a join for purposes of satisfying an IN with a subselect, "quickly terminate" on the first satisfaction of the IN condition.
Parameters
cur
The cursor handle associated with this function.
buffer
A pointer to the variable where this function returns the execution plan for the command. Each line of the execution plan is terminated with a linefeed character. The end of the execution plan is terminated with a null.
length
The length of the value pointed to by buffer.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
First, set up an area to receive the execution plan:
char buf [2000]
 
Then, compile a SQL command such as the one shown below:
SELECT DISTINCT S#, P#, QTY FROM SPJ
WHERE QTY =
(SELECT MAX(QTY) FROM SPJ SPJY, S
WHERE SPJY.P# = SPJ.P#
AND SPJY.S# = S.S#
AND S.CITY = 'ATHENS')
 
Call the sqlexp function:
ret = sqlexp(cur, buf, sizeof (buf));
 
The area buf will contain an execution plan as shown below.
EXECUTION PLAN:
 
SELECT TABLE INDEX OPTIONS
======= == ================= ============ =========
1 SPJ
1 TEMP TABLE-SEL TEMP INDEX
2 S
2 SPJ SPJX INDEXMERGE
 
sqlfer - Full ERror message
Syntax
#include <sql.h>
 
SQLTAPI sqlfer (error, msg)
 
SQLTRCD error; /* Error code */
SQLTDAP msg; /* Message buffer */
 
Description
This function returns the full text of the error message associated with the error code specified by error. The text that this function returns comes from error.sql.
Each SQL/API function returns a code. You can retrieve the most recent code with the function sqlrcd function.
The file error.sql contains message text for every return code. Each entry in error.sql contains the error code, the mnemonic, and the message text for that code.
When a program detects an error condition, it uses the error code to look up the error message. Use the sqlerr function to retrieve the error message text (without the mnemonic) associated to a return code. Use the sqlfer function to retrieve the error message text and the mnemonic associated to a return code
Parameters
error
The error code to retrieve the message text for.
msg
A pointer to the variable where this function returns the full error message text. The error message text is a null-terminated string. SQLMERR is a constant in sql.h that indicates the size of the error message text. This function always returns error message text.
Return value
This function returns zero if the value in error exists in error.sql. If this function returns a non-zero value, it means that the value in error does not exist in error.sql. The text returned in msg will also indicate this.
Example
#include "sql.h"
#include "stdio.h"
 
#define ERR_NUMS 12
 
main()
{
SQLTRCD error; /* error code */
int row_num;
char msg_buf[200];
 
static int msg_line[ERR_NUMS] =
{
1, 4, 2104, 9001, 9100, 9286, 9287, 9288, 9289, 9301,
171, 3001
};
 
for (row_num=0;row_num<ERR_NUMS;row_num++)
{
sqlfer(msg_line[row_num],msg_buf);
printf("Output from SQLFER(): %s\n",msg_buf);
}
 
}
 
Related functions
 
sqlerr, sqlrcd, sqlxer, sqletx
sqlfet - FETch next row from result set
Syntax
#include <sql.h>
 
SQLTAPI sqlfet (cur)
 
SQLTCUR cur; /* Cursor handle */
 
Description
This function fetches the next row resulting from a query. A successful sqlexe or sqlcex must come before this function. This function returns an end of fetch value (1) when there are no more rows to fetch.
This function is associated with fetchable commands. In SQLBase, a fetchable command is one that can return a result through sqlfet. The SELECT and PROCEDURE commands are fetchable commands. This means that you can fetch results from a SELECT or PROCEDURE command until you reach the end of output.
Retrieve LONG VARCHAR columns with the sqlrlo function.
If there is an error, the return code will not indicate the column that caused the problem. Check the pfc variable (set up with sqlssb) or use sqlgfi to determine the column in error.
Parameters
cur
The cursor handle associated with this function.
Return value
This function returns the values shown in the table below during normal operation. Any other value returned means that an error occurred.
Example
ret = sqlfet(cur);
 
Related functions
 
sqlcex, sqlgfi, sqlssb, sqlexe
sqlfgt - GeT File from server
Syntax
#include <sql.h>
 
SQLTAPI sqlfgt(shandle, srvfile, lclfile)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP srvfile; /* Server filename */
SQLTDAP lclfile; /* Local file name */
 
Description
This function copies the file specified by srvfile on the database server associated to shandle to the file lclfile on the client computer.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Parameters
shandle
The server handle returned by sqlcsv.
srvfile
A pointer to the null-terminated string that contains the name of the file on the database server to copy.
lclfile
A pointer to the null-terminated string that contains the name of the file on the client computer where the server file is copied.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
SQLTSVH shandle;
SQLTDAP srvname;
char *password;
char *srvfile;
char *lclfile;
 
srvname = "SERVER1";
password = 0;
srvfile = "sql.h";
lclfile = "localsql.h";
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
if (rcd = sqlfgt(shandle, srvfile, lclfile))
apierr("SQLFGT");
else
printf("Successful Get File from Server \n");
 
srvfile = "srvsqlfl.h";
 
if (rcd = sqlfpt(shandle, srvfile, lclfile))
apierr("SQLFPT");
else
printf("Successful Put File to Server \n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(shandle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
}
 
Related functions
 
sqlcsv, sqlfpt
sqlfpt - PuT File to server
Syntax
#include <sql.h>
 
SQLTAPI sqlfpt (shandle, srvfile, lclfile)
 
SQLTSVH shandle; /* Server handle */
SQLTDAP srvfile; /* Server file name */
SQLTDAP lclfile; /* Local file name */
 
Description
This function copies the file specified by lclfile on the client computer to the file srvfile on the database server associated to shandle.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Parameters
shandle
The server handle returned by sqlcsv.
srvfile
A pointer to the null-terminated string that contains the name of the file on the database server where the client file is copied.
lclfile
A pointer to the null-terminated string that contains the name of the file on the client computer to copy.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
main()
{
SQLTSVH shandle;
SQLTDAP srvname;
char *password;
char *srvfile;
char *lclfile;
 
srvname = "SERVER1";
password = 0;
srvfile = "sql.h";
lclfile = "localsql.h";
 
/* CONNECT TO THE SERVER */
 
if (rcd = sqlcsv(&shandle,srvname,password))
apierr("SQLCSV");
else
printf("Connection Established to Server \n");
 
if (rcd = sqlfgt(shandle, srvfile, lclfile))
apierr("SQLFGT");
else
printf("Successful Get File from Server \n");
 
srvfile = "srvsqlfl.h";
 
if (rcd = sqlfpt(shandle, srvfile, lclfile))
apierr("SQLFPT");
else
printf("Successful Put File to Server \n");
 
/* DISCONNECT FROM THE SERVER */
 
if (rcd = sqldsv(shandle))
apierr("SQLDSV");
else
printf("Disconnected from Server \n");
}
 
Related functions
 
sqlcsv, sqlfgt
sqlfqn - Fully-Qualified column Name
Syntax
#include <sql.h>
 
SQLTAPI sqlfqn (cur, col, nameptr, namelen)
 
SQLTCUR cur; /* Cursor handle */
SQLTFLD field; /* Field number */
SQLTDAP nameptr; /* Column name */
SQLTDAL PTR namelen; /* Length of column name */
 
Description
This function returns the fully-qualified name of a column in a SELECT list. The function can be called only after a SELECT command has been compiled or retrieved because this is the only time the information is available.
An attempt to get a SELECT list element that is not a database column name causes an error. This can happen when a SELECT list item is an expression, a view column name derived from an expression, or a constant.
This function is faster than a query on the SYSCOLUMNS system catalog table.
This function differs from sqldes and sqldsc because it returns the fully-qualified name of the underlying table of a column in a SELECT list. The sqldes and sqldsc functions only return the column heading.
Parameters
cur
The cursor handle associated with this function.
field
The column number that indicates the sequence number (starting with 1) of the item in the SELECT list for which the fully-qualified name is wanted.
nameptr
A pointer to the variable where this function returns the name. The fully-qualified name of a column has this form:
username.tablename.columnname
namelen
A pointer to the variable where this function returns the length of the name.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
#define NOTCOL 5131 /* select list element not a
column name error */
 
static char select[] = "select name, phone, from empview; ";
char colname[50];
uint cvl;
uint col;
short ret; /* return code */
 
/* get fully qualified name */
 
memset(colname, ' ', sizeof(colname)); /*initialize */
for (col=1; col <= 2; col++)
{
if (ret = sqlfqn(cur, col, colname, &cvl ))
{
if (ret == NOTCOL)
continue; /* not a real column */
else
... process error
}
ProcessName (colname, cvl);
}
 
Related functions
 
sqldsc sqldes
sqlgbc - Get Backend Cursor
Syntax
#include <sql.h>
 
SQLTAPI sqlgbc (cursor, curp)
 
SQLTCUR cursor; /* Cursor Handle */
SQLTCUR PTR curp; /* Cursor Handle */
 
Description
This function retrieves the backend cursor handle for the supplied cursor handle.
Parameters
cursor
A cursor handle returned by sqlcnc.
curp
A pointer to the variable where this function returns the backend cursor handle.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTCUR cur; /* Cursor handle */
SQLTCUR curp; /* Cursor handle */
SQLTRCD rcd; /* Return code */
 
 
if (rcd = sqlcnc( &cur, "PAYROLL/BOSS/SECRET", 0))
{
printf("Failure on connect (rcd = %d \n", rcd);
exit(0);
}
else
{
if ((rcd = sqlgbc( cur, &curp)) != 0)
{
apierr("SQLGBC");
}
else
{
printf("Backend Cursor: %d \n", curp);
}
}
sqlgbi - Get Backend Information
Syntax
#include <sql.h>
 
SQLTAPI sqlgbi (cursor, curp, pnmp)
 
SQLTCUR cursor; /* Cursor Handle */
SQLTCUR PTR curp; /* Backend cursor handle ptr */
SQLTPNM PTR pnmp; /* Backend process number ptr */
 
Description
This function retrieves the backend cursor handle and process number for the supplied cursor handle.
Parameters
cursor
A cursor handle returned by sqlcnc.
curp
A pointer to the variable where this function returns the backend cursor handle.
pnmp
A pointer to the variable where this function returns the backend process number.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
SQLTCUR cur; /* Cursor handle */
SQLTCUR curp; /* Backend cursor handle */
SQLTPNM pnmp; /* Backend process number */
SQLTRCD rcd; /* Return code */
 
 
if (rcd = sqlcnc( &cur, "PAYROLL/BOSS/SECRET", 0))
{
printf("Failure on connect (rcd = %d \n", rcd);
exit(0);
}
else
{
if ((rcd = sqlgbi( cur, &curp, &pnmp)) != 0)
{
apierr("SQLGBC");
}
else
{
printf("Backend Cursor: %d Backend Process: %d \n", curp, pnmp);
}
}
 
sqlgdi - Get Describe Information
Syntax
#include <sql.h>
 
SQLTAPI sqlgdi (cur, gdidef);
 
SQLTCUR cur; /* Cursor handle */
SQLTPGD gdidef; /* Describe structure */
 
Description
This function returns descriptive information about a column in a SELECT list.
This function returns all the descriptive information that sqldes and sqldsc return as well as the column label and the null indicator.
The diagram below shows how the SQLPDIS settings (SQLDELY, SQLDDLD, and SQLDNVR) control when describe information is available. You can specify the SQLPDIS parameter’s value by calling the sqlset function.
The following table explains how the setting of the SQLPDIS parameter controls when you can call sqlgdi. The SQLPDIS parameter controls when (and if) describe information for a SELECT statement is sent to a client.
SQLDELY
early
The server sends describe information after sqlcom; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlexe.
The server also sends describe information after sqlcex; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlfet.
SQLDDLD
delayed
The server sends describe information after sqlexe. Calling sqldes, sqldsc, or sqlgdi after calling sqlexe but before the first sqlfet is legal; calling sqldes, sqldsc, or sqlgdi at any other time is illegal.
The server also sends describe information after sqlcex; subsequent calls to sqldes, sqldsc, or sqlgdi are legal until after a call to sqlfet.
Use this setting to reduce message traffic for database servers that do not support compile (sqlcom) operations (like Microsoft’s SQL Server).
SQLDNVR
never
The server never sends describe information; any call to sqldes, sqldsc, or sqlgdi is illegal.
When SQLPDIS is set to SQLDNVR, sqlnsi always returns 0. You must hard code the number of SELECT items so that the application knows how many times to call sqlssb.
Use this setting to reduce message traffic when the application always knows the number and type of columns in a SELECT statement and never makes calls to sqldes, sqldsc, or sqlgdi.
You can retrieve the number of columns in the SELECT list with the sqlnsi function and then use the number of columns in a loop that calls sqlgdi for each column.
Parameters
cur
The cursor handle associated with this function.
gdidef
This is a structure that you define in the program where this function returns information about a column. The structure and typedefs below are defined in sql.h:
struct gdidefx
{
ubyte1 gdifl1[31]; /* filler reserved for future use */
ubyte1 gdifl2; /* filler reserved for future use */
ubyte1 gdilbb[31]; /* label buffer */
SQLTLBL gdilbl; /* label info length */
SQLTSLC gdicol; /* select column number */
SQLTDDT gdiddt; /* database data type */
SQLTDEDL gdiddl; /* database extended data length */
SQLTDDT gdiedt; /* external data type */
SQLTDEDL gdiedl; /* external extended data length */
SQLTPRE gdipre; /* decimal precision */
SQLTSCA gdisca; /* decimal scale */
byte2 gdinul; /* null indicator */
ubyte1 gdichb[47]; /* column heading buffer */
SQLTCHL gdichl; /* column heading length */
byte1 gdifil[2]; /* for future use */
};
typedef struct gdidefx gdidef;
typedef struct gdidefx SQLTGDI;
typedef struct gdidefx* SQLTPGD;
#define GDISIZ sizeof(gdidef)
 
The table below explains the elements in the structure. You only need to fill-in gdicol before calling sqlgdi.
The column heading (name) defined in the SYSCOLUMNS system catalog table.
Typedef in sql.h Number Data type
SQLDCHR 1 Character
SQLDNUM 2 Numeric
SQLDDAT 3 Date-time
SQLDLON 4 Long
SQLDDTE 5 Date (only)
SQLDTIM 6 Time (only)
Data type Length
Character Size specified when column was defined.
Numeric 27 (22 digits of precision plus room for scientific notation).
Typdef in sql.h Number Data type
SQLEINT 1 INTEGER
SQLESMA 2 SMALLINT
SQLEFLO 3 FLOAT
SQLECHR 4 CHAR
SQLEVAR 5 VARCHAR
SQLELON 6 LONGVAR
SQLEDEC 7 DECIMAL
SQLEDAT 8 DATE
SQLETIM 9 TIME
SQLETMS 10 TIMESTAMP
SQLEMON 11 MONEY
SQLEDOU 12 DOUBLE
SQLEGPH 13 GRAPHIC
SQLEVGP 14 VARGRAPHIC
SQLELGP 15 LONG
VARGRAPHIC
SQLEBIN 16 BINARY
SQLEVBI 17 VAR BINARY
SQLELBI 18 LONG BINARY
SQLEBOO 19 BOOLEAN
Data type Length
FLOAT 4 or 8
CHAR Size specified when column was defined.
VARCHAR Size specified when column was defined.
-1 Column can contain null value.
0 Column cannot contain null value.
Return value
If this function returns zero, it was successful. If this function returns a non-zero value, it was unsuccessful.
Example
sqlgdi(cur, gdidef);
 
Related functions
 
sqldes, sqllab, sqlnsi, sqldsc, sqlgdi2
sqlget - GET parameter
Syntax
#include <sql.h>
 
SQLTAPI sqlget (cur/shandle, parm, pbuf, len)
 
SQLTCUR cur/shandle;/* Database cursor or server
handle */
SQLTPTY parm; /* Parameter type */
SQLTDAP pbuf; /* Information buffer */
SQLTDAL PTR len; /* Information length */
 
Description
This function retrieves individual database parameters. Pass a parameter type and retrieve a corresponding value and length.
Note: SQLBase supports filenames up to 256 characters including the terminating null character.
Adapter Identifier. This parameter allows the setting of an network adapter identification string.
If you call sqlset and specify the SQLPAID parameter, it changes the setting of the adapter_id keyword in win.ini.
Process Activity file name. The file to which SQLBase writes the messages displayed on a multi-user servers Process Activity screen.
Apply net log. This parameter disables internal condition checking while a netlog is being applied.
If you call sqlset and specify the SQLPANL parameter, it changes the setting of the applynetlog keyword in sql.ini.
0 = Off
1 = On
Activate process timing. When this parameter is on (1), activation times are accumulated for prepares, executes and fetches. Activation times are accumulated at three different levels; system, process, and cursor. By default, this parameter is turned off.
0 = Off
1 = On
Note that if you are using the sqlset function to set the SQLPCTL (command time limit) parameter, parameter settings for the SQLPAPT (activate process timing) and SQLPSTA (statistics for server) parameters can be affected in the following ways:
When you enable a command time limit (by specifying a non-zero value in either the cmdtimeout keyword of the server’s sql.ini file or with the SQLPCTL parameter), SQLPSTA (statistics for server) and SQLPAPT (process timing) are automatically turned on.
If you turn off a command time limit, SQLPSTA (statistics for server) and SQLPAPT (process timing) are automatically turned off, unless you explicitly turned on either parameter after you enabled a command time limit.
If you explicitly turn off either SQLPSTA (statistics for server) or SQLPAPT (process timing), your command time limit (if you enabled on) is turned off and sql.ini is updated to reflect cmdtimeout=0.
It is recommended that if you set a value for any of these three parameters, you should set the same value for the other two. For example, if you set SQLPAPT parameter On (1), you should also set SQLPCTL and SQLPSTA parameters On (1).
Autocommit. Commits the database automatically after each SQL command. By default this parameter is Off (0) and SQLBase commits the database only when you issue a COMMIT command.
Autocommit is cursor-specific. When you set autocommit On (1) for a cursor and then perform an operation with that cursor, SQLBase commits all of the transaction’s cursors. Performing operations with cursors that do not have autocommit set on does not affect the rest of the transaction’s cursors.
OS averaging window size. This parameter specifies the number of samples of the CPU % Utilization value to keep for determining the average value. You can specify a window size of 1 to 255. The default setting is one (1). If you call sqlset and specify the SQLPAWS parameter, it changes the setting of the osavgwindow keyword in sql.ini.
0 = Off
1 = 255 units
Bulk execute mode. Reduces the network traffic for multi-row inserts, deletes, and updates. In bulk execute mode, data values are buffered so that many rows can be sent to the server in one message.
Increasing the size of the output message buffer (with the sqloms function) increases the number of operations that can be buffered in one message to the server, thereby improving performance.
SQLBALB - HP Allbase
SQLBAPP - SQLHost Application Services
SQLBAS4 - IBM AS/400 SQL/400
SQLBDB2 - IBM DB2
SQLBDBC - Teradata DBC Machines
SQLBIGW - Informix
SQLBIOL - Informix On-Line
SQLBNTW - NetWare SQL
SQLBORA - Oracle
SQLBSQB - Unify SQLBase
SQLBSHR - Teradata ShareBase
Backend result sets. If the database server supports backend result sets, this parameter’s value is 1 (Yes); otherwise, its value is 0 (No).
Size of database cache (in 1 KByte pages). This parameter sets the cache which buffers database pages in memory. The larger the cache, the less the disk input and output. In other words, as you increase the value of the cache setting, disk access is reduced.
If you call sqlset and specify the SQLPCAC parameter, it changes the setting of the cache keyword in sql.ini, but the new setting does not take effect until SQLBase is restarted.
Connect Closure Behavior. This parameter specifies the connect closure behavior that occurs when you terminate a connection using the sqldch function. Valid options are COMMIT, ROLLBACK, or DEFAULT. The default is 0 which means that connect closure behavior is dependent on the database server to which the user is connected. In the case of SQLBase, the DEFAULT setting (0) issues a COMMIT before a connection handle is terminated. To determine the DEFAULT behavior for other servers, read the applicable server documentation.
Setting this parameter on (1) instructs the server to issue a COMMIT before a connection handle is terminated, while a setting of (2) issues a ROLLBACK.
This option also specifies whether a COMMIT or ROLLBACK is issued before disconnecting to a cursor with an implicit connection using the sqlcnc function.
Client check. This parameter tells SQLBase to send the client a RECEIVE upon receipt of a request.
By default, clientcheck is off (0). When SQLBase has finished executing a command, it issues a SEND request to the client with the results of the command. If successful, the server then issues a RECEIVE request and waits to receive another command.
Setting this parameter on (1) instructs SQLBase to issue a RECEIVE request before beginning execution of the command, not after it finishes executing the command. Doing so allows SQLBase to detect a situation where the client session is dropped or a cancel request is made during command processing.
If you call sqlset and specify the SQLPCCK parameter, it changes the setting of the clientcheck keyword in sql.ini.
0 = Off
1 = On
Connection collation. Collation for the current connection. Collation specifies the language that SQLBase uses to sort data on a server, a particular database, or a particular connection.
Contiguous cache pages in cache group. This parameter specifies the number of contiguous cache pages to allocate. For example if you set cache at 3000, and cachegroup at 30, SQLBase allocates 100 cache groups, consisting of 30 pages each.
If you call sqlset and specify the SQLPCGR parameter, it changes the setting of the cachegroup keyword in sql.ini.
0 = Chained command does not contain a SELECT command.
1 = Chained command does contain a SELECT command.
In versions of SQLBase prior to 8.5, the configuration file name was hard-coded as SQL.INI, and the file was searched for using a specific algorithm (described in the Database Administrator Guide). In version 8.5 and later, using this parameter retrieves the fully-qualified path and file name of the configuration file being used by the client.
Client identifier. This parameter returns a client identification string.
Commit logging. When this parameter is On (1), SQLBase causes every database transaction in which data was modifed to log a row of data. The data that is logged contains the transaction’s identifier (Transaction ID) and a unique sequence number.
When the COMMIT operation is executed for a transaction that is modified, the data is logged in the system utility table SYSCOMMITORDER. The SYSCOMMITORDER table lists transactions that operated on the database in the order in which they were committed. For details on the SYSCOMMITORDER table, see “Appendix C,” in the Database Administrator’s Guide. Turning the SQLPCLG parameter Off (0), which is the default, stops commit logging.
Turning the SQLPCLG parameter Off (0), which is the default, stops commit logging. You must have DBA privileges to set the SQLPCLG parameter and to use DDL commands with the SQLPCLG parameter.
LOAD/UNLOAD Client Value. The load/unload’s ON CLIENT clause value.
0 = Off (file is on the server)
1 = On (file is on the server)
Client name. The name of a client computer.
Message compression. When message compression is On (1), messages sent between a client and the database server or gateway are compressed. This means that messages are shorter, and more rows can be packed into a single message during bulk insert and fetch operations.
The compression algorithm collapses repeating characters (run-length encoding). SQLBase performs the compression incrementally as each component of a message is posted.
Commit server status. Indicates whether commit service is enabled for the server.
0 = Off
1 = On
LOAD/UNLOAD control file indicator. Indicates whether a file is a load/unload control file.
0 = Not a control file
1 = Is control file
You can use this parameter in conjunction with the SQLPCTF parameter (control filename) to obtain information about a file after you compile the load/unload statement.
Checkpoint time interval. How often SQLBase should perform a recovery checkpoint operation. SQLBase’s automatic crash recovery mechanism requires that recovery checkpoints be done.
The default checkpoint time interval is one minute. This should yield a crash recovery time of less than a minute. If your site can tolerate a longer crash recovery time, you can increase this interval to up to 30 minutes.
Depending on the applications running against the database server, a checkpoint operation can affect performance. If this happens, you can increase the checkpoint interval until you attain the desired performance.
Command time limit. The amount of time (in seconds) to wait for a SELECT, INSERT, UPDATE, or DELETE statement to complete execution. After the specified time has elapsed, SQLBase rolls back the command.
Note that if you are using the sqlset function to set the SQLPCTL (command time limit) parameter, settings for the SQLPAPT (activate process timing) and SQLPSTA (statistics for server) parameters can be affected in the following ways:
When you enable a command time limit (by specifying a non-zero value in either the cmdtimeout keyword of the server’s sql.ini file or with the SQLPCTL parameter), SQLPSTA (statistics for server) and SQLPAPT (process timing) are automatically turned on.
If you turn off a command time limit, SQLPSTA (statistics for server) and SQLPAPT (process timing) are automatically turned off, unless you explicitly turned on either parameter after you enabled a command time limit.
If you explicitly turn off either SQLPSTA (statistics for server) or SQLPAPT (process timing), your command time limit (if you enabled on) is turned off and sql.ini is updated to reflect cmdtimeout=0.
It is recommended that if you set a value for any of these three parameters, you should set the same value for the other two. For example, if you set SQLPCTL parameter On (1), you should also set SQLPAPT and SQLPSTA parameters On (1).
Character set file name. This parameter identifies a file that specifies different values for the ASCII character set.
This is useful for non-English speaking countries where characters in the ASCII character set have different hex values than those same characters in the U.S. ASCII character set.
If you call sqlset and specify the SQLPCTS parameter, it changes the setting of the characterset keyword in sql.ini.
Country file section (for example, France). This parameter tells SQLBase to use the settings in the specified section of the country.sql file. SQLBase supports English as the standard language, but it also supports many national languages including those spoken in Europe and Asia. You specify information that enables SQLBase to support another language in the country.sql file. If you call sqlset and specify the SQLPCTY parameter, it changes the setting of the country keyword in sql.ini.
Execution plan cost. SQLBase uses a cost-based optimizer to determine the most efficient way to access data based on the available indexes, system catalog statistics, and the composition of a SQL command. The access plan SQLBase chooses is the one with the lowest estimated cost.
DBDIR keyword information. The drive, path, and database directory name information specified for the sql.ini’s DBDIR keyword.
Database mode. Indicates whether the database is local or remote.
SQLMDBL = local
SQLMRTR = remote
Database name. The name of the database that you are accessing.
Database collation. Default collation for the database. Collation specifies the language that SQLBase uses to sort data on a server, a particular database, or a particular connection.
Default database name. This overrides the SQLBase default database name of DEMO.
Database directory. The drive, path, and directory name where the
database you are connected to resides.
Describe information control. When (and if) SQLBase sends describe information for a SELECT command to a client.
SQLDELY (0) means early and is the default value. The server sends describe information after a call to sqlcom. Call sqldes, sqldsc, or sqlgdi after sqlcom and before sqlexe. The server also sends describe information after a call to sqlcex. Call sqldes,