How to Code the Return Value in a Bindable (CEE) API

Troubleshooting

Problem

An optional ILE feedback code can be coded on all bindable (CEE) APIs. It is a 12-byte feedback code passed by reference. If specified as an argument, feedback information (a condition token) is returned to the calling procedure.

Resolving The Problem

       dcl-ds fb1 qualified;
         sev     int(5);
         msgid   char(2);  // contains hex value of msgid
         flags   char(1);
         facID   char(3);
         isi     int(10);
       END-DS;

The actual prototype for an API might look like this (for the CEEDATE API):

       Dcl-Pr Prc_CEEDATE ExtProc('CEEDATE') opDesc;
         day#            int(10) const;
         picture         Char(30) const;
         result          Char(30);
         error           like(fb1);
       END-PR;

Refer to the IBM Documentation Center to view the specifications for each API.
https://www.ibm.com/docs/en/i/7.6.0?topic=ssw_ibm_i_76/apis/ile4a1TOC.html

For each API, a list of feedback codes is given. In the feedback code, bytes 3 and 4 contain a hex value with a message ID that can be translated to a character value and compared against the list of feedback codes, to determine the nature of the problem with the API, if a problem occurs. This can help during debug of the code, or during execution if an unexpected error occurs.

To get a readable version of the message ID, Convert Hex to Character (CVTHC) can be used to convert from the hex value to a character value. An example follows:

       CTL-Opt actgrp(*new);
       //Dcl-S day#In          int(10) inz(161648);
       //  161648 is 05/12/2025
       Dcl-S day#In          int(10) inz(9999999);
       Dcl-S picIn           Char(30) INZ('MMDDYYYY');
       Dcl-S resultOut       Char(30);
       dcl-ds fb1 qualified;
         sev             int(5);
         msgid           char(2);  // contains hex value of msgid
         flags           char(1);
         facID           char(3);
         isi             int(10);
       END-DS;

       Dcl-Pr Prc_CEEDATE ExtProc('CEEDATE') opDesc;
         day#            int(10) const;
         picture         Char(30) const;
         result          Char(30);
         error           like(fb1);
       END-PR;

       dcl-pr cvthc extproc(*dclcase); // Convert 1-byte hex values to 2-byte character values
         long_char_result char(65535) options(*varsize);       //  output: 'C1C2C3'
         short_hex_input char(32767) options(*varsize) const;  //  input: x'C1C2C3'
         output_bytes int(10) value;                           //  6 bytes in the output
       end-pr;
       dcl-ds msgid qualified;
         prefix char(3);
         num char(4);
       end-ds;


       Prc_CEEDATE(day#In: picIn : resultOut: fb1);

       msgid.prefix = fb1.facId;
       cvthc (msgid.num : fb1.msgid : 4);
       if msgid.num = '0000';
         snd-msg 'Result ' + resultOut;
       else;
         // Get the message ID from the feedback code
         //  Message ID . . . . . . . . . :   CEE2512
         // Message file . . . . . . . . :   QCEEMSG
         //  Library  . . . . . . . . . :     QSYS
         // Message text:   The value for the given Lilian date is not valid
         snd-msg 'CEEDATE Error Message: ' + msgid;
       endif;
       *INLR=*ON;

Compile using CRTBNDRPG PGM(<yourlib>/CEEDATER3) SRCFILE(<yourlib>/QRPGLESRC)
This sample is hard coding an invalid Lilian value just to demonstrate the use of the fb structure.
Dcl-S day#In int(10) inz(9999999);

Call from command line:
> call ceedater3
CEEDATE Error Message: CEE2512

Change the sample to use valid Lilian value, for example
Dcl-S day#In int(10) inz(161648);
// 161648 is 05/12/2025

> call ceedater3
Result 05122025

More details and explanations are available in this IBM Documentation link
https://www.ibm.com/docs/en/i/7.5.0?topic=handling-i-messages-bindable-api-feedback-code

[{"Type":"MASTER","Line of Business":{"code":"LOB68","label":"Power HW"},"Business Unit":{"code":"BU070","label":"IBM Infrastructure"},"Product":{"code":"SWG60","label":"IBM i"},"ARM Category":[{"code":"a8m3p000000hB4rAAE","label":"API"},{"code":"a8m0z0000000CHtAAM","label":"Programming ILE Languages"}],"ARM Case Number":"","Platform":[{"code":"PF012","label":"IBM i"}],"Version":"and future releases;7.1.0"}]

Historical Number

533265209

Was this topic helpful?

Document Information

Modified date:
13 May 2025

UID

nas8N1012797

Tips