ILE COBOL – Miscellaneous Topics

By default, the debugger truncates variable output (often around 1024 characters), which makes it difficult to view or check bad data in variables during debugging. This is frequently visible during following activities:

• Large VARCHAR/CHAR fields
• Preparing dynamic SQL Statements
• Handling DATA Queue String
• Preparing or extracting JSON String
• Preparing or extracting XML String
• Api request or response

Example of large dynamic SQL Statement:

                              Evaluate Expression                         
                                                                          
 Previous debug expressions                                               
                                                                          
      661   ' "PROP_LOSS", coalesce(max(MONEY."MONEY"), 0.00) as "MONEY_L'
      721   'OSS", sum(RDKXX.D64) as "CLAIM_TOTAL" From AXXXXXX.RDKXX2025'
      781   ' as RDKXX Left Join (Select RDKXX.CLAIMOCC, RDKXX.COVERAGE, '
      841   'sum(RDKXX.D64) as "BUILDINGS" From AXXXXXX.RDKXXXXX Where R'
      901   'DKXX.COVERAGE = '850' and RDKXX.TRANS in('41','51','61') and'
      961   ' RDKXX.B70 between 1250101 and 1251231 Group By RDKXX.CLAIMO'
     1021   'CC, '                                                        

To view the full contents of large variables without debugger truncation in IBMi/ COBOL400 environments, programmer can override the display length in the debug command line using the syntax:

EVAL variable_name:c length

Explanation of Syntax:

• “:c” = character format display
• length = maximum number of characters to display

Depending on how much data programmer need to check, use the following formats in the debugger command entry line:

• Show first 35,000 characters: EVAL variable_name:c 35000
• Show first 5,000 characters: EVALvariable_name:c 5000

Example of large dynamic SQL Statement till first 4000 characters

                              Evaluate Expression                               
                                                                                
 Previous debug expressions                                                     
                                                                                
     3061   'From AXXXXXX.RDKXX2025 Where RDKXX.COVERAGE = '876' and RDK1'      
     3121   '8.TRANS in('41','51','61') and RDKXX.B70 between 1250101 and'      
     3181   ' 1251231 Group By RDKXX.CLAIMOCC, RDKXX.COVERAGE  Order By R'      
     3241   'DK18.CLAIMOCC, RDKXX.COVERAGE) PROP on RDKXX.CLAIMOCC = PROP'      
     3301   '.CLAIMOCC and RDKXX.COVERAGE = PROP.COVERAGE  Left Join (Sel'      
     3361   'ect RDKXX.CLAIMOCC, RDKXX.COVERAGE, sum(RDKXX.D64) as "MONEY'      
     3421   '" From AXXXXXX.RDKXX2025 Where RDKXX.COVERAGE = '866' and RD'      
     3481   'K18.TRANS in('41','51','61') and RDKXX.B70 between 1250101 a'      
     3541   'nd 1251231 Group By RDKXX.CLAIMOCC, RDKXX.COVERAGE  Order By'      
     3601   ' RDKXX.CLAIMOCC, RDKXX.COVERAGE) MONEY on RDKXX.CLAIMOCC = M'      
     3661   'ONEY.CLAIMOCC and RDKXX.COVERAGE = MONEY.COVERAGE Where RDK1'      
     3721   '8.GRPLNE = '75' and RDKXX.COVERAGE in('850','851','854','861''     
     3781   ','862','866','874','876') and RDKXX.B70 between 1250101 and '      
     3841   '1251231 and RDKXX.TRANS in('41','51','61') Group By RDKXX.PO'      
                                                                        More... 
 Debug . . .                                                                    
                                                                                
 F3=Exit   F9=Retrieve   F12=Cancel   F16=Repeat find   F19=Left   F20=Right    
 F21=Command entry       F23=Display output

Character fields

When a programmer calls an ILE COBOL program from the IBMi command line and passes character or variable-length data using single or double quotes, it is accepted by the program. Even if the value is ‘’ (blank), it is treated as spaces in ILE COBOL.

Example –

CALL PGM(COBCHARS) PARM (‘ ‘ ‘KUMAR’ ‘POLICY@’ ‘AB’’C’)

Here, ILE COBOL program COBCHARS receives 3 parameters as follows:

• Character FIELD-1 receives spaces
• Character FIELD-2 receives ‘KUMAR’
• Character FIELD-3 receives ‘POLICY@’
• Character FIELD-3 receives AB’C – Using double apostrophe to pass single apostrophe.

Numeric fields

When numeric data is passed as a decimal value from command line (for example, 123, -34.5, or 999.23),

1. It may not be accepted by an ILE program.
2. It may be accepted, and later may cause data decimal error.
3. It may be accepted and may give different output.

The same issue can also occur in RPG/RPGLE and CLP/CLLE programs.

When these parameters are passed via a data variable declared in CL, the COBOL program accepts those values and functions correctly. This issue arises when developers attempt to test or debug programs from the command line, and in doing so, pass decimal-formatted numeric data. To resolve this issue, the ILE COBOL program must be provided with the hexadecimal representation of the data via the command line, rather than decimal-formatted data.

