If there's an API for your problem, don't hesitate to use it.

Brief: Normally, formatting a numeric field with an edit code or edit word is only practical when done at the time you write the variable (with DDS specs or a HLL specification). With V2R2, OS/400 provides edit function Application Programming Interfaces (APIs) that can be used to apply an edit code or edit words to a numeric field before you write it.

It hasn't happened to me often, but a few times in the past, I wanted to include an edited field within another field. For example, when making up a line for display, I wanted to embed an edited numeric field within other text. Because I could not determine ahead of time where the numeric field should be within the text, I could not simply define the field as a separate field on the display. I tried writing a subroutine to mimic the behavior of an edit code, but the problem quickly escalated to the point where that attempt was impractical. So I simply gave up, gave the numeric field it own location and used the edit codes.

That didn't really solve the problem; and until V2R2, there was no good system-supplied solution. But now there are three application programming interfaces (APIs) that will apply an edit code or edit word to a numeric field, and format the field. This means that you can now use an edited version of the field as part of a text string. I've furnished the "OS/400 API Basics" sidebar to provide a little background on these edit function APIs.

How the Editing APIs Are Used

To format a numeric field with the APIs, you must use two of the three available APIs. Your first API selection depends upon whether you want to edit with an edit code or with an edit word. After choosing one of those two APIs, you use the third API to actually apply the editing to the field.

The QECCVTEC API is used to work with an edit code. For edit words, use the QECCVTEW API. These APIs take the edit code or edit word value plus some other parameters and create an edit mask that is returned as a parameter. The edit mask must then be passed to the QECEDT API to perform the actual formatting on the numeric field. The variable can then be used in your program as a character string value. For example, you can embed the edited value in a message with a series of concatenate operations.

During my testing of these APIs, I examined the edit masks returned by them and decided that it would be pointless to try to generate the edit mask through other means. The edit mask is a hexadecimal character string that is used as a parameter to the MI edit instruction. I tell you this so that you will not think you can bypass calling either of the first two APIs and proceed directly to the QECEDT API. Trying to create your own edit mask would probably be as much work as trying to edit the field in code without the APIs.

Parameters Used With the QECCVTEC and QECCVTEW APIs

The parameters used with the QECCVTEC (edit code) and QECCVTEW (edit word) APIs are shown in Figures 1 and 2. You must supply values for each of the input parameters associated with the particular API you are using. Returned values are available in the output parameters. Note that each of the parameter lists ends with the error code parameter, followed by a list of possible error messages. (For more information, see the accompanying sidebar, "The API Error Code Parameter.")

The first three parameters of the QECCVTEC and QECCVTEW APIs are the same. The first returns the edit mask. The second returns the edit mask length, and the third returns the length of the numeric field after the edit mask is applied. All three of these parameters are used later by the QECEDT (apply edit mask) API.

For the QECCVTEC API, the additional parameters that you must supply include the edit code, the fill or floating currency character, the source variable precision (length) and the source variable decimal positions. The edit code is one of the valid system-defined edit codes or the user-defined edit codes 5-9.

You may look at the parameters for QECCVTEC and wonder where the value that you want to edit is specified. The value is not specified in this API-just the edit code that you want to use. Remember that the purpose of this API is to generate the edit mask that will be applied to the value you want to edit. Even though the value itself is not specified in this API, you should be careful to define the precision and decimal positions parameters so that they are in agreement with the value to be edited.

The QECCVTEW API has fewer parameters than the QECCVTEC API, because most of the options are specified in the edit word. The edit word and the length of the edit word are passed as input parameters to this API in the same format as used in RPG/400 or DDS.

If you are going to edit several similar fields in your programs, you can save the values of the edit mask, edit mask length and receiver variable length. For example, if you intend to edit three DEC(9,2) fields with the 'J' edit code, you can call the QECCVTEC API once to generate the edit mask and go on to use that same edit mask for each of the three edits.

Parameters Used With the QECEDT API

