action.skip

Migrating to CitOESQL


CitSQL and CitOESQL Comparison

Implementation Comparison CitSQL CitOESQL
Command Line >citsql [options|@optionFile](source file(s)|@sourcesFile) >citoesql [options] [@]filesNames(s)

Options may include USE

Command line options

CitSQL CitOESQL
:CloseOnCommit=[True/False]

For Oracle compatibility, cursors after a commit.
-CLOSEONCOMMIT=YES|NO

-CLOSEONROLLBACK=YES|NO
:CursorSynteticName=[True/False]

Causes the Cursor Name to be generated dynamically at runtime by the RCQ runtime.
Unique cursor names are always generated at runtime.
:DBEncoding=<Codepage or UTF-8]

Specifies what encoding is used by the DB storage.
ODBC drivers provide conversion between the client codepage and the database encoding, it is not necessary to inform the precompiler of the database encoding.
:DeallocateCloseCursor=[True/False]

Causes the CLOSE CURSOR statement to also deallocate the DECLAREd cursor.
No equivalent. CitOESQL maintains a cache of prepared statements to optimize performance, cursors, and other prepared statements. These are deallocated when necessary using a least recently used algorithm.
:DefaultCCSID=<Valid codepage or UTF-8)

Specifies the default CCSID for string fields that have no explicit CCSID declaration.
No equivalent, however, ODBC drivers will automatically convert data between the client and database encodings.
:DebugMode= [TRUE/FALSE]

Default [FALSE] When set to TRUE, causes log file created when LogMode=TRUE to contain more detail in some situations.
The TRACELEVEL option provides varying degrees of logging for diagnostic and optimization purposes.

ODBC provides its own API logging capability that can be turned on and off without recompiling an application.
:ForceStringMode=[TRUE/FALSE]

When set to True, CitSQL noncompound PIC X data fields are sent to the database as a C-String (where the String is terminated by the character X’00’). When set to FALSE, CitSQL sends PIC X data to the database as a byte-array.
-[NO]ALLOWNULLCHAR
:FreeFormatOutput=[TRUE/FALSE]

Default [FALSE] When set to TRUE, causes output of the precompiler to be created in “free” source format.
- SOURCEFORMAT=(FIXED|FREE|VARIABLE)
:ImmediateCursor=[True/False]

(CitSQL for PostgreSQL Only) When set to True, causes as PREPARE EXEC to be executed before the OPEN when a CURSOR is declared with OPEN and FETCH statements

Attention should be taken when applying the ImmediateCursor preprocessor parameter. Since the full results of the cursor are returned before the OPEN statement, this parameter should only be applied for cursors returning small numbers of lines.

(CitSQL for PostgreSQL Only) When set to TRUE, causes a PREPARE EXEC statement to be executed before the OPEN statement when a CURSOR is declared with OPEN and FETCH statements.

NOTE: Attention should be taken when applying the ImmediateCursor preprocessor parameter. Since the full results of the cursor are returned before the OPEN statement, this parameter should only be applied for cursors returning small numbers of lines.
Declare cursor is purely declarative which enables it to be placed in the DATA DIVISION, which some legacy applications depend on.

CitOESQL optimizes cursor behavior for SELECT INTO statements and OPEN CURSOR statements.
:IncludeSearchPath=<Path>

Default [Current Working Directory] A comma, or semicolon separated list of the directories in which CitSQL will look for Include files.
COBCPY environment variable plus current directory.
:LibName=<libname>

