APIs by Example: User Index APIs, Part Two

In this follow-up to User Index APIs, Part One, I will show how the User Index APIs can be put to work to create a Convert Display File Constants (CVTDSPFCNS) command.

As discussed in part one, user indexes offer sort and search functionality, very much like a keyed file does, but the process is significantly faster. The CVTDSPFCNS utility presented in this article employs the Add User Index Entry and Retrieve User Index Entry APIs, the Create User Index command that I demonstrated in the previous installment, and the native Delete User Index command.

The utility itself was inspired by a facility offered by DDS, whereby display file constants can be externalized into message descriptions, giving you the option to change the constants without recompiling the display file.

This especially comes in handy when you need to enable applications to support more than one language. Simply copy the message file holding the message descriptions to another library, for example APPLIBDEU (Application Library – German), and translate the copied message file’s message descriptions to German. If you now add the APPLIBDEU library before the original application library in your job’s library list, the display file will start “speaking” German.

The system automatically retrieves the message text of the message IDs referred by the MSGID keyword in the display file record format every time an output operation is performed against the record format.

Using this technique, you will only need to maintain one display file no matter how many languages you have to support. Adding a new language only requires you to translate the messages again. No programming is needed! Optionally, you can also choose to externalize all display file error messages defined by the ERRMSG keyword.

The task solved by the user index in the CVTDSPFCNS command is to keep track of the message IDs generated during the conversion process. The message ID prefix is either passed as an explicit value by the command or generated from each record format name. An incrementing integer is then appended to this prefix. To avoid possible duplicate message IDs, it is necessary to store each message ID prefix’s current integer value so that when you want to add to the message file, you have a way of knowing what the next available message ID will be.

This requirement meant that I had to make the utility perform an initial pass through the display file source to retrieve any already existing MSGID and ERRMSGID referenced message IDs. That facility also simplifies the task of adding new constants to a display file that already has had its constants externalized; simply add the new constants and rerun the CVTDSPFCNS command.

Download the save file containing the source code.

Read the entire article