The RDML preprocessor can operate on an OpenVMS system that has
Oracle Rdb installed.
To invoke the RDML preprocessor, you must first define a symbol.
For example:
$ RDML :== $RDML
$ RDML/PASCAL SALARY_PLAN.RPA
You must preprocess any programs that contain RDML statements
before processing them with the C or Pascal compiler.
1 – Language Selection
The RDML preprocessor will preprocess C and Pascal files that
contain RDML statements. There are two methods that allow you to
specify the language type of the source file:
1. Use a language qualifier when invoking the RDML preprocessor
2. If you do not specify a language qualifier, the RDML
preprocessor will attempt to determine what language the
source file contains by looking at the file extension supplied
in the command line. If the file extension is ".RC", RDML will
assume the file is a C file. If the file extension is ".RPA",
the RDML preprocessor will assume the file is a Pascal file.
An error message will be produced if the RDML preprocessor can
not determine what language is to be associated with a specified
input file.
2 /LISTING
Specifies a file for the error listing file. The default file
types are ".LC" for VAX C and DEC C, and ".LPA" for VAX Pascal
and DEC Pascal. If /LISTING is not specified, no listing file
will be created.
Format:
/LISTING[=file-spec]
/NOLISTING (Default)
Example:
$ RDML/LISTING EMPUPDATE.REP
3 /OUTPUT
Specifies a file for the host language output. The default file
types are ".C" for VAX C and DEC C and ".PAS" for VAX Pascal,
and DEC Pascal. The RDML preprocessor will create this file only
following a successful precompilation.
Format:
/OUTPUT[=file-spec] (Default)
/NOOUTPUT
Example:
$ RDML/OUTPUT=EMPUPDATE.PAS EMPUP.REP
4 /C
Specifies that the input file is a VAX C or DEC C source file.
If the /C qualifier is used on the command line, the RDML
preprocessor will assume a file extension of ".RC" unless you
specify otherwise in the file specification.
Format:
/C
Example:
$ RDML/C EMPUP
4.1 – More
The following restrictions affect the use of C host variables:
o Host variables in C of the form *host_variable that appear directly
after a host variable in an RSE are not detected correctly. For
instance, *year_ptr is interpreted incorrectly as part of the host
variable emp_id in the following example:
FOR D IN DEGREES WITH D.EMPLOYEE_ID = emp_id
*year_ptr = D.YEAR_GIVEN;
END_FOR;
The workaround for this restriction is to use braces around the host
language statements, or parentheses around the WITH clause. For
example, either of the following RSEs will preprocess correctly:
FOR D IN DEGREES WITH D.EMPLOYEE_ID = emp_id
{
*year_ptr = D.YEAR_GIVEN;
}
END_FOR;
FOR D IN DEGREES WITH (D.EMPLOYEE_ID = emp_id)
*year_ptr = D.YEAR_GIVEN;
END_FOR;
o Although host variables with parentheses are permitted in non-RDML
statements, they cannot be used as host variables in RDML statements.
For example, the following syntax is not permitted:
FOR E IN EMPLOYEES
WITH E.LAST_NAME = (name)[offset].element
.
.
.
END_FOR;
However, the following is permitted:
FOR E IN EMPLOYEES
WITH E.LAST_NAME = name[offset].element
.
.
.
END_FOR;
The C string continuation character (a backslash, \) in string
constants followed immediately by a new line is not recognized by
RDML. Do not use this method of continuation with this version of
RDML. RDML generates an error if it finds a string constant that does
not begin and end on the same line within quotation marks.
For example, the following C lines cause a syntax error:
printf ("abcdefg\
hijklmnopqrstuvwxyz");
5 /PASCAL
Specifies that the input file is a DEC Pascal or VAX Pascal
source file. If the /PASCAL qualifier is used on the command
line, the RDML preprocessor will assume a file extension of
".RPA" unless you specify otherwise in the file specification.
Format:
/PASCAL
Example:
$ RDML/PASCAL SALARY_PLAN
On Oracle Rdb for OpenVMS Alpha, Pascal users will need to compile
/ALIGN=VAX because RDML/PASCAL generates code that is byte aligned.
This is a permanent restriction.
5.1 – More
o RDML/Pascal does not generate the correct length for a character
string value expression in the form:
FOR E IN EMPLOYEES WITH E.LAST_NAME = ('T' | host_variable)
... some statements ...
END_FOR;
This statement generates an error from VAX Pascal, such as:
00470 0 0 RDB$PORT_FIELD_0 : VARYING[0] OF CHAR;
1
%PASCAL-E-MAXLENRNG, (1) Max-length must be in range 1..65535
%PASCAL-E-ENDDIAGS, Pascal completed with 1 diagnostic
To avoid this problem, construct the value needed before issuing the
query, using a method such as the following:
host_variable1 := 'T' + host_variable2;
FOR E IN EMPLOYEES WITH E.LAST_NAME = host_variable1
... some statements ...
END_FOR;
This method is recommended for all RDML statements when possible
because it generally improves the performance of the query.
o RDML/Pascal does not accept all possible valid Pascal host
language variables, and it issues the following error if one it
does not accept is encountered:
%RDML-W-HOST_VARIABLE, error detected in host variable syntax
The set of possible values is limited to the syntax described in the
RDML Reference Manual, with the restriction that the expression
allowed in an array index must be a simple name or expression.
The following illustrates an unacceptable statement:
FOR E IN EMPLOYEES WITH E.EMPLOYEE_ID = emparray[empstruct.index]
... some statements...
END_FOR;
In the preceding example, empstruct.index is a reference to a
structure member. To avoid this problem, you would assign
empstruct.index to an intermediate variable and use that variable
in the FOR statement WITH clause.
6 /LINKAGE
This qualifier allows you to determine whether RDML will
communicate between separate modules with program sections or
global symbols by specifying either program section or global
symbol linkage methods.
Format:
/LINKAGE=PROGRAM_SECTIONS (Default)
/LINKAGE=GLOBAL_SYMBOLS
6.1 – PROGRAM_SECTIONS
When you use this qualifier, RDML communicates between separate
modules with program sections. Using this qualifier will allow
you to link RDML modules with SQLPRE and RDBPRE modules.
6.2 – GLOBAL_SYMBOLS
When you use this qualifier, RDML communicates between separate
modules with global symbols. Rdb recommends that you only
use this qualifier if you have problems linking with program
sections.
7 /DEFAULT_TRANSACTIONS
The /[NO]DEFAULT_TRANSACTIONS qualifier controls whether or not
the RDML preprocessor will generate code to support automatic
database attachment and automatic transactions by default.
Format:
/DEFAULT_TRANSACTIONS (Default)
/NODEFAULT_TRANSACTIONS (Recommended)
When you use the /DEFAULT_TRANSACTIONS qualifier, RDML allows you
to issue a query, without explicitly issuing a READY statement or
START_TRANSACTION statement first. If you do not issue these
statements explicitly, RDML will attach to the database and
start a READ_ONLY transaction for you when it encounters the
first DML statement. Furthermore, RDML allows you to detach
from a database without first completing (committing or rolling
back) any transaction that is attached to the database you are
finishing. RDML will commit any outstanding transaction for you.
The /DEFAULT_TRANSCTIONS qualifier causes the RDML preprocessor
to generate additional (often unnecessary) code that may incur
a significant amount of overhead because RDML must check the
state of the database and transactions as each DML statement is
processed.
The /NODEFAULT_TRANSACTIONS qualifier eliminates this overhead
by requiring you to explicitly READY a database and begin and end
transactions. When you use the /NODEFAULT_TRANSACTIONS qualifier
RDML does not check the state of the database and transactions as
each RDML statement is processed. In fact, if you do not close a
transaction prior to issuing a FINISH statement for the database
with which the transaction is associated, RDML will issue the
error message: %RDB-F-OPEN_TRANS.
Rdb recommends that you always use the
/NODEFAULT_TRANSACTIONS qualifier to reduce overhead, maximize
performance and enforce good programming practices. However,
the default for this qualifier is /DEFAULT_TRANSACTIONS, as this
causes the behavior that RDML has exhibited prior to Oracle Rdb
V3.0.
8 /INITIALIZE_HANDLES
The /[NO]INITIALIZE_HANDLES qualifier lets you control whether
RDML will initialize RDML-supplied database, transaction, and
request handles. Use of the /NOINITIALIZE_HANDLES qualifier
allows you to link a main image against a shareable image and
share handles between the two.
Format:
/INITIALIZE_HANDLES (Default)
/NOINITIALIZE_HANDLES
These qualifiers have no effect on whether or when handles are
cleared in the generated code; they only control initialization
of handles in declarations. Furthermore, they only affect
database, transaction and request handles that RDML declares.
User-specified transaction and request handles will not be
initialized when you use the /INITIALIZE_HANDLES qualifier.
RDML will initialize database handles when their scope is GLOBAL
or LOCAL. EXTERNAL scope database handles are never initialized.
9 /DISTRIBUTED_TRANSACTION
For application programs that were written under Oracle Rdb V3.1 or
earlier, use the two-phase commit protocol simply by recompiling
your programs. You must use the /DISTRIBUTED_TRANSACTION
qualifier in the precompiler command line. When you do this,
Oracle Rdb invokes the DECdtm system service calls for your
application. For example, to recompile the C program SAMPLE.RC
with the RDML preprocessor, use the following command:
$ RDML :== $RDML/C
$ RDML
SOURCE FILE> SAMPLE /DISTRIBUTED_TRANSACTION
10 /QUADWORD
The /QUADWORD qualifier allows RDML to translate the quadword
data type into a double or an unformatted buffer (RDML$QUAD_
TYPE).
Format:
/QUADWORD = DOUBLE (Default)
/QUADWORD = UNFORMATTED
The default is DOUBLE, which is the same as in previous versions.
11 /NEGSCALED_NUMERIC
The /NEGSCALED_NUMERIC qualifier enables RDML to convert the
negative scaled numeric to floating (REAL or DOUBLE), depending
upon the scale and data type, or to the original data type
ignoring negative scale.
Format:
/NEGSCALED_NUMERIC = FLOATING (Default)
/NEGSCALED_NUMERIC = UNSCALED
The default is FLOATING, which is the same as in previous
versions.
12 /DATE_TYPE
The /DATE_TYPE qualifier determines whether RDML generates the
DATE data type as an empty record or not as an empty record,
which is a pair of LONGWORD. This qualifier is used only when
preprocessing a Pascal program.
Format:
/DATE_TYPE = EMPTY_RECORDS (Default)
/DATE_TYPE = NOEMPTY_RECORDS
The default is EMPTY_RECORDS.