When working with hexadecimal (HEX) data representations, programmers must ensure that the data being passed exactly matches the format and definition expected by the called COBOL program. Any mismatch can lead to serious runtime issues.

Key Rules to Follow:

• Data Format Alignment

  The structure, data type, and encoding of the HEX data must precisely match the COBOL field definitions (e.g., COMP, COMP-3, DISPLAY). If mismatched, the receiving program may accept the data successfully but interpret it incorrectly, resulting in junk or invalid values. This can later lead to decimal data errors (MCH1202) during arithmetic computations and MOVE operations involving numeric fields.

• Data Length Consistency

  The length of the passed HEX data must exactly match the receiving COBOL field length. If there is mismatch, it may cause to data truncation or overflow and eventually causing program crashes or abends. Data accepted with truncation may cause MCH1202. Data accepted with overflow is different than what is passed.

• Sign Alignment and Consistency

  For numeric fields (especially COMP and COMP-3), the sign representation must be correctly aligned with COBOL expectations. If do not match, it may cause decimal data errors (MCH1202).

Zoned – Unsigned Integers

Zoned – Unsigned Decimals

Zoned – Signed Integers

Zoned – Signed Decimals

Zoned – Signed Decimals with Separate leading or trailing

Packed – Unsigned Integers

Packed – Unsigned Decimals

Packed – Signed Integers

Packed – Signed Decimals

Packed – Signed Decimals with Separate leading or trailing

Step 1: Compile Program with Debug Information

Before debugging, compile the required COBOL program with debug options enabled. Use one of the following commands based on source type:

For CBL source type objects:

CRTCBLPGM PGM(MYLIB/CBLPGM) + 
          SRCFILE(MYLIB/QCBLLESRC) + 
          OPTION(*SRCDBG)
CRTCBLPGM PGM(MYLIB/CBLPGM) +
          SRCFILE(MYLIB/QCBLLESRC) + 
          OPTION(*LSTDBG)

For CBLLE source type objects:

CRTBNDCBL PGM(MYLIB/CBLLEPGM) + 
          SRCFILE(MYLIB/QCBLLESRC) + 
          DBGVIEW(*SOURCE)
CRTBNDCBL PGM(MYLIB/CBLLEPGM) + 
          SRCFILE(MYLIB/QCBLLESRC) + 
          DBGVIEW(*LIST)

• OPTION(*SRCDBG), OPTION(*LSTDBG), DBGVIEW(*SOURCE) or DBGVIEW(*LIST) adds debugging information to the program.

• This allows:

  1. Setting breakpoints
  2. Viewing and modifying variable values
  3. Using debugging commands – ATTR, F11 etc.

Step 2: Start the Debugger

IBM i provides an interactive debugger using the STRDBG command. To start debugging:

STRDBG PGM(MYLIB/CBLPGM) + 
       OPMSRC(*YES) + 
       UPDPROD(*YES)
STRDBG PGM(MYLIB/CBLLEPGM) + 
       OPMSRC(*NO) + 
       UPDPROD(*YES)

• Press ENTER key to activate debug mode.
• The system loads the program and displays the debug screen.
• OPMSRC(*YES): Crucial. If left as the default (*NO), the green screen will bypass your source code and throw you into a legacy unformatted command-line debug environment.
• UPDPROD(*YES): Allows the program to update database files in production libraries during active debug session

Step 3: Set Breakpoints

Breakpoints are used to pause execution at a specific line. We can set breakpoints in the following ways:

• Press F6 on the required source line.
• Or type BREAK 100 or type BR 100 to pause at line 100.
• Multiple breakpoints can be set on and set off while debugging.
• Conditional breakpoint can be set on like
  BREAK 1000 WHEN FIELD = ‘1000’

Step 4: Run the Program

Run the program as usual from command line based on parameter requirement:

CALL PGM(MYLIB/CBLPGM01)
CALL PGM(MYLIB/CBLPGM02) +
     PARM(‘ABC’ x’F1F1’)
CALL PGM(MYLIB/CBLLEPGM01) 
CALL PGM(MYLIB/CBLLEPGM02) + 
     PARM(‘NEW’ x’012D’)

• When execution reaches a breakpoint:

  1. The debugger pauses the program.
  2. The current source line is displayed.

Step 5: Debug the Program

Control Execution:

Use the following function keys:

• F10 (Step): Execute one line at a time.
• Shift + F10(Step Into): Go into called programs or procedures.
• F12 (Resume): Continue execution until next debug point or complete the program.

Check and Modify Variables:

• View variable value:

  1. EVAL MYFIELD
  2. Press F11 on the variable.

• Change a variable value:

  1. EVAL CHARFIELD = ‘NEWVALUE’
  2. EVAL ZONEDFIELD = -123
  3. EVAL PACKEDFIELD = -88.88

Step 6: End Debugging

To stop debugging:

ENDDBG