Difference between revisions of "CPGuide - Message Management"

From EDM2
Jump to: navigation, search
(Created page with "{{IBM-Reprint}} {{CPGuide}} This chapter describes the use of message files to hold an application's text messages to the user. Keeping messages in a message file simplifies ...")
(No difference)

Revision as of 02:43, 27 March 2020

Reprint Courtesy of International Business Machines Corporation, © International Business Machines Corporation

Control Program Programming Guide and Reference
  1. Introduction to the Control Program
  2. Control Program Functions
  3. Keyboard Functions
  4. Mouse Functions
  5. Video Functions
  6. Data Types
  7. Errors
  8. Debugging
  9. Kernel Debugger Communications Protocol
  10. Device I/O
  11. Dynamic Linking
  12. Error Management
  13. Exception Management
  14. Extended Attributes
  15. File Management
  16. File Names
  17. File Systems
  18. Generic IOCtl Commands
  19. Memory Management
  20. Message Management
  21. National Language Support
  22. Pipes
  23. Program Execution Control
  24. Queues
  25. Semaphores
  26. Timers

This chapter describes the use of message files to hold an application's text messages to the user. Keeping messages in a message file simplifies changing those messages, for example when maintaining versions of the same application for different countries.

The following topic is related to the information in this chapter:

  • National language support

About Message Management

For full-screen applications, text messages-used by an application to display information to the user-can be held in a message file.

To keep and maintain messages in a message file, create a separate message file for each national language you intend to support. Use the MKMSGF utility program to create a binary version of a message file, and the MSGBIND utility program to bind the binary file to the application's executable file. Binding the messages to an application's executable file inserts the messages into the .EXE file. This enables faster access (but, of course, a larger .EXE file).

OS/2 provides several functions to assist in message management. Applications can get messages from a message file, substitute variable information into the messages, and write messages to the screen or to a file.

Code Page Considerations You can have versions of the message file for each code page you choose to support. When you use MKMSGF to create the message files, the utility will insert the code page information and link together the message files of the different versions.

When message files are linked together in this manner, DosGetMessage will search for the appropriate version of the message for the code page that is active at the time the function is called. If there is no version of the message for the current code page, the function will return the first version of the message, no matter which code page it is associated with.

Note: To create portable source code for message files, make sure you specifically set the code page in CONFIG.SYS using the CODEPAGE statement. If you have the wrong code page, or use the default code page, which could be wrong, DosGetMessage returns error code 37 (ERROR_CODE_PAGE_MISMATCHED).

Using Message Management

DosGetMessage retrieves a message from the specified system message file, and inserts variable information into the body of the message.

DosInsertMessage inserts variable text-string information into the body of the message, but does not retrieve the message.

DosPutMessage sends the message in a buffer, usually to a display screen. DosPutMessage formats the screen buffer to prevent words from being split at the end of a line.

DosQueryMessageCP retrieves the message file list of code pages and language identifiers.

Note
In the example code fragments that follow, error checking was left out to conserve space. Applications should always check the return code that the functions return. Control Program functions return an APIRET value. A return code of 0 indicates success. If a non-zero value is returned, an error occurred.

Message Retrieval and String Substitution

DosGetMessage retrieves a message from a system message file, and inserts variable text-string information into the message.

In the following code fragment, the message file is "D:\MESSAGE\AUTOMSG.MSG". The third message within the message file contains the string "%1 Error at Station %2". The application calls DosGetMessage to convert this message into the string "Automation Failure Error at Station 69B".


    #define INCL_DOSMISC   /* Miscellaneous values */
    #include <os2.h>
    #include <stdio.h>

    UCHAR   *ucIvTable[2];    /* Table of variables to insert       */
    ULONG    ulIvCount;       /* Number of variables                */
    UCHAR    ucDataArea[80];  /* Message buffer (returned)          */
    ULONG    ulDataLength;    /* Length of buffer                   */
    ULONG    ulMsgNumber;     /* Number of the message              */
    UCHAR    ucFileName[40];  /* Message file path-name string      */
    ULONG    ulMsgLength;     /* Length of message (returned)       */
    UCHAR    ucField1[20];    /* String to substitute into variable */
                              /* field %1 of the message            */
    UCHAR    ucField2[20];    /* String to substitute into variable */
                              /* field %2 of the message            */
    APIRET   ulrc;            /* Return code                        */

    strcpy(ucField1,
           "Automation Failure");   /* Define the field with which to  */
                                    /* perform the first substitution  */

    strcpy(ucField2,
           "69B");                  /* Define the field with which to            */
                                    /* perform the second substitution           */

    ucIvTable[0] = ucField1;       /* Set up the array of pointers to           */
    ucIvTable[1] = ucField2;       /* substitute strings                        */

    ulIvCount = 2;                 /* Two variable message fields in message    */

    ulDataLength = 80;             /* Data buffer that will receive the         */
                                   /* complete message is 80 bytes in size      */

    ulMsgNumber = 3;               /* Specify the third message in the          */
                                   /* message file                              */

    strcpy(ucFileName,
           "D:\\MESSAGE\\AUTOMSG.MSG");
           /* Path name of the message file            */

    ulrc = DosGetMessage(ucIvTable,
                         ulIvCount,
                         ucDataArea,
                         ulDataLength,
                         ulMsgNumber,
                         ucFileName,
                         &ulMsgLength);

    if (ulrc != 0) {
        printf("DosGetMessage error: return code = %ld",
               ulrc);
        return;
    }

