Host variables in COBOL
In COBOL programs, you can specify numeric and character host variables.
- Only some of the valid COBOL declarations are valid host variable declarations. If the declaration for a variable is not valid, any SQL statement that references the variable might result in the message UNDECLARED HOST VARIABLE.
- One or more REDEFINES entries can follow any level 77 data description entry. However, you cannot use the names in these entries in SQL statements. Entries with the name FILLER are ignored.
- Be careful of overflow. For example, suppose that you retrieve an INTEGER field value into a PICTURE S9(4) host variable and the field value is larger than 32767 or smaller than -32768. You get an overflow warning or an error, depending on whether you specify an indicator variable.
- Be careful of truncation. For example, if you retrieve an 80-character CHAR field value into a PICTURE X(70) host variable, the rightmost 10 characters of the retrieved string are truncated. Retrieving a double precision floating-point or decimal field value into a PIC S9(8) COMP host variable removes any fractional part of the value. Similarly, retrieving a field value with DECIMAL data type into a COBOL decimal variable with a lower precision might truncate the value.
Numeric host variables
You can specify the following forms of numeric host variables:
- Floating-point numbers
- Integers and small integers
- Decimal numbers
The following diagram shows the syntax for declaring floating-point or real host variables.
- 1 level-1 indicates a COBOL level between 2 and 48.
- 2 COMPUTATIONAL-1 and COMP-1 are equivalent.
- 3 COMPUTATIONAL-2 and COMP-2 are equivalent.
The following diagram shows the syntax for declaring integer. small integer, and big integer host variables.
- 1 level-1 indicates a COBOL level between 2 and 48.
- 2 The COBOL binary integer data types BINARY, COMPUTATIONAL, COMP, COMPUTATIONAL-4, and COMP-4 are equivalent.
- 3 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).
- 4 Any specification for scale is ignored.
The following diagram shows the syntax for declaring decimal host variables.
- 1 level-1 indicates a COBOL level between 2 and 48.
- 2 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).
- 3 PACKED-DECIMAL, COMPUTATIONAL-3, and COMP-3 are equivalent. The picture-string that is 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.
In COBOL, you declare the SMALLINT and INTEGER data types as a number of decimal digits. IMS uses the full size of the integers (in a way that is similar to processing with the TRUNC(BIN) compiler option) and can place larger values in the host variable than would be allowed in the specified number of digits in the COBOL declaration. If you compile with TRUNC(OPT) or TRUNC(STD), ensure that the size of numbers in your application is within the declared number of digits.
For small integers that can exceed 9999, use S9(4) COMP-5 or compile with TRUNC(BIN). For large integers that can exceed 999 999 999, use S9(10) COMP-3 to obtain the decimal data type. If you use COBOL for integers that exceed the COBOL PICTURE, specify the field as decimal to ensure that the data types match and perform well.
If you are using a COBOL compiler that does not support decimal numbers of more than 18 digits, use one of the following data types to hold values of greater than 18 digits:
- A decimal variable with a precision less than or equal to 18, if the actual data values fit. If you retrieve a decimal value into a decimal variable with a scale that is less than the source field in the database, the fractional part of the value might be truncated.
- An integer or a floating-point variable, which converts the value. If you use an integer variable, you lose the fractional part of the number. If the decimal number might exceed the maximum value for an integer or if you want to preserve a fractional value, use a floating-point variable. Floating-point numbers are approximations of real numbers. Therefore, when you assign a decimal number to a floating-point variable, the result might be different from the original number.
Character host variables
You can specify the following forms of character host variables:
- Fixed-length strings
The following diagram shows the syntax for declaring fixed-length character host variables.
- 1 level-1 indicates a COBOL level between 2 and 48.
- 2 The picture-string that is associated with these forms must be X(m) (or XX…X, with m instances of X), where m is up to COBOL's limitation.
The following diagrams show the syntax for declaring varying-length character host variables.
- 1 level-1 indicates a COBOL level between 2 and 48.
- 1 You cannot use an intervening REDEFINE at level 49.
- 2 You cannot directly reference var-1 as a host variable.
- 3 IMS 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 You cannot use an intervening REDEFINE at level 49.
- 2 You cannot directly reference var-2 as a host variable.
- 3 For fixed-length strings, the picture-string must be X(m) (or XX, with m instances of X), where mis up to COBOL's limitation.