Host-variable arrays in COBOL

In COBOL programs, you can specify numeric, character, graphic, LOB, XML, and ROWID host-variable arrays. You can also specify LOB locators and LOB and XML file reference variables.

Host-variable arrays can be referenced only as a simple reference in the following contexts. In syntax diagrams, host-variable-array designates a reference to a host-variable array.

In a FETCH statement for a multiple-row fetch. See FETCH statement.
In the FOR n ROWS form of the INSERT statement with a host-variable array for the source data. See INSERT statement.
In a MERGE statement with multiple rows of source data. See MERGE statement.
In an EXECUTE statement to provide a value for a parameter marker in a dynamic FOR n ROWS form of the INSERT statement or a MERGE statement. See EXECUTE statement.

Start of change If an application references a host-variable array in other contexts that are not supported, Db2 returns the SQLCODE -312 error. End of change

Restriction: Only some of the valid COBOL declarations are valid host-variable array declarations. If the declaration for a variable array is not valid, any SQL statement that references the variable array might result in the message UNDECLARED HOST VARIABLE ARRAY.

Numeric host-variable arrays

You can specify the following forms of numeric host-variable arrays:

Floating-point numbers
Integers and small integers
Decimal numbers

The following diagram shows the syntax for declaring floating-point host-variable arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² COMPUTATIONAL-1 and COMP-1 are equivalent.
³ COMPUTATIONAL-2 and COMP-2 are equivalent.
⁴ dimension must be an integer constant in the range 1–32767.

The following diagram shows the syntax for declaring integer and small integer host-variable arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² The COBOL binary integer data types BINARY, COMPUTATIONAL, COMP, COMPUTATIONAL-4, and COMP-4 are equivalent.
³ COMPUTATIONAL-5 (and COMP-5) are equivalent to the other COBOL binary integer data types if you compile the other data types with TRUNC(BIN).
⁴ dimension must be an integer constant in the range 1–32767.
⁵ Any specification for scale is ignored.

The following diagram shows the syntax for declaring decimal host-variable arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² PACKED-DECIMAL, COMPUTATIONAL-3, and COMP-3 are equivalent. The picture-string that is associated with these types must have the form S9(i)V9(d) (or S9...9V9...9, with i and d instances of 9) or S9(i)V.
³ The picture-string that is associated with SIGN LEADING SEPARATE must have the form S9(i)V9(d) (or S9...9V9...9, with i and d instances of 9 or S9...9V with i instances of 9).
⁴ dimension must be an integer constant in the range 1–32767.

Character host-variable arrays

You can specify the following forms of character host-variable arrays:

Fixed-length character strings
Varying-length character strings
CLOBs

The following diagrams show the syntax for forms other than CLOBs.

The following diagram shows the syntax for declaring fixed-length character string arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² The picture-string must be in the form X(m) (or XX…X, with m instances of X), where 1 <= m <= 32767 for fixed-length strings. However, the maximum length of the CHAR data type (fixed-length character string) in Db2 is 255 bytes.
³ dimension must be an integer constant in the range 1–32767.

The following diagrams show the syntax for declaring varying-length character string arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² dimension must be an integer constant in the range 1–32767.

Notes:

¹ You cannot directly reference var-1 as a host-variable array.
² Db2 uses the full length of the S9(4) BINARY variable even though COBOL with TRUNC(STD) recognizes values up to only 9999. This behavior can cause data truncation errors when COBOL statements execute and might effectively limit the maximum length of variable-length character strings to 9999. Consider using the TRUNC(BIN) compiler option or USAGE COMP-5 to avoid data truncation.

Notes:

¹ You cannot directly reference var-2 as a host-variable array.
² The picture-string must be in the form X(m) (or XX…X, with m instances of X), where 1 <= m <= 32767 for fixed-length strings; for other strings, m cannot be greater than the maximum size of a varying-length character string.
³ You cannot use an intervening REDEFINE at level 49.

The following example shows declarations of a fixed-length character array and a varying-length character array.

01  OUTPUT-VARS.
    05  NAME OCCURS 10 TIMES.
        49 NAME-LEN   PIC S9(4) COMP-4 SYNC.
        49 NAME-DATA  PIC X(40).
    05  SERIAL-NUMBER PIC S9(9) COMP-4 OCCURS 10 TIMES.

Graphic character host-variable arrays

You can specify the following forms of graphic host-variable arrays:

Fixed-length strings
Varying-length strings
DBCLOBs

The following diagrams show the syntax for forms other than DBCLOBs.

The following diagram shows the syntax for declaring fixed-length graphic string arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² For fixed-length strings, the format for picture-string is G(m) or N(m) (or, m instances of GG...G or NN...N), where 1 <= m <= 127; for other strings, m cannot be greater than the maximum size of a varying-length graphic string.
³ Use USAGE NATIONAL only for Unicode UTF-16 data. In the picture-string for USAGE NATIONAL, you must use N in place of G.
⁴ You can use USAGE NATIONAL only if you are using the Db2 coprocessor.
⁵ dimension must be an integer constant in the range 1–32767.

The following diagrams show the syntax for declaring varying-length graphic string arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² dimension must be an integer constant in the range 1–32767.

Notes:

¹ You cannot directly reference var-1 as a host-variable array.
² Db2 uses the full length of the S9(4) BINARY variable even though COBOL with TRUNC(STD) recognizes values up to only 9999. This behavior can cause data truncation errors when COBOL statements execute and might effectively limit the maximum length of variable-length character strings to 9999. Consider using the TRUNC(BIN) compiler option or USAGE COMP-5 to avoid data truncation.

Notes:

¹ You cannot directly reference var-2 as a host-variable array.
² For fixed-length strings, the format for picture-string is G(m) or N(m) (or, m instances of GG...G or NN...N), where 1 <= m <= 127; for other strings, m cannot be greater than the maximum size of a varying-length graphic string.
³ Use USAGE NATIONAL only for Unicode UTF-16 data. In the picture-string for USAGE NATIONAL, you must use N in place of G.
⁴ You can use USAGE NATIONAL only if you are using the Db2 coprocessor.

Binary host-variable arrays

The following diagram shows the syntax for declaring binary host-variable arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² For BINARY host variables, the length must be in the range 1 to 255. For VARBINARY host variables, the length must be in the range 1 to 32704.
³ dimension must be an integer constant in the range 1–32767.

LOB, locator, and file reference variable arrays

The following diagram shows the syntax for declaring BLOB, CLOB, and DBCLOB host variable, locator, and file reference arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² dimension must be an integer constant in the range 1–32767.

XML host and file reference variable arrays

The following diagram shows the syntax for declaring BLOB, CLOB, and DBCLOB host variable and file reference arrays for XML data types.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² dimension must be an integer constant in the range 1–32767.

ROWID variable arrays

The following diagram shows the syntax for declaring ROWID variable arrays.

Notes:

¹ level-1 indicates a COBOL level in the range 2–48.
² dimension must be an integer constant in the range 1–32767.