On successful return, the DataArea buffer contains the complete message (with the two variable fields appropriately updated), and the MsgLength variable contains the length of the message that was placed into the DataArea buffer.

If an error occurs (that is, if the return code does not equal 0), a message that is related to the error will be placed in the message buffer. See the DosGetMessage API reference in Control Program Programming Reference for a description of the default messages that can be placed into the user's buffer if an error occurs during the processing of these requests.

Text String Substitution in Memory

DosInsertMessage inserts variable text-string information into a message that resides within program memory.

In the following code fragment, the message resides in a program string variable named Message. The message is the string "%1 Error at Station %2". The application calls DosInsertMessage to convert this message into the string "Automation Failure Error at Station 69B".

    #define INCL_DOSMISC   /* Miscellaneous values */
    #include <os2.h>
    #include <stdio.h>

    UCHAR   *ucIvTable[2];               /* Table of variables to insert         */
    ULONG    ulIvCount;                  /* Number of variables                  */
    UCHAR    ucMsgInput[40] = "%1 Error at Station %2";     /* The input message */
    ULONG    ulMsgInLength;              /* Length of input message              */
    UCHAR    ucDataArea[80];             /* Message buffer (returned)            */
    ULONG    ulDataLength;               /* Length of updated message buffer     */
    ULONG    ulMsgLength;                /* Length of updated message (returned) */
    UCHAR    ucField1[20];               /* String to substitute into variable   */
                                         /* field %1 of the message              */
    UCHAR    ucField2[20];               /* String to substitute into variable   */
                                         /* field %2 of the message              */
    APIRET   ulrc;                       /* Return code                          */

    strcpy(ucField1,
           "Automation Failure");        /* Define the field with which to  */
                                         /* perform the first substitution  */

    strcpy(ucField2,
           "69B");                       /* Define the field with which to  */
                                         /* perform the second substitution */

    ucIvTable[0] = ucField1;     /* Set up the array of pointers to */
    ucIvTable[1] = ucField2;     /* substitute strings              */

    ulIvCount = 2;                          /* Two variable message fields in  */
                                            /* message                         */

    ulMsgInLength = strlen(ucMsgInput);     /* Length of input message         */

    ulDataLength = 80;                      /* Data buffer that will receive   */
                                            /* the complete message is 80      */
                                            /* bytes in size                   */

    ulrc = DosInsertMessage(ucIvTable,
                            ulIvCount,
                            ucMsgInput,
                            ulMsgInLength,
                            ucDataArea,
                            ulDataLength,
                            &ulMsgLength);

    if (ulrc != 0) {
        printf("DosInsertMessage error: return code = %ld",
               ulrc);
        return;
    }


On successful return, the DataArea buffer contains the complete message (with the two variable fields appropriately updated), and the MsgLength variable contains the length of the message that was placed into the DataArea buffer.

If an error occurs (that is, if the return code does not equal 0), a message that is related to the error will be placed in the message buffer. See the DosGetMessage API reference in Control Program Programming Reference for a description of the default messages that can be placed into the user's buffer if an error occurs during the processing of these requests.

Writing Messages

DosPutMessage is used to write the message to the screen or to a file on a disk.


The following code fragment writes the message string contained in MessageBuffer to the file specified by FileHandle. The message string has already been placed in MessageBuffer using either DosGetMessage or DosInsertMessage. MsgLength was set to the length of the message string by the same call that put the message into MessageBuffer.

    #define INCL_DOSMISC   /* Miscellaneous values */
    #include <os2.h>
    #include <stdio.h>


    HFILE   hfFileHandle;           /* Handle of output file or device */
    ULONG   ulMsgLength;            /* Length of message buffer        */
    UCHAR   ucMessageBuffer[80];    /* Message buffer                  */
    APIRET  ulrc;                   /* Return code                     */

    ulrc = DosPutMessage(hfFileHandle,
                         ulMsgLength,
                         ucMessageBuffer);

    if (ulrc != 0) {
        printf("DosPutMessage error: return code = %ld",
               ulrc);
        return;
    }

To write a message to the screen, use the standard output file handle.

Code Page Information Associated with Message Files

DosQueryMessageCP obtains a list of code page identifiers and language identifiers that are associated with a specified message file.

In the following code fragment code page and language identifiers associated with the message file "D:\MESSAGE\AUTOMSG.MSG" are retrieved.


    #define INCL_DOSMISC   /* Miscellaneous values */
    #include <os2.h>
    #include <stdio.h>

    UCHAR    ucBufferArea[20];  /* Buffer for the returned list  */
    ULONG    ulBufferLength;    /* Length of the buffer area     */
    UCHAR    ucFileName[40];    /* Message file path-name string */
    ULONG    ulDataLength;      /* Length of the returned data   */
    APIRET   ulrc;              /* Return code                   */

    strcpy(ucFileName,
           "D:\\MESSAGE\\AUTOMSG.MSG");
           /* Path name of message file */

    ulBufferLength = 20;                           /* Length of buffer area     */

    ulrc = DosQueryMessageCp(ucBufferArea,
                             ulBufferLength,
                             ucFileName,
                             &ulDataLength);

    if (ulrc != 0) {
        printf("DosQueryMessageCp error: return code = %ld",
               ulrc);
        return;
    }


On successful return, the BufferArea buffer contains a set of information concerning the code page identifiers and language identifiers that are associated with the message file.