Invoking an SQR Program by Using the SQR API

The SQR API is provided in Microsoft Windows through a Dynamic Link Library (dll). You can use the SQR API from any application that is capable of calling dll functions. For C and C++ applications, a header file (sqrapi.h) and an import library (sqrwin.lib) are provided. SQR requires the following .dll files to run for Microsoft Windows: sqrw.dll, bclw32.dll, libsti32.dll, and stimages.dll. These dll files are located in the BINW directory.

On platforms other than Microsoft Windows, the SQR API is provided as a static library (sqr.a or sqr.lib). For C and C++ applications, a header file (SQRAPI.H or sqrapi.h) is provided. Be sure to include the SQR API library and your database library when you link your C or C++ application. Three additional libraries are required: sqrlibsti64.a , sqrbcl.a and sqrzlib.a.

The following table describes the API functions that are defined for calling SQR:

Function	Description
int sqr(char *)	Runs an SQR program. Passes the address of a null terminated string containing an SQR command line, including program name, connectivity information, flags, and arguments. This function is a synchronous call. It returns when the SQR program has finished. This function returns zero if it is successful.
void sqrcancel(void)	Cancels a running SQR program. The program may not stop immediately because SQR waits for any currently pending database operations to finish. Because the SQR function does not return until the SQR program has finished, sqrcancel is called by using another thread or some similar asynchronous method.
int sqrend(void)	Releases memory and closes cursors. Cursors can be left open to speed up repeated running of the same SQR program. Call this function after the last program has run or optionally between SQR program runs. This function always returns zero.

Function

Description

int sqr(char *)

Runs an SQR program. Passes the address of a null terminated string containing an SQR command line, including program name, connectivity information, flags, and arguments. This function is a synchronous call. It returns when the SQR program has finished. This function returns zero if it is successful.

void sqrcancel(void)

Cancels a running SQR program. The program may not stop immediately because SQR waits for any currently pending database operations to finish.

Because the SQR function does not return until the SQR program has finished, sqrcancel is called by using another thread or some similar asynchronous method.

int sqrend(void)

Releases memory and closes cursors. Cursors can be left open to speed up repeated running of the same SQR program. Call this function after the last program has run or optionally between SQR program runs.

This function always returns zero.

For the benefit of C and C++ programmers, the APIs are declared in the sqrapi.h file. Include this header file in your source code:

#include 'sqrapi.h'

When you call SQR from a program, the most recently run SQR program is saved in memory. If the same SQR program is run again with either the same or different arguments, the program is not scanned again and the SQL statements are not parsed again. This feature provides a significant improvement in processing time.

To force SQR to release its memory and database cursors, call sqrend() at any time.

Although memory is automatically released when the program exits, you must call sqrend before the calling program quits to ensure that SQR properly cleans up any database resources, such as database cursors and temporarily stored procedures.

To relink SQR on all UNIX/Linux platforms, use the sqrmake and makefile files that are located in $SQRDIR/../lib. After you invoke sqrmake and optionally select the specific database version to link with, the SQR executables are re-created.

Check which cc command line is created and invoked for SQR, and adapt it to your program. Each UNIX/Linux platform and database has its own requirements. Consult your operating system and database product documentation for specific information.

Check the make files or link scripts that are supplied with SQR for details. You may want to copy and modify those to link in your program.

To call SQR, call sqr() and pass a command line. For example, in C:

status = sqr("myprog sammy/baker arg1 arg2 arg3");
if (status != 0)
      ...error occurred...

The following table describes the standalone and callable error values that SQR returns:

Error Value	Description
0	Normal exit.
1	Error exit.
2	Cannot process SQRERR.DAT.
3	Command-line flag in error.
4	Problem creating the .SQT file.
5	Program did not compile.
6	Problem with the .SQR/.SQT file (open/read).
7	Problem with the .LIS file (create/write).
8	Problem with the .ERR file (create/write).
9	Problem with the .LOG file (create/write).
10	Problem with the POSTSCRI.STR file (open/read).
11	Cannot call SQR recursively.
12	Problem with Microsoft Windows.
13	Internal error occurred.
14	Problem with SQRWIN.DLL.
15	Problem with -ZCF file.

Error codes 9 and 12 are applicable to the Microsoft Windows release only.

For more information about linking with SQR, see your installation guide.

See the product documentation for PeopleSoft 9.2 Application Installation.