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.
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.
(1) >>---level-1--------variable-name--+---------------+------------> | .-IS-. | '-USAGE--+----+-' (4) >--+-COMPUTATIONAL-1-+--OCCURS--dimension------+-------+--------> | (2) | '-TIMES-' +-COMP-1----------+ +-COMPUTATIONAL-2-+ | (3) | '-COMP-2----------' >--+---------------------------------+-- . -------------------->< | .-IS-. | '-VALUE--+----+--numeric-constant-'
Notes:
- level-1 indicates a COBOL level between 2 and 48.
- COMPUTATIONAL-1 and COMP-1 are equivalent.
- COMPUTATIONAL-2 and COMP-2 are equivalent.
- dimension must be an integer constant between 1 and 32767.
The following diagram shows the syntax for declaring integer and small integer host variable arrays.
(1) .-IS-. >>---level-1--------variable-name--+-PICTURE-+--+----+----------> '-PIC-----' (2) >--+-S9(4)------+--+---------------+--+-BINARY----------+-------> +-S9999------+ | .-IS-. | +-COMPUTATIONAL-4-+ +-S9(9)------+ '-USAGE--+----+-' +-COMP-4----------+ '-S999999999-' +-COMPUTATIONAL-5-+ | (3) | +-COMP-5----------+ +-COMPUTATIONAL---+ '-COMP------------' (4) >--OCCURS--dimension------+-------+-----------------------------> '-TIMES-' (5) >--+---------------------------------+-- . -------------------->< | .-IS-. | '-VALUE--+----+--numeric-constant-'
Notes:
- level-1 indicates a COBOL level between 2 and 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 between 1 and 32767.
- Any specification for scale is ignored.
The following diagram shows the syntax for declaring decimal host variable arrays.
(1) >>---level-1--------variable-name--+-PICTURE-+------------------> '-PIC-----' .-IS-. >--+----+--picture-string--+---------------+--------------------> | .-IS-. | '-USAGE--+----+-' (2) >--+-+-PACKED-DECIMAL--+---------------------------------------------+--> | +-COMPUTATIONAL-3-+ | | '-COMP-3----------' | | .-IS-. (3) .-CHARACTER-. | '-+-DISPLAY--+--SIGN--+----+--LEADING SEPARATE------+-----------+-' '-NATIONAL-' (4) >--OCCURS--dimension------+-------+--+---------------------------------+--> '-TIMES-' | .-IS-. | '-VALUE--+----+--numeric-constant-' >-- . ---------------------------------------------------------><
Notes:
- level-1 indicates a COBOL level between 2 and 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 between 1 and 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.
(1) >>---level-1--------variable-name--+-PICTURE-+------------------> '-PIC-----' .-IS-. (2) >--+----+--picture-string------+----------------------------+---> '-+---------------+--DISPLAY-' | .-IS-. | '-USAGE--+----+-' (3) >--OCCURS--dimension------+-------+-----------------------------> '-TIMES-' >--+-----------------------------------+-- . ------------------>< | .-IS-. | '-VALUE--+----+--character-constant-'
Notes:
- level-1 indicates a COBOL level between 2 and 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 between 1 and 32767.
The following diagrams show the syntax for declaring varying-length character string arrays.
(1) (2) >>-level-1------variable-name--OCCURS--dimension------+-------+-- . ->< '-TIMES-'
Notes:
- level-1 indicates a COBOL level between 2 and 48.
- dimension must be an integer constant between 1 and 32767.
(1) .-IS-. (2) >>-49--var-1------+-PICTURE-+--+----+--+-S9(4)-----+------------> '-PIC-----' '-S9999-----' >--+---------------+--+-BINARY----------+--+-SYNCHRONIZED-+-----> | .-IS-. | +-COMPUTATIONAL-4-+ '-SYNC---------' '-USAGE--+----+-' +-COMP-4----------+ +-COMPUTATIONAL-5-+ +-COMP-5----------+ +-COMPUTATIONAL---+ '-COMP------------' >--+---------------------------------+-- . -------------------->< | .-IS-. | '-VALUE--+----+--numeric-constant-'
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.
(1) .-IS-. (2) >>-49--var-2------+-PICTURE-+--+----+--picture-string-----------> '-PIC-----' >--+----------------------------+-------------------------------> '-+---------------+--DISPLAY-' | .-IS-. | '-USAGE--+----+-' (3) >--+-----------------------------------+-- . ------------------>< | .-IS-. | '-VALUE--+----+--character-constant-'
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.
Example: 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.
(1) >>-level-1------variable-name--+-PICTURE-+----------------------> '-PIC-----' .-IS-. (2) >--+----+--picture-string---------------------------------------> .-IS-. >--USAGE--+----+--+-DISPLAY-1--------+--------------------------> | (3) (4) | '-NATIONAL---------' (5) >--OCCURS--dimension------+-------+-----------------------------> '-TIMES-' >--+---------------------------------+-- . -------------------->< | .-IS-. | '-VALUE--+----+--graphic-constant-'
Notes:
- level-1 indicates a COBOL level between 2 and 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 between 1 and 32767.
The following diagrams show the syntax for declaring varying-length graphic string arrays.
(1) (2) >>---level-1--------variable-name--OCCURS--dimension------+-------+-- . ->< '-TIMES-'
Notes:
- level-1 indicates a COBOL level between 2 and 48.
- dimension must be an integer constant between 1 and 32767.
(1) .-IS-. (2) >>-49--var-1------+-PICTURE-+--+----+--+-S9(4)-----+------------> '-PIC-----' '-S9999-----' >--+---------------+--+-BINARY----------+--+-SYNCHRONIZED-+-----> | .-IS-. | +-COMPUTATIONAL-4-+ '-SYNC---------' '-USAGE--+----+-' +-COMP-4----------+ +-COMPUTATIONAL-5-+ +-COMP-5----------+ +-COMPUTATIONAL---+ '-COMP------------' >--+---------------------------------+-- . -------------------->< | .-IS-. | '-VALUE--+----+--numeric-constant-'
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.
(1) >>-49--var-2------+-PICTURE-+-----------------------------------> '-PIC-----' .-IS-. (2) .-IS-. >--+----+--picture-string------USAGE--+----+--+-DISPLAY-1--------+--> | (3) (4) | '-NATIONAL---------' >--+---------------------------------+-- . -------------------->< | .-IS-. | '-VALUE--+----+--graphic-constant-'
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.
(1) >>-level-1------variable-name--SQL TYPE IS----------------------> (2) >------+-BINARY---------+----(--length------)-------------------> +-BINARY VARYING-+ '-VARBINARY------' (3) >--OCCURS--dimension------+-------+--.------------------------->< '-TIMES-'
Notes:
- level-1 indicates a COBOL level between 2 and 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 between 1 and 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.
(1) >>-level-1------variable-name--+---------------+--SQL TYPE IS---> | .-IS-. | '-USAGE--+----+-' >--+-+-+-BINARY LARGE OBJECT-+----+--(--length--+---+--)-+------> | | '-BLOB----------------' | +-K-+ | | +-+-CHARACTER LARGE OBJECT-+-+ +-M-+ | | | +-CHAR LARGE OBJECT------+ | '-G-' | | | '-CLOB-------------------' | | | '-DBCLOB---------------------' | +-+-BLOB-LOCATOR---+----------------------------------+ | +-CLOB-LOCATOR---+ | | '-DBCLOB-LOCATOR-' | '-+-BLOB-FILE---+-------------------------------------' +-CLOB-FILE---+ '-DBCLOB-FILE-' (2) >--OCCURS--dimension------+-------+--.------------------------->< '-TIMES-'
Notes:
- level-1 indicates a COBOL level between 2 and 48.
- dimension must be an integer constant between 1 and 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.
(1) >>-level-1------variable-name--+---------------+----------------> | .-IS-. | '-USAGE--+----+-' >--SQL TYPE IS XML AS-------------------------------------------> >--+-+-+-BINARY LARGE OBJECT-+----+--(--length--+---+--)-+------> | | '-BLOB----------------' | +-K-+ | | +-+-CHARACTER LARGE OBJECT-+-+ +-M-+ | | | +-CHAR LARGE OBJECT------+ | '-G-' | | | '-CLOB-------------------' | | | '-DBCLOB---------------------' | '-+-BLOB-FILE---+-------------------------------------' +-CLOB-FILE---+ '-DBCLOB-FILE-' (2) >--OCCURS--dimension------+-------+--.------------------------->< '-TIMES-'
Notes:
- level-1 indicates a COBOL level between 2 and 48.
- dimension must be an integer constant between 1 and 32767.
ROWID variable arrays
The following diagram shows the syntax for declaring ROWID variable arrays.
(1) >>-level-1------variable-name--+---------------+----------------> | .-IS-. | '-USAGE--+----+-' (2) >--SQL TYPE IS--ROWID--OCCURS--dimension------+-------+--.----->< '-TIMES-'
Notes:
- level-1 indicates a COBOL level between 2 and 48.
- dimension must be an integer constant between 1 and 32767.