INIe (INI editor)

IBM License Agreement for INIE IF YOU DOWNLOAD OR USE THIS PROGRAM YOU AGREE TO THESE TERMS. International Business Machines corporation grants you a license to use the Program only in the country where you acquired it. The Program is copyrighted and licensed (not sold). We do not transfer title to the Program to you. You obtain no rights other that those granted you under this license. Under this license, you may: 1. use the Program on one or more machines at a time; 2. make copies of the Program for use or backup purposes within your Enterprise; and 3. modify the Program and merge it into another program. You must reproduce the copyright notice and any other legend of ownership on each copy or partial copy, of the Program. Except as expressly provided in the DAPTOOLS LIBRARY License Agreement (TOOLIC.TXT), you may NOT: 1. distribute the program in any manner, including through electronic bulletin board systems or other means; 2. sublicense, rent, lease, or assign the Program; and 3. reverse assemble, reverse compile, or otherwise translate the object code of the Program. We do not warrant that the Program is free from claims by a third party of copyright, patent, trademark, trade secret, or any other intellectual property infringement. Under no circumstances are we liable for any of the following: 1. third-party claims against you for losses or damages; 2. loss of, or damage to, your records or data; or 3. economic consequential damages (including lost profits or savings) or incidental damages, even if we are informed of their possibility. Some jurisdictions do no allow these limitations or exclusions, so they may not apply to you. We do not warrant uninterrupted or error free operation of the Program. We have no obligation to provide service, defect correction, or any maintenance for the Program. We have no obligation to supply any Program updates or enhancements to you even in such are or later become available. IF YOU DOWNLOAD OR USE THIS PROGRAM YOU AGREE TO THESE TERMS. THIS PROGRAM IS PROVIDED "AS IS" WITHOUT ANY WARRANTIES, EXPRESS OR IMPLIED, INCLUDING THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. Some jurisdictions do not allow the exclusion of implied warranties, so the above exclusion may not apply to you. You may terminate this license at any time. We may terminate this license if you fail to comply with any of its terms. In either event, you must destroy all your copies of the Program. You are responsible for the payment of any taxes resulting from this license. You may not sell, transfer, assign, or subcontract any of your rights or obligations under this license. Any atdttempt to do so is void. Neither of us may bring a legal action more than two years after the cause of action arose. If you acquired the Program in the United States, this license is governed by the laws of the State of New York. If you acquired the Program in Canada, this license is governed by the laws of the Province of Ontario. Otherwise, this license is governed by the laws of the country in which you acquired the Program. ----------------------------------------------------------------------------- (message.doc) (C)Copyright IBM Corporation, 1991, 1992, 1993 Brian E. Yoder This message facility allows you to put a set of messages in a single table for ease of translation. The message table may either be an array that is linked in with your program (perhaps via a shared library), or it may be contained in a separate file. The first method results in faster message look-up, while the second method allows you to change messages without relinking your program. You first need to create a 'message description file'. This text file contains all of your messages and the C language labels that you can use to reference them. You then use the 'mkmsg' program to create the C-language .h header file, .c source file, and/or the separate message file for use by your program. The use of mkmsg can be put into your makefile, so your programs can be automatically and correctly rebuilt whenever the message description file is changed. Why yet another message facility? AIX already provides its own message facility. However, the language translators must make changes to a C source file when translating messages. All of the C syntax rules apply. Forget a comma and the program may recompile ok but will not look up messages correctly. The syntax of the message description file used by this message facility is much easier to understand and far more forgiving of mistakes. The translators don't have to be C experts. This facility also allows you, the programmer, to maintain message labels and their text strings from one place: the message description file. The mkmsg utility will generate both the correct .h header file and the correct message text array from the same source. I've written many programs with message look-up arrays. I've spent lots of time updating message numbers and arrays and keeping them "in synch" with each other. I've been bitten by missing commas in string array initializers that compile correctly and are hard to detect. This is the facility that I wish I had all along. ----------------------------------------------------------------------- How your program obtains a message ----------------------------------------------------------------------- Programs that need to look up messages must include the header file that 'mkmsg' builds. The message labels are contained in an enumerated set. Your program source code references labels with meaningful names, while the look-up subroutines are passed numeric message indexes. To get the text string that is associated with a message, your program passes the label of the message to the appropriate look-up subroutine. If the messages are put into an array and linked with your program (or a shared library), your program uses the lookup subroutine whose name you specified in the message description file. The header file that mkmsg builds contains a prototype of the look-up subroutine. The C source file that mkmsg builds contains both the message array and the lookup subroutine. If the messages are put into a separate file, your program uses the getfmsg() subroutine. Your program must pass getfmsg() the name of the message file in addition to the message number. ----------------------------------------------------------------------- The 'mkmsg' program ----------------------------------------------------------------------- Usage: mkmsg [-h|d|c|f|r] msgdfile outfile [htext] The mkmsg program reads the message description file 'msgdfile' and builds the 'outfile', depending upon the flags. The message description file is a text file that describes the C language labels and text strings associated with a set of messages. If -h is specified, then 'outfile' will be a header file with the message labels contained in an enumerated variable. This is the default action. If -d is specified, then 'outfile' will be a header file with the message labels defined by #define statements. If a header file is needed for the OS/2 resource compiler, then use -d instead of -h. The resource compiler is not capable of processing an enum. If -c is specified, then 'outfile' will be a C language source file that contains the messages in an array and an externally available subroutine that is used to access the message array. If -f is specified, then 'outfile' will be a message file that can be accessed using the getfmsg() subroutine. If -r is specified, then 'outfile' will contain a text-string table. This file can be included in an OS/2 resource file using the 'rcinclude' statement. If no flag is specified, the default is to make a .h (header) file. For the -h, -d, and -c options: If htext is specified, then it is assumed to be the name of a text file that contains header commentary. The contents of this file are copied to the outfile before mkmsg adds anything else to the outfile. ----------------------------------------------------------------------- The 'fmsg' program ----------------------------------------------------------------------- Usage: fmsg msgfile code [code ...] The fsmg program reads the specified external message file 'msgfile'. This message file must have been created by the 'mkmsg -f' command. The program then displays the message that corresponds to each 'code' within the message file. The fmsg program displays an error message if it cannot open the message file or if the message file has the wrong version stored in it (see msg.h and this .doc file for the format of a message file). It gets the errors from an error message array stored in the fmsgtext.c file. This .c file is, of course, built by the mkmsg command (see the makefile for this directory). Therefore, the fmsg program contains an example of how to use this message facility. ----------------------------------------------------------------------- Message Description File ----------------------------------------------------------------------- A message description file is an ASCII text file. Blank lines are ignored. Lines whose first nonblank character is a '#' are assumed to contain only comments and are also ignored. Each of the other lines cotains a single statement. A statement consists of a series of one or more tokens. A token may be an equal sign '=', a sequence of contiguous non-whitespace characters, or a sequence characters enclosed by either single quotes or by double quotes. If a token begins with a '#', it and all remaining tokens on that line are assumed to be comments and are ignored. All tokens are case-sensitive. Each message description file must have the following types of statements, and in the order shown: enum = enum.name This statement must be the first statement. When generating a header file (when the -h flag is specified), all message labels are stored in an enumerated set. The enum identifier is set to 'enum.name'. lookup = subr.name This statement must be the second statement. It specifies the name of the message array look-up subroutine. The .c source file (when the -c flag is specified) will contain the externally-available subroutine named 'subr.name'. This subroutine obtains a message string based upon a message codes. The .h header file (when the -h flag is specified) will contain the function prototype for this message look-up subroutine. If you are putting messages into an external file or resource file and have no plans to build a .c file that contains a message array and lookup subroutine, then you do not need a lookup subroutine. In this case, specify a null string as the name of the lookup subroutine: lookup = "" msg label.name = "message string" At least one of these statements is required. All of the 'msg' statements must follow the 'enum' and 'lookup' statements. A 'msg' statement defines a message label and its associated text string. Programs that need to get a message's text string will pass the message's 'label.name' to the lookup subroutine. The last message string is also the one that is returned whenever a program passes to a look-up function a message index that is negative or larger than the last message's index. See the "testmsg.m" file for a working example of a message description file. ----------------------------------------------------------------------- .h Header File Format ----------------------------------------------------------------------- The mkmsg program produces this file when the -h flag is specified. In each case, 'N' is the message number: enum enum.name { / * N * / label.name , / * N * / label.name , / * N * / label.name , . . . / * N * / label.name }; char *subr.name ( unsigned int ); The integer 'N' (message number) that is associated with each label is calculated by mkmsg and put into a comment for reference purposes. Message numbers always start at zero and increase in value by one each time. Therefore, both mkmsg and the C compiler will assign the same number to each enumerated message label. If a look-up subroutine was defined, its prototype is generated. You include this file in each program module that needs to access the messages by the appropriate 'label.name'. If the messages are to be stored in a C-language array that is linked with the program, then you can look up a message by calling subr.name(). If the messages are stored in an external file, you can look up a message by calling the getfmsg() subroutine. ----------------------------------------------------------------------- .c C Source File Format ----------------------------------------------------------------------- The mkmsg program produces this file when the -c flag is specified, where 'N' is the message number: #define MsgCount N / * Number of messages * / static char *Msg[] = { / * N * / "message string" , / * N * / "message string" , / * N * / "message string" , . . . . / * N * / "message string" }; / * Message Lookup Subroutine * / char *subrname ( unsigned int msgnum ) { ... body of subroutine ... } You normally compile this file and link the object with your program. Your program calls the look-up subroutine named 'subr.name' to get a pointer to a message. The message lookup subroutine always returns a non-NULL pointer. It returns either a pointer to the message string whose index is 'msgnum', or a pointer to the last message in the array if 'msgnum' is out of range. ----------------------------------------------------------------------- Message File Format ----------------------------------------------------------------------- The mkmsg program produces this file when the -f flag is specified: (1) Header. (N) Offsets: One offset for each message. (N) Strings: One string for each message. The header of the file is defined by the FMSG_HEADER structure type. It contains a version string and a count of the number of messages in the file. A set of contiguous offsets follow, one for each message. Each offset is defined by the FMSG_OFFSET structure type. Each contains the offset within the file of the message's corresponding text string. Finally, a set of contiguous null-terminated strings follow, one string for each message. This file is kept separate from your program's executable text. Your programs use the getfmsg() subroutine to look up messages in this file. Your program passes to getfmsg() the name of the message file and the message number. It takes longer for your programs to access messages when they are stored in a separate file than when they are stored in an array that is linked with your program. However, it can be easier to translate messages when they are separate from a program's executable and don't require access to your program's source code and build environment.