Defaults are: RCQMYSQL (MySQL) and RCQPGSQL (PostgreSQL.
No equivalent. The runtime library odbcrw32.dll (or its Linux equivalent shared object) may not be renamed.
:LogMode=[TRUE/FALSE]

Default is: [FALSE] When set to TRUE the runtime component creates a log file called RCQDLL.log that traces all SQL operations.
-TRACELEVEL=<number>
:MaxMem=<number megabytes>

Default is: 100 Allocates memory for the precompilation of very large source files.
No equivalent.
:NoRecCode=<numeric>

Default is 1403. Allows mapping of value returned to indicate the end of a FETCH statement.
Default is 100 as defined by ANSI. -ERRORMAP can be used to override default 100 value.
:Prefetch=<numeric>

Allows for the prefetch of records in a network transaction, where there is a whole number that represents the number of records to read in a networked transaction. The Prefetch option is available only with PGSQL.
-PF_RO_CURSOR
-PF_UPD_CURSOR

Prefetch sizes may be set separately for read only and updatable cursors. High values may benefit read only cursors but can cause concurrency conflicts for updatable cursors. Available with all databases.
:QuoteTranslation=<pattern>

Default is: QDB

Allows mapping of single quotes, double quotes, and back quotes. By default, quotes are unchanged, which corresponds to a default value of QuoteTranslation=QDB.
No equivalent.

All major databases allow use of single and double quotes consistently in line with ANSI.

Mapping of back quotes could be helpful to applications developed for Microsoft Access being ported to other databases.
:SelectPrepare=[True/False]

(CitSQL for PostgreSQL Only) Default is TRUE. Now, the preprocessor causes the PREPARE EXEC statement to be executed prior to the OPEN statement and the results stored. When set to False, the former behavior is applied.
No similar requirement.
:StandardPrefix=<prefix>

Default is: [None] Characters prefixed to generated data items.
Currently all generated data items are prefixed by ‘PCS-‘ (for precompiler services).
StepLimit=<numeric>

The CitSQL parser is based on a Backtracking technology. In order to do this, it must set a limit on the number of cases it must be able to consider. You can control this limit with the :StepLimit option. Normally you will not need to use the :StepLimit option.

The CitSQL parser is based on a Backtracking technology where it must set a limit on the number of cases it must be able to consider. You can control this limit with the :StepLimit option. In general you will not need to use the :StepLimit option.
No similar requirement
;StrictMode=[TRUE/FALSE]

Default is: [FALSE] When set to TRUE, the CitSQL precompiler aborts in cases where it does not recognize an SQL syntax in an EXEC statement.
-[NO]CHECK (plus
-DB=<connectionName> and -
PASS=<userid>.<password>)

When set a database connection will be used at compile time to validate SQL statements.
:StrictPictureMode=[TRUE/FALSE]

Default is: [FALSE] When set to TRUE, the CitSQL precompiler aborts in cases where it does not recognize a PICTURE clause.
No equivalent.

The preprocessor generates an error if a host variable is used that does not have a data type acceptable for use as a host variable.
: TargetPattern=<pattern>

Describes a group of tokens that can be strung together as components to describe the location and naming convention applied to the precompiled target file.
No equivalent. Output files are always generated in the same location as source files and with an extension of ‘.cbp’ except when COBOL-IT’s preprocess directive is used.
:TrimMode=[TRUE/FALSE]

Default is: [FALSE] When set to TRUE, alphanumeric (PIC X) strings that are passed to the database are first trimmed, (right space removed), so that the data in the database does not have trailing spaces.
-PICXBINDING={DEFAULT | PAD | TRIM | TRIMALL | FIXED | VARIABLE}
:TruncComments=[TRUE/FALSE]

When set to TRUE, Comments are truncated after column 72. When set to FALSE, comments are not truncated after column 72.
No equivalent.
:UTFInput=[TRUE/FALSE]

When set to TRUE, specifies that the source code contains literals encoded in UTF-8.
No equivalent.

Host Variables

CitSQL CitOESQL
CitSQL supports the non-COBOL
USAGE Clauses:

USAGE [LONG]VARCHAR
USAGE [LONG] VARRAW
USAGE VARYING
CitOESQL supports the non-COBOL USAGE
Clauses:

USAGE [LONG]VARCHAR
USAGE [LONG] VARRAW
USAGE VARYING

Supported SQL [TYPE] [IS]:
DATE, DATE-RECORD
TIME, TIME-RECORD
TIMESTAMP, TIMESTAMP-RECORD
TIMESTAMP-OFFSET, TIMESTAMPOFFSET-
RECORD
BINARY, VARBINARY, LONG-VARBINARY
CHAR, LONG-VARCHAR
CHAR-VARYING

ESQL features

CitSQL CitOESQL
N/A Passes all the NIST ANSI ESQL compliance tests.

Includes support for dynamic SQL.

Multiple documented extensions to ANSI ESQL:
- Array insert and fetch
- GET DIAGNOSTICS
- SAVEPOINT support

Directives and constants in source code based on MF $SET syntax.

Conditional compilation based on MF COBOL conditional compilation built into the precompiler.

Dependencies and Limitations

CitSQL CitOESQL
N/A Requires ODBC on Windows and Linux.

Database ODBC drivers may depend on database client libraries.

Requires 3rd party ODBC Driver Manager for Linux (UnixODBC recommended).

32 and 64 bit support on Linux and Windows.

SQL Statement Differences and Limitations

CitSQL CitOESQL
N/A Does not support CitSQL EXEC SQL CONNECT statement syntax directly, however, does provide 6 flexible ODBC alternatives.

Does not support CitSQL EXEC SQL DECLARE hostvar VARIABLE CCSID xxxxx statement.

Does not support CitSQL PIC N USAGE VARCHAR USAGE CLAUSE.