SQLCODE -311: Input host variable length not valid

What it means

In COBOL a VARCHAR host variable is a group item with two parts. The first is a halfword length field, PIC S9(4) COMP at level 49. The second is the text. Db2 doesn't look at the text to work out how long the string is. It trusts the length field.

When the program passes the variable as input, in a WHERE clause, a SET or VALUES list, or as the statement text on a PREPARE, Db2 checks that length against the declared size of the text part. If the length is below zero or larger than that size, Db2 rejects the statement with -311 and runs nothing. The message gives the position number of the host variable, and SQLERRMC carries the same number.

The same check covers the length in an SQLDA entry for dynamic SQL.

Common causes

• The length field was never set. If the whole group was filled with spaces, the length reads as X'4040', which is 16448, larger than nearly any declared size.
• The program moved a value to the group item instead of the text field, so the first two characters of the data landed in the length field.
• The length was computed wrongly, for example from the size of a larger work field, or by arithmetic that went negative.
• A dynamic statement is longer than 32,767 bytes. A VARCHAR can't describe it. Db2 9 and later accept much longer statements, but the PREPARE host variable has to be a CLOB.
• In dynamic SQL with an SQLDA, SQLLEN was set to the wrong value for a string entry.
• A vendor tool or utility built its own host variables wrongly. IBM has fixed several of these through APARs, so check for maintenance if the failing SQL isn't yours.

How to find the problem

1. Take the position number from the message and count the host variables in the statement from left to right. Count only the ones Db2 receives as input, in WHERE, SET, VALUES and USING.
2. Display the length field just before the statement runs, in hex. X'4040' means spaces. A value of X'8000' or higher is negative.
3. Compare the length with the PIC clause of the text field under the same group. The length must be between 0 and that size.
4. In a dump, the length is the two bytes just in front of the text.
5. For a PREPARE, check the real length of the statement string against 32,767 and against the declared size of the variable.

How to fix it

• Set the length every time you set the text. A common pattern is MOVE FUNCTION LENGTH(FUNCTION TRIM(WS-IN-NAME TRAILING)) TO WS-NAME-LEN, followed by a move to the text field. Check what your compiler's TRIM returns for an all-blank field, and handle that case on its own.
• Start VARCHAR groups with INITIALIZE. It sets the length to zero and the text to spaces.
• Never MOVE to the 01 or 10 level of a VARCHAR group. Move to the 49-level fields only.
• Use a CLOB host variable for statements longer than 32 KB.
• Let DCLGEN build the VARCHAR layouts so the length field always has the right type.

What it looks like

DSNT408I SQLCODE = -311, ERROR:  THE LENGTH OF INPUT HOST VARIABLE NUMBER 2 IS NEGATIVE OR
         GREATER THAN THE MAXIMUM
DSNT418I SQLSTATE   = 22501 SQLSTATE RETURN CODE

Technical reviewer: Albert Joseph, WND Software.

Last reviewed 2026-10-18 by the WND Software team. Written in our own words. For the full reference, check IBM’s Db2 for z/OS documentation for your release.