Handling Oversized Character Values Gracefully

The FmtNum subprocedure has been very useful to me in dealing with oversized numbers. When I use FmtNum in a report program, it is obvious to anyone when a number has gotten too large for its allotted space. I suppose it was only a matter of time until I would need to show that a character value is too large for the space I had allowed for it. While chopping off the end of many character fields, such as customer names and inventory item descriptions, is no big deal, chopping of the end of others does present a problem.

I encountered such a problem recently at my day job. The well-known ERP system we run allows more room than we use for most data values. I was cramped for space in the detail line of a report and was looking for places to trim some fat. However, I had to be sure that a certain alpha field value, the inventory item number, was not truncated.

I considered several ways to indicate that a value was truncated, and finally decided to place a greater-than sign in the last position. For example, moving the value ABCDE to a four-byte variable yields the value ABC>. The routine is implemented as a function, returning a variable-length value of up to 256 characters. Since output fields on displays and reports are much shorter than 256 bytes, this limitation is in effect infinity. The first parameter is a variable-length string that is to be copied to the fixed-length destination.

The second parameter is the length of the destination field or variable. This parameter is defined as a two-byte (three-digit) unsigned value. For more information about the numeric formats, see When a 10-Digit Variable Won’t Hold a 10-Digit Number.

While I was preparing this routine for publication, it occurred to me that some folks might like to indicate a truncated value in a different way. For this reason, I added an optional parameter in which you can pass some other character to indicate truncation.

Here’s the procedure prototype.

D FmtChar         pr           256a   varying                
D  inString                    256a   varying value          
D  inLength                      3u 0 value                  
D  inTruncChar                   1a   value options(*nopass) 

Here’s the subprocedure itself.

D/copy prototypes,FmtChar                                    
                                                             
P FmtChar         b                   export                 
D                 pi           256a   varying                
D  inString                    256a   varying value          
D  inLength                      3u 0 value                  
D  inTruncChar                   1a   value options(*nopass) 
                                                             
D TruncChar       s              1a                          
D DftTruncChar    c                   const('>')             
                                                             
 /free                                                       
    if inLength <= *zero                                     
    or %len(%trimr(inString)) <= inLength;                   
       return inString;                                      
    endif;

    if %parms() < 3;                                     
       TruncChar = DftTruncChar;                         
    else;                                                
       TruncChar = inTruncChar;                          
    endif;                                               
                                                         
    if inLength = 1;                                     
       return TruncChar;                                 
    else;                                                
       return %subst(inString:1:inLength-1) + TruncChar; 
    endif;                                               
 /end-free                                               
P                 e

Here are some examples of calls to FMTCHAR.

 /free
     ToField = FmtChar(FromField:%len(ToField));             
     ToField = FmtChar(FromField:%len(ToField):'-');         
 /end-free

In the first assignment, a truncated value is indicated by a greater-than sign in the last position. In the second assignment, truncated is indicated with a hyphen. In each case, the size of the receiving field (or variable) is passed through the second parameter, ensuring that FMTCHAR is able to determine whether the value is truncated or not.

I suggest adding this routine to a module of string-handling routines from which a service program is built, but I will leave it to the interested reader to implement the FmtChar function according to his or her good judgment.

RELATED STORIES

When a 10-Digit Variable Won’t Hold a 10-Digit Number

Handling Oversized Numbers Gracefully