Nonstop Database, HiRDB Version 9 UAP Development Guide
![[Contents]](FIGURE/CONTENT.GIF)
![[Index]](FIGURE/INDEX.GIF)
![[Back]](FIGURE/FRONT.GIF)
![[Next]](FIGURE/AFTER.GIF)
8.2.3 Preprocessing in Windows
(a) Environment variable setting
Before a UAP is preprocessed, the environment variable described below can be specified in the HiRDB.INI file, if necessary.
The HiRDB.INI file is installed in the %windir% directory.
- PDCLTLANG
- Specifies the character code classification to be used for preprocessing. If this environment variable is omitted, sjis is assumed. For details about the PDCLTLANG operand, see 6.6.4 Environment definition information.
Following are the three methods of activating the SQL preprocessor:
- Execution by means of overlaying icons
- Execution by means of filename specification
- Execution from the command prompt or MS-DOS prompt
- Execution by overlaying icons
In Windows Explorer, drag the file to be preprocessed onto and overlay it on the preprocessor file (PDCPP.EXE); execution then occurs automatically.
When this method is used, no options can be specified to be set during execution.
- Execution by filename specification
Click the preprocessor icon (PDCPP.EXE), and follow the procedures below:
- Select Run from the File menu.
- Specify a filename and options on the command line.
- Execution from the command prompt or MS-DOS prompt
Activate the command prompt or MS-DOS prompt. Execute the program by entering either PDCPP.EXE (in C) or PDOCC.EXE (in C++).
A command is entered in the following format:
PDCPP.EXE input-file-name [options [output-file-name|authorization-identifier]]
- Note
- In the case of C++, the underlined section must be changed to PDOCC.EXE.
- input-file-name
- Specifies the name of the C source file. .EC must be used as the file identifier.
- output-file-name
- Specifies the name of the C source file. If the output filename is omitted, .C is used as the file identifier.
- authorization-identifier
- Specifies the default authorization identifier to be used when an authorization identifier is omitted in the SQL. If the authorization identifier is omitted, the user identifier used during CONNECT is assumed.
- options
- Specifies, as necessary, the options shown in table below. Upper-case and lower-case characters are not discriminated in the options.
Table 8-8 Preprocessing options (for C in the Windows environment)
| Preprocessing option |
Description |
| /S |
Specifies that only syntax is checked and that no post source will be output; when this option is omitted, the post source is output. Note that the SQL preprocessor may not be able to detect all syntax errors in the SQL statements because it does not perform a rigorous SQL syntax check unless /Xp is also specified. |
| /O file-name |
Specifies a filename for the post source that is output; when this option is omitted, the input filename with its file identifier changed to .C is used as the output filename. |
| /A authorization-identifier |
Specifies that the default authorization identifier, which is used when no authorization identifier is specified in a static SQL statement, is to be changed.
A static SQL statement refers to the INSERT, UPDATE, DELETE, single-row SELECT, OPEN (format 1), CALL, LOCK, or PURGE TABLE statement. |
| /h64 |
Specifies that a post source for 64-bit mode is to be created. Note that this option cannot be specified if you have used a 32-bit edition preprocessor.
If an embedded variable that uses the long type is declared, an error occurs. |
| /Xe{y|n} |
Specifies whether the cursor for PREPARE statement execution is to be closed automatically.
y: Creates a post source that closes the cursor automatically.
n: Creates a post source that does not close the cursor automatically.
If this option is omitted, the preprocessor creates a post source according to the specification value in the PDPRPCRCLS client environment definition. |
| /Xv |
Specifies that VARCHAR- and BINARY-type structures are to be analyzed as normal structures when the /E2 option is specified. To declare VARCHAR- and BINARY-type embedded variables, use the SQL TYPE IS-type variable declaration. This option must be specified together with the /E2 option. Do not specify this option if the UAP uses macros for repetition columns. |
| /XA |
Specifies that an X/Open-compliant API is to be used to create the UAP. |
| /Xo |
Specifies that the SQL statements extracted from the UAP are to be output to standard output. The output method for outputting the SQL statements is described below.
- Embedded variables in SQL statements are replaced with the ? parameter.
- INTO clauses in single-row SELECT statements are deleted.
- Multiple space characters between word clauses in SQL statements are replaced with one space character.
- Any SQL statement that is split across several lines is consolidated into a single line.
- Only SQL statements that are sent to the server during execution are output. SQL statements that are not executed (such as WHENEVER statements and BEGIN DECLARE SECTION) are not output.
- A semicolon (;) is added to the end of an SQL statement.
- Declarations of embedded variables are not output.
- A dynamic SQL statement is output only if the SQL is specified with a literal. In all other cases, dynamic SQL statements are not output.
- An OPEN statement outputs a query expression only if a format 1 cursor is used.
- A post source is not generated.
|
| /E{1|2|3} ["option-character-string"] |
Specifies that preprocessor declaration statements used in the UAP are to be validated or that embedded variables are to be used without being declared in the embedded SQL declare section, or both. Note that this option is ignored in PDOCC.EXE.
/E1: Specifies that preprocessor declaration statements are to be validated.
/E2: Specifies that embedded variables are to be used without being declared in the embedded SQL declare section. This value can also specify that pointers or structure references are to be used as embedded variables.
/E3: Specifies that both /E1 and /E2 apply.
"option-character-string":
Specifies the path name of the directory from which the file to be included is to be retrieved. Specify the path name in the format of the /I option specified in the C compiler. When specifying multiple options in option-character-string, use semicolons to separate the options. You can also specify any C compiler. When the /E2 option is specified, this value ignored.
When the /E1 option is specified, the path name to the compiler must be specified in the PATH environment variable because the preprocessor calls the C compiler internally. |
| /Xp |
Specifies that a rigorous SQL syntax check is to be executed. However, do not specify this option when the SQL reserved word deletion facility is used. |
| /XU16[L|B][T"type-specifier"] |
- Specifies the UTF-16 byte order.
If a UTF16 character set name is specified in the declaration of an embedded variable, you must specify the UTF-16 byte order to be stored in embedded variables.
- /XU16L[T"type-specifier"]
- Use little endian for the UTF-16 byte order.
- /XU16B[T"type-specifier"]
- Use big endian for the UTF-16 byte order.
If neither L nor B is specified, or this option is omitted, the UTF-16 byte order of the OS used for preprocessing is assumed as the byte order.
- Specifies the type specifier used for expanding UTF-16 embedded variables.
If you have declared a variable in a data description beginning with SQL TYPE IS CHAR or SQL TYPE IS VARCHAR, this option specifies the type specifier to be added to the variable or structure member that stores UTF-16 character string data in a C declaration that is expanded into the post source.
You can only specify sizeof(type-specifier) == 2 for the type specifier, because one 2-byte UTF-16 character data item is stored in one array element of the type specified by the type specifier.
- Example of type specifier:
- This example can be used only by a compiler that is sizeof(wchar_t)==2:
- /XU16T"wchar_t"
- The following example can be used by any compiler because it is sizeof(unsigned short)==2:
- /XU16T"unsigned short"
If you omit T"type-specifier" or this option, char is used as the type specifier. In such a case, one 2-byte UTF-16 character data is stored in two char-type array elements. |
| /g{c89|c99} |
When the /E2 or /E3 option is specified, specifies the C standard that is to be complied with when the SQL preprocessor analyzes a UAP source.
- /gc89
- Comply with C89 (ISO/IEC 9899:1990, Programming languages - C).
- /gc99
- Comply with C99 (ISO/IEC 9899:1999, Programming languages - C).
If this option is omitted, /gc89 is assumed.
If the /E2 and /E3 options are both omitted, this option is ignored, if specified. |
- Note 1
- The following table shows the functions that can be used when the /E option is specified.
| Function |
Omitted |
/E1 |
/E2 |
/E3 |
| Validate the macro defined with #define. |
N |
Y |
N |
Y |
| Validate the header file that was included with #include. |
N |
Y |
N |
Y |
| Enable conditional compilation with #if, #ifdef, and other statements. |
N |
Y |
N |
Y |
| Use variables declared anywhere in the UAP as embedded variables. |
N |
N |
Y |
Y |
| Use structures as embedded variables. |
N |
N |
Y |
Y |
| Use pointers as embedded variables. |
N |
N |
Y |
Y |
- Legend:
- Y: The function can be used.
- N: The function cannot be used.
- Note 2
- When the /E option is specified, the preprocessor calls the Microsoft Visual C++ compiler (load name during calling: CL.EXE) internally.
- If you wish to use any other C compiler, specify the absolute path name of the compiler, including the load directory, at the beginning of the option-character-string value. The directory name and the load name cannot include spaces or semicolons. If a path name has been added to the PATH environment variable, the path name does not have to be the absolute path name.
- When specifying a load name, separate the load name and the options with a semicolon.
- The compiler to be used must support the /C and /E options. This is because to process pseudo-instructions such as #define and #include, the preprocessor internally specifies the /C and /E options to the C compiler and creates temporary work files. The other options that can be specified in option-character-string depend on the specifications of the compiler to be used. However, if an option that is incompatible with the /C or /E option is specified, the preprocessor produces an error. If an option that displays help information is used, the operation is not guaranteed.
- If the /E2 and /E3 options are both specified, the preprocessor analyzes syntax based on the C standard (C89 or C99) that is specified in or assumed for the /g option in order to recognize embedded variables declared at any location in the UAP. Therefore, a syntax error might result in the following cases:
- The /E2 or /E3 option is specified, but a syntax that does not comply with the selected standard is used in the UAP source file.
- The /E3 option is specified, but a syntax that does not comply with the selected standard is used in the header file included by applying the #include statement.
- To avoid syntax errors, use the syntax that complies with the selected standard in the UAP source files and header files. If a syntax error occurs because a syntax that does not comply with the selected standard is used in header files provided by the compiler product, you might be able to avoid the errors by specifying compiler options that comply with the selected standard in /E3 option-character-string.
- Note 3
- SQL statements and SQL TYPE IS-type variable declarations cannot be specified in the included header file. If the preprocessor finds an SQL statement or an SQL TYPE IS-type variable declaration in the header file, it displays an error message and continues processing but does not generate a post source. If you specify the /E1 option and also specify an embedded variable declare section in the header file, that section becomes invalid. To use variables defined in the header file as embedded variables, specify the /E3 option. However, in this case as well, SQL TYPE IS-type variable declarations cannot be specified in the include file.
- Note 4
- If a UTF16 character set name is specified in the declaration of an embedded variable, the SQL preprocessor expands the source code for specifying the character set name in the character set descriptor area in the post source. The source code depends on the specified /XU16 option: UTF-16LE is set for little endian, and UTF-16BE is set for big endian.
- If you determine the character set name for I/O variables during UAP execution by using an SQL descriptor area and character set descriptor area without using an embedded variable, the byte order specified in the /XU16 option is ignored. In such a case, if you specify UTF16 for the character set name, the byte order is set to big endian.
- Note 5
- The following data descriptions are applicable to a function for which a type specifier is specified in the /XU16 option:
- SQL TYPE IS CHAR(2n) CHARACTER SET [IS] [MASTER.]UTF16 variable-name;
- SQL TYPE IS CHAR(2n) CHARACTER SET [IS] [MASTER.]UTF16 variable-name[m];
- SQL TYPE IS CHAR(2n) CHARACTER SET [IS] [MASTER.]UTF16 *variable-name;
- SQL TYPE IS VARCHAR(2n) CHARACTER SET [IS] [MASTER.]UTF16 variable-name;
- SQL TYPE IS VARCHAR(2n) CHARACTER SET [IS] [MASTER.]UTF16 variable-name[m];
- SQL TYPE IS VARCHAR(2n) CHARACTER SET [IS] [MASTER.]UTF16 *variable-name;
- Note 6
- The handling of the reserved words added in C99 depends on the specified /g option. The following reserved words have been added in C99:
- restrict, inline, _Bool, _Complex, _Imaginary, _Pragma
- In C89, restrict and inline can be used as identifiers such as variable names, but they can no longer be used as identifiers in C99. If restrict and inline are used as identifiers in an existing UAP that is compliant with C89 and that UAP is analyzed as being compliant with C99, an error will result.
- The following table describes the handling of the reserved words added in C99:
| /g option |
Handling |
| Omitted |
Handled as identifiers.# |
| /gc99 specified |
Handled as reserved words as in C99. |
| /gc89 specified |
Handled as identifiers.# |
- #
- Names that begin with one underscore (_) followed immediately by an upper-case letter (A to Z) or by a second underscore are also reserved for libraries in C89. Therefore, if _Bool, _Complex, _Imaginary, or _Pragma is used as an identifier in a UAP, the preprocessor operation is not guaranteed.
- The table below explains the /g option specifications. The /g option has no effect other than on the handling of reserved words added in C99.
| Usage of reserved words added in C99 |
/g option specification |
| Used as reserved words |
If you specify /gc99, you can execute the SQL preprocessor. A post source cannot be compiled because Visual C++ (version up to 2008) does not support C99. If the compiler used is not Visual C++, the compilation operation is not guaranteed. |
| Used as identifiers |
Omit the /g option or specify /gc89. |
| Not used as reserved words or identifiers |
There is no need to specify the /g option. The words can be specified as comments. |
- You should note the following about specifying the /g option:
- If a C99-compliant compiler product is used, reserved words added in C99 might be used in a header file provided by the compiler. If you specify the /E3 option, such a header file might be included by the #include statement.
- Some compiler products enable you to specify the handling of reserved words individually (for example, specifying restrict as a reserved word and inline as a non-reserved word). However, with the SQL preprocessor, the handling of reserved words cannot be specified individually.
- Note 7
- If you omit the /E2 and /E3 options, reserved words added in C99 are handled as identifiers in the embedded SQL declaration section. Only the embedded SQL declaration section and SQL statements (EXEC SQL ...;) are analyzed.
- Examples of command specification in C
Example 1
The UAP source filename is SAMPLE and no post source will be output.
PDCPP SAMPLE.EC /S
Example 2
The UAP source filename is SAMPLE and the filename of the post source to be output is MAIN.
PDCPP SAMPLE.EC /O MAIN.C
- Examples of command specification in C++
Example 1
The UAP source filename is SAMPLE and no post source will be output.
PDOCC.EXE SAMPLE.ECP /S
Example 2
The UAP source filename is SAMPLE and the filename of the post source to be output is MAIN.
PDOCC.EXE SAMPLE.ECP /O MAIN.CPP
(c) SQL preprocessor return codes
The SQL preprocessor returns a return code to the OS when the processing is completed. The return code can be referenced by the OS batch command ERRORLEVEL.
The following table lists and describes the return codes.
Table 8-9 SQL preprocessor return codes (for C programs in a Windows environment)
| Return code |
Explanation |
| 0 |
Normal termination |
| 4, 8 |
Error (preprocessing was completed) |
| 12, 16 |
Error (preprocessing terminated abnormally) |
(d) Error output
When a syntax error is detected in an SQL statement, the SQL preprocessor ignores that SQL statement and continues processing. If an error is detected in an option specification, however, processing is suspended. Processing terminates abnormally when a system error, such as a memory shortage or a file I/O error, occurs and processing cannot be continued.
For a syntax error in an SQL statement, the SQL preprocessor outputs an error message to the standard error output. By redirecting the standard error output, the error message can be stored in a file. This file can be referenced for the error content, the UAP source filename, and the error location (line number in the SQL statement).
The following table shows the standard input and output for the SQL preprocessor.
Table 8-10 SQL preprocessor standard input and output (for C programs in a Windows environment)
| File |
Application |
| Standard input |
File input (cannot be used by the user) |
| Standard output |
File output (cannot be used by the user) |
| Standard error output |
Output of error messages |
(a) Environment variable setting
The following environment variables can be set in the HIRDB.INI file before a UAP is preprocessed (the HIRDB.INI file is installed in the %windir% directory):
- PDCBLFIX
- This environment variable specifies an optional file identifier other than the standard identifier of the COBOL source file.
- The specification must be a character string of 1-4 alphabetic characters beginning with a period. The file identifier specified in this environment variable can be used only for the input file.
- PDCBLLIB
- This environment variable specifies directories from which library texts to be included in the source file are to be retrieved by the COPY statement. When specifying multiple directories, separate the directories with a colon. When this environment variable is omitted, only the current directory is retrieved.
- PDCLTLANG
- This environment variable should be specified if a specific type of character codes is to be used for preprocessing. The default is sjis. For details about the PDCLTLANG operand, see 6.6.4 Environment definition information.
- Example
[HiRDB] 1
PDCBLFIX=.AAA 2
PDCBLLIB=E:\USER\COPY 3
- Specifies [HiRDB].
- Specifies .AAA as a COBOL language source file identifier.
- Specifies a directory (E:\USER\COPY in this example) from which library text to be included by the COPY statement is to be retrieved.
Following are the three methods of activating the SQL preprocessor:
- Execution by means of overlaying icons
- Execution by means of filename specification
- Execution from the command prompt or MS-DOS prompt
- Execution by overlaying icons
In Windows Explorer, drag the file to be preprocessed onto and overlay it on the preprocessor file (PDCBL.EXE). Execution then occurs automatically.
When this method is used, no options can be specified to be set during execution.
- Execution by filename specification
Click the preprocessor icon (PDCBL.EXE) and use the following procedure:
- Select Run from the File menu.
- Specify a filename and options on the command line.
- Execution from the command prompt or MS-DOS prompt
Activate the command prompt or MS-DOS prompt. Execute the program by entering either PDCBL.EXE (in COBOL) or PDOCB.EXE (in OOCOBOL).
A command is entered in the following format:
PDCBL.EXE input-file-name [options [output-file-name|authorization-identifier]]
- Note
- In the case of OOCOBOL, the underlined section must be changed to PDOCB.EXE.
- input-file-name
- Specifies the name of the COBOL source file. .ECB, .COB, or .CBL must be used as the file identifier. If any other file identifier was registered during environment setting, that identifier can also be used.
- output-file-name
- Specifies the name of the COBOL source file. If the output filename is omitted, .CBL is used as the file identifier.
- authorization-identifier
- Specifies the default authorization identifier to be used when an authorization identifier is omitted in the SQL. If the authorization identifier is omitted, the user identifier used during CONNECT is assumed.
- options
- Specifies, as necessary, the options shown in the table below. Upper-case and lower-case characters are not discriminated in the options.
Table 8-11 Preprocessing options (for COBOL in the Windows environment)
| Preprocessing option |
Description |
| /S |
Specifies that only syntax is checked and that no post source will be output; when this option is omitted, the post source is output.
Note that the SQL preprocessor may not be able to detect all syntax errors in the SQL statements because it does not perform a rigorous SQL syntax check unless /Xp is also specified. |
| /O file-name |
Specifies that the filename for the output post source is to be changed.
When this option is omitted, the input filename with its file identifier changed to .CBL (for COBOL language) or .OCB (for OOCOBOL language) and is used as the output filename.
If the input file identifier is .CBL (for COBOL language) or .OCB (for OOCOBOL language), this option must be specified to change the post source filename to an identifier other than .CBL (for COBOL language) or .OCB (for OOCOBOL language). |
| /XC |
Specifies that the double quotation mark is used as the quotation mark in the character string to be created by the SQL preprocessor; the default quotation mark is the apostrophe. |
| /A authorization-identifier |
Specifies that the default authorization identifier, which is used when no authorization identifier is specified in a static SQL statement, is to be changed.
A static SQL statement refers to the INSERT, UPDATE, DELETE, single-row SELECT, OPEN (format 1), CALL, LOCK, or PURGE TABLE statement. |
| /h64 |
Specifies that a post source for 64-bit mode is to be created. Note that this option cannot be specified if you have used a 32-bit edition preprocessor. |
| /XD |
Specifies that a DLL is to be created.
The prerequisite compiler for creating a DLL is COBOL85 Version 4.0 04-02 or a later version. Do not create an application that contains both UAPs that were preprocessed by specifying the /XD option and UAPs that were preprocessed without specifying the /XD option. Otherwise, an error (KCCBO204R-S) occurs in the COBOL runtime library during application execution. |
| /Xe{y|n} |
Specifies whether the cursor for PREPARE statement execution is to be closed automatically.
y: Creates a post source that closes the cursor automatically.
n: Creates a post source that does not close the cursor automatically.
If this option is omitted, the preprocessor creates a post source according to the specification value in the PDPRPCRCLS client environment definition. |
| /XAD |
Specifies that a UAP that used an X/Open-compliant API is to be created as a DLL. |
| /XA |
Specifies that the UAP is to be created by using an X/Open-compliant API. |
| /Xo |
Specifies that the SQL statements extracted from the UAP are to be output to standard output. The output method for outputting the SQL statements is described below.
- Embedded variables in SQL statements are replaced with the ? parameter.
- INTO clauses in single-row SELECT statements are deleted.
- Multiple space characters between word clauses in SQL statements are replaced with one space character.
- Any SQL statement that is split across several lines is consolidated into a single line.
- Only SQL statements that are sent to the server during execution are output. SQL statements that are not executed (such as WHENEVER statements and BEGIN DECLARE SECTION) are not output.
- A semicolon (;) is added to the end of an SQL statement.
- Declarations of embedded variables are not output.
- A dynamic SQL statement is output only if the SQL is specified with a literal. In all other cases, dynamic SQL statements are not output.
- An OPEN statement outputs a query expression only if a format 1 cursor is used.
- A post source is not generated.
|
| /E2 |
Specifies that embedded variables are to be used without being declared in the embedded SQL declare section. |
| /Xp |
Specifies that a rigorous SQL syntax check is to be executed. However, do not specify this option when the SQL reserved word deletion facility is used. |
| /XU16[L|B] |
You specify this option when you use the Unicode function of COBOL2002. For details about the execution of UAPs that use the Unicode function of COBOL2002, see 8.4.3 UAP execution using the Unicode functionality of COBOL2002.
This option specifies the byte order of character codes (UTF-16) in Japanese data items.
- /XU16L
- Uses little endian for the UTF-16 byte order.
- /XU16B
- Uses big endian for the UTF-16 byte order.
- /XU16
- Uses the byte order of the OS used for preprocessing for the UTF-16 byte order:
- In Windows and Linux, little endian is used.
- In AIX, big endian is used.
- If this option is specified for any other OS, the preprocessor operations are not guaranteed.
Do not specify this option if you do not use the Unicode function of COBOL2002. If this option is specified in such a case, it will not be possible to use Japanese data items in the declaration of embedded variables. |
- Examples of command specification in COBOL
Example 1
The UAP source filename is SAMPLE and no post source will be output.
PDCBL SAMPLE.ECB /S
Example 2
The UAP source filename is SAMPLE and the filename of the post source to be output is MAIN.
PDCBL SAMPLE.ECB /O MAIN.CBL
- Examples of command specification in OOCOBOL
Example 1
The UAP source filename is SAMPLE and no post source will be output.
PDOCB.EXE SAMPLE.EOC /S
Example 2
The UAP source filename is SAMPLE and the filename of the post source to be output is MAIN.
PDOCB.EXE SAMPLE.EOC /O MAIN.OCB
(c) SQL preprocessor return codes
The SQL preprocessor returns a return code to the OS when the processing is completed. The return code can be referenced by the OS batch command ERRORLEVEL.
The following table lists and describes the return codes.
Table 8-12 SQL preprocessor return codes (for COBOL programs in a Windows environment)
| Return code |
Explanation |
| 0 |
Normal termination |
| 4, 8 |
Error (preprocessing was completed) |
| 12, 16 |
Error (preprocessing terminated abnormally) |
(d) Error output
When a syntax error is detected in an SQL statement, the SQL preprocessor ignores that SQL statement and continues processing. If an error is detected in an option specification, however, processing is suspended. Processing terminates abnormally when a system error, such as a memory shortage or a file I/O error, occurs and processing cannot be continued.
For a syntax error in an SQL statement, the SQL preprocessor outputs an error message to the standard error output. By redirecting the standard error output, the error message can be stored in a file. This file can be referenced for the error content, the UAP source filename, and the error location (line number in the SQL statement).
The following table shows the standard input and output of the SQL preprocessor.
Table 8-13 SQL preprocessor standard input and output (for COBOL programs in a Windows environment)
| File |
Application |
| Standard input |
File input (cannot be used by the user) |
| Standard output |
File output (cannot be used by the user) |
| Standard error output |
Output of error messages |
All Rights Reserved. Copyright (C) 2011, Hitachi, Ltd.