Once the edit mask and associated fields have been generated, you can edit the value with the QECEDT API. As shown in 3, most of the parameters used with this API are input parameters. The resulting edited field is returned to your program in the first parameter.

Once the edit mask and associated fields have been generated, you can edit the value with the QECEDT API. As shown in Figure 3, most of the parameters used with this API are input parameters. The resulting edited field is returned to your program in the first parameter.

Parameter number two, receiver variable length, indicates to the API the length of the edited field. There is no need for you to calculate this value manually. It is returned from the QECCVTEC or QECCVTEW API and should be used as is. For example, editing a DEC(9,2) field with the 'A' edit code results in a receiver variable length of 14. There are nine digit positions, two thousands separators, the decimal position and the two-character "CR" sign.

The third parameter, source variable, is where you actually supply the value to be edited. The fourth and fifth parameters further describe the value that you want to edit. The source variable class is used to specify the type of numeric value. If you have defined the value within your RPG program, the type defaults to *PACKED. If the value is defined as a data structure subfield or a field from a file, the value might also be *BINARY or *ZONED. You must use the correct type so that the API will know how to work with the value. The fifth parameter, source variable precision, indicates the total number of digits in the value. Binary fields have a precision of either 5 or 10, but packed or zoned fields have the precision that they were declared with. For example, a *PACKED(9,2) field has a precision of 9.

The sixth, seventh and eighth parameters are used to pass the generated edit mask, edit mask length and zero balance fill character to the QECEDT API. The edit mask and edit mask length are return parameters from the QECCVTEC or QECCVTEW API, and should simply be used as is for the QECEDT API. The zero balance fill character is a return value from the QECCVTEC API and should also be used as is. However, the QECCVTEW API does not return a zero balance fill character, so you have to supply a null byte (the value x'00') as the fill character. The documentation for this API indicates that unpredictable results may occur if any other value (for example, a blank, x'40') is used in this parameter.

The Sample Program

The sample program in 4 demonstrates how to use the QECCVTEC and QECEDT APIs to edit a *PACKED(9,2) field. The first part of the executable code gets the edit mask associated with the 'A' edit code for a (9,2) field. The field to be edited is then initialized and printed, so that you can see the results of printing the unedited field with other text.

The sample program in Figure 4 demonstrates how to use the QECCVTEC and QECEDT APIs to edit a *PACKED(9,2) field. The first part of the executable code gets the edit mask associated with the 'A' edit code for a (9,2) field. The field to be edited is then initialized and printed, so that you can see the results of printing the unedited field with other text.

Next, parameters are set for the QECEDT API. Note that the receiver variable length, edit mask, edit mask length and zero balance fill character parameters are set to the values returned from the QECCVTEC API. The QECEDT API is then called and finally the edited return variable is embedded in a text field and printed.

A Practical Solution

Before the edit function APIs, it wasn't practical for a programmer to dynamically construct output which included formatted numeric data. Now, with the APIs, it's possible. These functions open the door for you to create versatile programs that can be employed generically. For example, you could create a general-purpose subfile program which has one 79-byte alphanumeric field in the subfile record. By calling other programs, you can build subfields including edited numeric data and then display the subfile.

Craig Pelkie can be contacted through Midrange Computing.

References

System Programmer's Interface Reference, SC41-8223 (CD ROM QBKA8401) CL Programmer's Guide, SC41-8077 (CD ROM QBKA7101)

The Edit APIs

Figure 1 Parameters Used With QECCVTEC API

 Number Description Type Usage 1 Edit mask. This is passed to the QECEDT API. CHAR(256) Output 2 Edit mask length. Length of the edit mask, BIN(4) Output passed to the QECEDT API. 3 Receiver variable length. Length of the BIN(4) Output output field produced when the edit mask is used. Pass to the QECEDT API. 4 Zero balance fill character. CHAR(1) Output Pass to the QECEDT API. 5 Edit code. This is the code that is to be CHAR(1) Input translated into an edit mask. Valid values are A-D, J-Q, Y-Z, 1-9. 6 Fill or Floating currency indication. Used CHAR(1) Input to indicate how output is padded on left. ' ' - (blank) Blank fill: all suppressed zeros are replaced with blanks. '*' - Asterisk fill: all suppressed zeros are replaced with asterisks. Character - Blank fill: the character is used as a floating currency symbol and placed to the left of the first nonsuppressed digit. Valid values are in the range x'41' - x'FE'. 7 Source variable precision. Number of BIN(4) Input positions before the decimal point. Valid values depend on the edit code used: Edit code Y: 3-7 Other codes: 1-31 Within these ranges, the maximum length depends on the class of the variable: Packed, Zoned: Precision is as declared. For example, a PACKED(9,2) field has a precision of 9. BINARY(2): Precision is 5. BINARY(4): Precision is 10. 8 Source variable decimal positions. Number BIN(4) Input of digits after the decimal point. Value must be less than or equal to source variable precision and greater than or equal to 0. The allowable values depend on the class of the variable: Packed, Zoned: Decimal positions are as declared. For example, a PACKED(9,2) field has 2 decimal positions. BINARY(2): Decimal position is 0. BINARY(4): Decimal position is 0. 9 Error code (see sidebar: The API Error Code Parameter) I/O Error Messages Sent by QECCVTEC API Message Message Text CPF2620 Field longer than integer or fraction mask. CPF2639 Edit mask too large. CPF27B2 Edit code not valid. CPF27B3 Fill/floating currency indication not valid. CPF27B4 Source variable precision not valid. CPF27B5 Source decimal position not valid. CPF3CF1 Error code parameter not valid. CPF9801 Object &2 in library &3 not found. CPF9802 Not authorized to object &2. 
 
 The Edit APIs
 
 Figure 2 Parameters Used With QECCVTEW API
 
 Number Description Type Usage 1 Edit mask. This is passed to the QECEDT CHAR(256) Output API. 2 Edit mask length. Length of the edit mask, BIN(4) Output passed to QECEDT API. 3 Receiver variable length. Length of the BIN(4) Output output field produced when the edit mask is used. Pass to the QECEDT API. 4 Edit word. The edit word that is to be CHAR(*) Input translated into the edit mask. The character in system value QCURSYM is used as a currency symbol if it is used in the edit word. 5 Edit word length. The actual length of the BIN(4) Input edit word. Valid values range from 1-256. 6 Error code (see sidebar: The API Error Code I/O Parameter) Error Messages Sent by QECCVTEC API Message Message Text CPF2639 Edit mask too large. CPF27B6 Edit word length not valid. CPF3CF1 Error code parameter not valid. 
 
 The Edit APIs
 
 Figure 3 Parameters Used With QECEDT API
 
 Number Description Type Usage 1 Receiver variable. Contains the edited . CHAR(*) Output output. 2 Receiver variable length. The length of the BIN(4) Input edited receiver variable.Set in QECCVTEC or QECCVTEW APIs. 3 Source variable. The numeric value that is * Input to be converted. Type is defined in Source Variable Class parameter; length is specified in Source Variable Precision parameter. 4 Source variable class. Used to specify the CHAR(10) Input type of variable in the Source Variable parameter. Valid values are: *BINARY *PACKED *ZONED 5 Source variable precision. The maximum BIN(4) Input length depends on the class of the variable: Packed, Zoned: Precision is as declared. For example, a PACKED (9,2) field has a precision of 9. BINARY(2): Precision is 5. BINARY(4): Precision is 10. 6 Edit mask. Use the value returned from the CHAR(*) Input QECCVTEC or QECCVTEW APIs. 7 Edit mask length. Use the value returned BIN(4) Input from the QECCVTEC or QECCVTEW APIs. 8 Zero balance fill character. CHAR(1) Input QECCVTEC used to create edit mask: use the value returned in the zero balance fill parameter. QECCVTEW used to create edit mask: use x'00' value for this parameter. 9 Error code (see Sidebar: The API Error Code I/O Parameter) Error Messages Sent by QECEDT API Message Message Text CPF27AB Source variable class not valid. CPF27AF Edit mask not valid. CPF27B4 Source variable precision not valid. CPF27B7 Receiver variable length not valid. CPF27B8 Edit mask length not valid. CPF3CF1 Error code parameter not valid. 
 
 The Edit APIs
 
 Figure 4 RPG Program XCP001RG
 
 **************************************************************** * Program edit - Test convert edit code (QECCVTEC) API **************************************************************** FQSYSPRT O F 132 OF PRINTER * I 'This is the value - C BEFORE I 'before editing' I 'This is the value - C AFTER I 'after editing' **************************************************************** * Standard API error data structure **************************************************************** IAPIERR DS I B 1 40AEBYPR I B 5 80AEBYAV I 9 15 AEEXID I 16 16 AERESV I 17 116 AEEXDT **************************************************************** * Standard parameters for QECCVTEC (convert edit code) API **************************************************************** IECPARM DS I 1 256 ECMASK I B 257 2600ECMSKL I B 261 2640ECRCVL I 265 265 ECZBAL I 266 266 ECEDCD I 267 267 ECFILL I B 268 2710ECSPRC I B 272 2750ECSDEC **************************************************************** * Standard parameters for QECEDT (edit) API **************************************************************** IEDPARM DS I B 1 40EDRCVL I 5 14 EDSCLS I B 15 180EDSPRC I B 19 220EDMSKL I 23 23 EDZBAL * Get edit mask for edit code "A" for a 9.2 field * C MOVE 'A' ECEDCD Edit code C CLEARECFILL Fill/float C Z-ADD9 ECSPRC Source prec C Z-ADD2 ECSDEC Source decimals C EXSR #CVTEC * * Print unedited 9.2 field, apply edit mask from * previous step, then print edited 9.2 field * C Z-SUB1234567.89WORK92 92 C MOVE WORK92 WORK9 9 C BEFORE CAT WORK9:1 PRTFLD 80 P C EXCPTDETAIL * C Z-ADDWORK92 EDSVAR Source var C Z-ADDECRCVL EDRCVL Rcv var length C MOVELECMASK EDMASK Edit mask C Z-ADDECMSKL EDMSKL Edit mask len C MOVELECZBAL EDZBAL Zero bal fill C EXSR #EDIT * C AFTER CAT EDRVAR:1 PRTFLD P C EXCPTDETAIL * C SETON LR * **************************************************************** * Call QECCVTEC (convert edit code) API **************************************************************** C #CVTEC BEGSR C CLEARECMASK Edit mask C CLEARECMSKL Edit mask len C CLEARECRCVL Rcv var length C CLEARECZBAL Zero bal char C CLEARAPIERR API error code C Z-ADD116 AEBYPR Bytes provided * C CALL 'QECCVTEC' C PARM ECMASK Edit mask C PARM ECMSKL Edit mask len C PARM ECRCVL Receiver length C PARM ECZBAL Zero bal fill C PARM ECEDCD Edit code C PARM ECFILL Fill/float C PARM ECSPRC Source prec C PARM ECSDEC Source decimals C PARM APIERR API error code * C ENDSR * **************************************************************** * Call QECEDT (edit) API **************************************************************** C #EDIT BEGSR C CLEAREDRVAR Receiver var C Z-ADD9 EDSPRC Source var prec C MOVEL'*PACKED' EDSCLS P Source class C CLEARAPIERR API error code C Z-ADD116 AEBYPR Bytes provided * C CALL 'QECEDT' C PARM EDRVAR 64 Receiver var C PARM EDRCVL Rcv var length C PARM EDSVAR 92 Source var C PARM EDSCLS Source class C PARM EDSPRC Source var prec C PARM EDMASK256 Edit mask C PARM EDMSKL Edit mask len C PARM EDZBAL Zero bal fill C PARM APIERR API error code * C ENDSR * OQSYSPRT E 1 DETAIL O PRTFLD 80