Message Catalogs:Programmer's Guide 900 Series HP 3000 Computers ABCDE HP Part No. 32650-90021 Printed in U.S.A.
Copyright c 1987,1988,1989,1990,1991,1992,1993,1994 by Hewlett-Packard Company The information contained in this document is subject to change without notice. Hewlett-Packard makes no warranty of any kind with regard to this material, including, but not limited to, the implied warranties of merchantability or tness for a particular purpose.
Printing History The following table lists the printings of this document, together with the respective release dates for each edition. The software version indicates the version of the software product at the time this document was issued. Many product releases do not require changes to the document. Therefore, do not expect a one-to-one correspondence between product releases and document editions. Edition Date Software Version First Edition November 1987 A.01.
Documentation Map iv
Preface MPE/iX, Multiprogramming Executive with Integrated POSIX, is the latest in a series of forward-compatible operating systems for the HP 3000 line of computers. In HP documentation and in talking with HP 3000 users, you will encounter references to MPE XL, the direct predecessor of MPE/iX. MPE/iX is a superset of MPE XL.
This manual is intended for use by programmers that are developing or maintaining a message catalog. It assumes knowledge of general programming and MPE concepts. Organization of This Manual This manual is structured as follows: Chapter 1 Introduction contains an introduction to message macilities on MPE/iX.
Conventions UPPERCASE In a syntax statement, commands and keywords are shown in uppercase characters. The characters must be entered in the order shown; however, you can enter the characters in either uppercase or lowercase.
Conventions (continued) [ ... ] In a syntax statement, horizontal ellipses enclosed in brackets indicate that you can repeatedly select the element(s) that appear within the immediately preceding pair of brackets or braces. In the example below, you can select parameter zero or more times. Each instance of parameter must be preceded by a comma: [,parameter][...
Contents 1. Introduction When to Use Message Catalogs Application Message Facility . GENCAT Utility . . . . . Catalog Intrinsics . . . . . User Message Catalogs . . System Message Facility . . . HELP Facility . . . . . . . Program Examples . . . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4. Modifying the Application Message Catalog Overview . . . . . . . . . . . . . . . Creating an Expanded Source File . . . . Modifying a Source File . . . . . . . . . Editing the Source File . . . . . . . . Merging Source and Maintenance Files . Merging by Line Numbers . . . . . . . Modifying a Record . . . . . . . . . Adding a Record . . . . . . . . . . Deleting a Record . . . . . . . . . . Example . . . . . . . . . . . . . . Merging by Set and Message Number . . Adding a Set . . . . . . . . . . . .
6. Creating Your Own HELP Facility Overview . . . . . . . . . . . Creating the Source File . . . . . Keyword Commands . . . . . File Commands . . . . . . . . Example Source File . . . . . Formatting the Source File . . . . Accessing the HELP Facility . . . Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figures 1-1. 2-1. 3-1. 4-1. 4-2. 4-3. 4-4. 5-1. 5-2. 5-3. 6-1. Message Catalog Access . . . . . . . . . . . . . . . . . . . . . . . Formatting a Source File With GENCAT . . . . . . . . . . . . . . . Accessing an Application Message Catalog . . . . . . . . . . . . . . . Merging Files to Create a New Source (Creating a Collision File is Optional) Expanding a GENCAT Formatted Catalog . . . . . . . . . . . . . . . Creating a New Source . . . . . . . . . . . . . . . . . . . . . . .
1 Introduction Message catalogs are les that contain informative user messages to be output from applications. These messages are numbered and grouped into numbered sets. The messages are accessed with their set and message numbers by your application program and output to users. This manual tells you how to create, access, and modify your own message catalogs, access system message catalogs, and create your own HELP facility. It takes you step-by-step through the steps needed to work with message catalogs.
Figure 1-1. Message Catalog Access MPE/iX supports three message facilities: Application Message Facility System Message Facility HELP Facility Each is used for a di erent cataloging task. Application Message Facility The Application Message Facility contains: GENCAT.PUB.SYS utility program Catalog intrinsics User message catalogs GENCAT Utility GENCAT is a menu-driven program that performs various operations on message catalogs.
Catalog Intrinsics Three intrinsics are available for accessing application message catalogs: CATOPEN, CATREAD, and CATCLOSE. These intrinsics open the formatted catalog, read and output the messages, and close the catalog. Use of these intrinsics is discussed in Chapter 3. User Message Catalogs You create your own catalogs by organizing your numbered messages into numbered sets and then formatting them with GENCAT.
HELP Facility The HELP Facility is a special type of message facility. It contains CICAT.PUB.SYS, the default HELP subsystem catalog that provides users with online help for MPE/iX. CICAT.PUB.SYS can be equated to a your HELP le. HELP catalogs are formatted with the MAKECAT utility and accessed directly by users. The HELP Facility provides a user interface that allow messages to be accessed very di erently from the user's standpoint.
2 Creating an Application Message Catalog Application messages catalogs are message catalogs that you build, access, and modify. These catalogs contain messages that you output to users from your applications. Application message catalogs are used to organize messages from an application program. These messages may be grouped by type of message (prompt, error message, etc.
Introducing the GENCAT Utility GENCAT.PUB.SYS is the program that formats, incorporates your modi cations, and unformats (expands) the message catalog les. GENCAT is menu-driven with HELP available in each step. GENCAT has an online HELP facility. To access HELP, enter the index number for HELP from the menu, or a \?" in response to any prompt that does not have a menu selection for HELP. Explanations of GENCAT error messages are given in Appendix A.
If GENCAT encounters an error while formatting, expanding, or modifying a catalog, it will abort the job. For information on formatting with GENCAT, refer to the end of this chapter. For information about creating jobs, refer to the MPE/iX Commands Reference Manual (32650-90003). GENCAT JCWs GENCAT sets one of three Job Control Words (JCWs) at the conclusion of a formatting, maintenance, or expansion operation: GCFORMAT, GCMAINT, or GCEXPAND, respectively.
$SET Records A $SET record initiates a logical grouping of messages. Sets break the catalog into manageable segments containing logical groupings of messages (for example, one set of messages for prompts, one set for instructions, one set for error messages). Each set is identi ed by a set number. Set numbers: Identify each set. Must be in ascending sequence and unique within the catalog that contains them. Do not need to be consecutive. Must be greater than 0 and less than 256. May have leading zeros.
exception is made if one of two special characters, \%" or \&," follow the message number. These characters will not be replaced by a blank. Their meaning is explained in the following section. An example of message records, set directives, and comments follows: $SET 1 Prompts 1 ENTER FIRST NAME 2 ENTER LAST NAME $ $ $set 2 Error Messages 1 NAME NOT ON DATA BASE 2 ILLEGAL INPUT Special Characters Special characters are used to control the format and content of messages when the messages are output.
Parameter Substitution Parameter substitutions are used to insert values that will be known at run time into your messages. An exclamation mark (!) is used within a message to indicate where the parameter is to be inserted. ! is treated as a special character; if you want to use an exclamation point in your message, use the tilde before it. You are allowed up to ve parameter substitutions in each message. The parameters that are substituted are strings with an ASCII null as the last character.
Example Source Catalog Notice the $SET numbers, message numbers, message comments, and the use of blanks in the example source catalog listed below: $SET 1 Prompts 1 ENTER FIRST NAME 2 ENTER LAST NAME $ $ $set 2 Error Messages 1 NAME NOT ON DATA BASE 2 ILLEGAL INPUT 3 AN ERROR OCCURRED DURING THE LOADING % OF THE DATA BASE. 98 THE NUMBER OF FILES & DOES NOT MATCH THE & SYSTEM'S CALCULATIONS.
Formatting a Source File You must format the source catalogs so the catalog intrinsics can access them. GENCAT formatted message les are binary and cannot be edited. Formatting compacts the les and creates a directory, which saves disc space and reduces access time. As shown in Figure 2-1, GENCAT creates a formatted catalog from a source le. Figure 2-1. Formatting a Source File With GENCAT During the formatting process, GENCAT veri es that: All directives are legal and used correctly.
>>3 ENTER NAME OF SOURCE FILE TO BE FORMATTED >>SOURCE FORMATTING... ENTER NAME FOR NEW FORMATTED FILE >>FORMAT TOTAL NUMBER OF SET FORMATTED = 3 TOTAL NUMBER OF MESSAGES FORMATTED = 8 FORMATTING SUCCESSFUL The formatted catalog given above is used in further examples in this manual and denoted by the le name, FORMAT.
3 Accessing Application Message Catalogs After you create a formatted message catalog with the GENCAT utility, you access the formatted catalog from your application with system intrinsics, as shown in Figure 3-1. To read and output the messages, you must rst open the catalog. Messages may be output to a le or a bu er. If run-time parameters are speci ed, they are substituted when messages are output. Before your program nishes, you must close the catalog.
Opening a Catalog The CATOPEN intrinsic opens an application message catalog. The syntax for the CATOPEN intrinsic is: catindex := CATOPEN (formaldesignator, catstatus); The catindex is a value returned by the CATREAD intrinsic used to identify the message catalog being accessed. This number is not the same as the le number. The formaldesignator parameter contains the string that identi es the catalog le to open; catstatus returns the error number. It tells if the call is successful.
Parameter Substitution Parameters may be inserted into the message read from the catalog. Parameter substitution is used when a message output contains information only known at run time. The parameters are passed to the message with the param1 , param2, param3, param4, and param5 parameters in the CATREAD intrinsic and are inserted in the message wherever an \!" is found.
Closing a Catalog CATCLOSE closes the message catalog speci ed by the catindex parameter. The syntax for the CATCLOSE intrinsic is: CATCLOSE(catindex, catstatus) The catindex parameter contains the value returned by the CATOPEN intrinsic that identi es the message catalog. The rst element of catstatus returns the error number that tells if the call was successful. Closing the example catalog using the CATCLOSE intrinsic is done as follows: var Catstatus Catindex : packed array [1..
Catstatus : packed array [1..2] of CHAR; Function CATOPEN: INTEGER; intrinsic; Function CATREAD: SHORTINT; intrinsic; Procedure CATCLOSE; intrinsic; Procedure OPEN_A_CATALOG; {This procedure opens FORMAT} var Designator : packed array [1..
Procedure CLOSE_A_CATALOG; {This procedure closes FORMAT} begin CATCLOSE (Catindex, Catstatus); {Call procedure to check Catstatus} end; begin {main} OPEN_A_CATALOG; READ_A_CATALOG; CLOSE_A_CATALOG; end. When this example is run, the output is as follows: ENTER FIRST NAME MARY INPUT FROM MARY ON TERMINAL NUMBER 3 Summary After you have formatted your catalog, you access it with your program. This access is done using the ''CATOPEN, CATREAD, and CATCLOSE intrinsics.
4 Modifying the Application Message Catalog You modify a message catalog by adding, replacing, and deleting set, message, and comment records in the source le. This modi cation is done by merging two les, an old source le, and the maintenance le to create a new source le, as shown in Figure 4-1. The old source le is the catalog you originally created and input to the GENCAT utility to be formatted. The maintenance le contains the changes that will be made to the old source le.
Figure 4-1. Merging Files to Create a New Source (Creating a Collision File is Optional) Creating an Expanded Source File To modify your application message catalog, you must have a source le. If you do not have access to your original source le, re-create a source le by expanding the formatted catalog with the GENCAT utility, as shown in Figure 4-2. The expanded source le doesn't have the comments that were included in the original, but the rest of the content in the catalog is the same.
HP32414A.02.01 GENCAT/3000 (C) HEWLETT-PACKARD., 1983 ENTER INDEX OF 0. EXIT. 1. HELP. 2. MODIFY 3. FORMAT 4. EXPAND DESIRED FUNCTION SOURCE CATALOG. SOURCE INTO FORMATTED CATALOG. FORMATTED CATALOG INTO SOURCE. >>4 ENTER NAME OF FORMATTED CATALOG TO EXPAND >>FORMAT ENTER NAME OF NEW SOURCE FILE >>SOURCE EXPANDING...
Merging Source and Maintenance Files You use GENCAT to merge source and maintenance les. You can use either of two di erent merging methods: Merging by Line Number Merging by Set and Message Numbers Each method requires a di erent type of maintenance le. Creating each type of maintenance le is described below, and examples are given. For examples of merging les, the example source catalog created earlier in this manual is used. The example catalog is listed below.
Modifying a Record If the maintenance le's line number is common to the source le's, the source's record is overwritten by the maintenance record. Adding a Record If the line number in the maintenance le does not exist in the source, the record represented by that line number from the maintenance le is added to the source at that line number. Make sure you don't have any blank lines in your maintenance le; GENCAT will merge them into your source le and when you try to format it, GENCAT will abort.
Merging by Set and Message Number This method is usually the easiest method of modifying your source. When the source is merged with a maintenance le by set and message numbers, you have rollback capability and an easy way to build a maintenance le. When GENCAT reads a $SET record from the maintenance le, all records following the $SET record are considered to be message records or comment records within that set until GENCAT reads another $SET record or exhausts the maintenance le.
Comment Records Comment records cannot be added, deleted, or modi ed when you merge by set and message number. You must merge by line number to perform operations on comment records. All comment lines included in a maintenance le for message and set number merging are ignored by GENCAT. Example Below is an example of merging by set and message numbers. The maintenance le that follows, is merged with the example source catalog created in Chapter 2 and repeated at the beginning of this chapter.
Figure 4-3. Creating a New Source The dialog listed below is an example of merging source and maintenance les. Note that the method of merging you specify depends on the type of maintenance le you created. To use GENCAT to modify your source catalog, enter: :RUN GENCAT.PUB.SYS HP32414A.02.01 GENCAT/3000 (C) HEWLETT-PACKARD., 1983 ENTER INDEX OF DESIRED FUNCTION 0. 1. 2. 3. 4. EXT. HELP. MODIFY SOURCE CATALOG. FORMAT SOURCE INTO FORMATTED CATALOG. EXPAND FORMATTED CATALOG INTO SOURCE.
>>2 or >>3 Entering an \0" or 4Return5 aborts the maintenance function and returns to the main menu. You have the option of saving all the modi cations resulting from the merge in a collision le. SAVE COLLISIONS? ENTER "YES" OR "NO" >>YES ENTER NAME OF COLLISION FILE >>COLISION If the name of an existing le is entered, the prompt is repeated. A 4Return5 continues the merging without saving the collisions.
Figure 4-4. Rolling Back to the Old Source Catalog Summary To modify a message catalog, you modify your source le then reformat the new source before accessing the message catalog. To create a new source, merge the maintenance les against the old source by line number, or set and message number. A collision le may be created during the merging operation. When the collision le is used as a maintenance le on the new source, the old source is re-created.
5 Accessing System Error Messages The System Message Facility consists of two error message catalogs. The message catalogs, CATALOG.PUB.SYS and SYSCAT.PUB.SYS , contain Compatibility Mode (CM) and Native Mode (NM) error messages. You can access these messages, but cannot modify them. To output error messages without creating your own message catalog, use system error messages. When to Use System Error Messages Only if you prefer to use system error messages should you consider accessing them.
Both CATALOG.PUB.SYS and SYSCAT.PUB.SYS may be accessed from Native Mode. Figure 5-1 shows the catalogs and the intrinsics that access them. Figure 5-1. Accessing System Error Messages Format of a Message Catalog Although the two system error message catalogs contain di erent sets of messages, their format is the same. The messages are numbered and grouped into numbered sets. The sets are logical divisions of messages.
$FIRST LINE, AND THE SECOND LINE IS "HP32002" 35!% HP32002B.00.! . . . 276 LDEV # FOR "!" ON ! (NUM)! $ $SET 2 CIERROR MESSAGES 82 STREAM FACILITY NOT ENABLED: SEE OPERATOR.(CIERR 82) 200 MORE THAN 30 PARAMETERS TO BUILD COMMAND.(CIERR 200) . . . Directives and Special Characters Directives and special characters are not output to users, but they are important factors in the unformatted message catalog. A directive begins in column one and denotes the beginning of a set, a comment, or a message.
Accessing the CM Error Message Catalog The CM error message catalog, CATALOG.PUB.SYS, is read with the GENMESSAGE intrinsic; the catalog le is opened with HPFOPEN and closed with FCLOSE. Accessing any catalog that was formatted with MAKECAT.PUB.SYS is similar to accessing CATALOG.PUB.SYS. Figure 5-2 shows how intrinsics are used to access the CM error message catalog. Figure 5-2. Accessing CATALOG.PUB.SYS Opening the CM Error Message Catalog CATALOG.PUB.
FileName Perm On Inhibited ASCII : : : : : packed array [1..20] of CHAR; INTEGER; INTEGER; INTEGER; INTEGER; FileName := '%CATALOG.PUB.SYS%'; Perm := 1; On := 1; Inhibited := 1; ASCII := 1; HPFOPEN (Filenum, Status, Designator, FileName, Domain, Perm, MultiRec, On, Buffering, Inhibited, ASCII/Binary, ASCII); Filenum returns the le number for CATALOG.PUB.SYS; Status returns a value that indicates if the intrinsic call was successful. If it was not successful, Status gives you information about the error.
The parmask parameter indicates the format of each of the ve substitution parameters. Three bits describe the data type for each of these parameters. With bit zero being the leftmost bit, the value of parmask is represented as follows: Bits (0:3) param1 Bits (3:3) param2 Bits (6:3) param3 Bits (9:3) param4 Bits (12:3) param5 These bit values are as follows: 000 Parameter is a string that is terminated by an ASCII null (0). 001 Parameter is a 16-bit signed integer.
For detailed information about the GENMESSAGE intrinsic, refer to the MPE/iX Intrinsics Reference Manual (32650-90028). Closing the CM Error Message Catalog To close the CM error message catalog, use the FCLOSE intrinsic. Close the catalog with the same domain as when opened (PERM) with unrestricted access.
var {These are the parameters for HPFOPEN} Status : INTEGER; {Returned by HPFOPEN} FileName : packed array [1..20] of char; Perm : INTEGER; On : INTEGER; Inhibited : INTEGER; ASCII_file : INTEGER; begin FileName := '%CATALOG.PUB.
Securitycode : SHORTINT; begin Disposition := 0; {No changes in domain } {or disc space} Securitycode := 0; {Unrestricted access} FCLOSE (Filenum, Disposition, Securitycode); {Call procedure to check Condition Code for errors} end; begin {main} OPEN_CATALOG; READ_CATALOG; CLOSE_CATALOG; end. When this program is executed, the output is: SYSTEM LOG FILE NUMBER 95 IS ON Accessing the NM Error Message Catalog To open, read, and close the NM error message catalog, SYSCAT.PUB.
Opening the NM Error Message Catalog The CATOPEN intrinsic opens the NM error message catalog. The syntax for CATOPEN is: catindex := CATOPEN (formaldesignator, catstatus); The catindex is an index used to identify the message catalog being accessed. This number is not the same as a le number. The formaldesignator parameter contains a string that identi es the catalog le to open; catstatus returns the error number.
To output message #8 from set #221 to $STDLIST, a call to the CATREAD intrinsic is done as follows: var Catindex Catstatus Setnum Msgnum Parm1 Dumy Msgdest Msglength : : : : : : : : INTEGER; packed array [1..
Example of Accessing the NM Error Message Catalog The following listing is a Pascal program that inserts the value 42 into message #8 in set #201 in the message catalog SYSCAT.PUB.SYS. The message is output to $STDLIST. The accessed portion of the message catalog is: $SET 201 . . . 008 The value passed for parameter #! is invalid. Program NM_MSGCAT (input, output); var Catindex : INTEGER; Catstatus : packed array [1..
{Append ASCII null} Msgdest := 0; {Output to $STDLIST} Msglength := CATREAD (Catindex, Setnum, Msgnum, Catstatus,,, Parm1,,,,, Msgdest); {Call procedure to check Catstatus for errors} end; Procedure CLOSE_SYSCAT; {This procedure closes SYSCAT.PUB.SYS} begin CATCLOSE (Catindex, Catstatus); {Call procedure to check Catstatus for errors} end; begin {main} OPEN_SYSCAT; READ_SYSCAT; CLOSE_SYSCAT; end. When this program is executed, the output is: The value passed for parameter #42 is invalid.
6 Creating Your Own HELP Facility A HELP facility is a help catalog and the user interface to that catalog. You create your own HELP facility by developing a help catalog and allowing users to access it via the MPE/iX HELP user interface. You are probably already familiar with the MPE/iX HELP user interface; you use it when you access the MPE/iX HELP facility. HELP facilities provide extra information to the user by outputting explanatory text in response to keyword input.
Keyword Commands Keywords identify the set of text that is output when a keyword is input to the HELP facility. For example, if the keyword HELLO is input to the MPE/iX HELP Facility, a description of the :HELLO command, and an explanation of its syntax, operation, and parameters is output. There are three keyword commands: \ENTRY=entryname comment , where entryname is a major divisional entry point in your HELP facility and comment is optional text about the entry. The entryname must be in upper case.
File Commands The other commands in the source le specify information that is not output to users. The le commands are: \ALL indicates the end of the source le. It is required. \STOPHELP denotes the start of a section in the le that will not be shown when the facility is accessed. \STARTHELP denotes the point at which the HELP facility resumes displaying help information. \SUBSET, put at the beginning of the le, allows all text between \STOPHELP and \STARTHELP to be excluded from the formatted catalog.
** FILE ERROR ON CATALOG (100) PROGRAM TERMINATED IN ERROR STATE. (CIERR 976) Accessing the HELP Facility To use your HELP facility you must disable the system HELP facility and assign your HELP le to CICAT.PUB.SYS. Create a UDC or User Command to perform these functions easily. To access your HELP facility with the command HELPME, use the following UDC: HELPME PARM1=" " PARM2= " " FILE CICAT.PUB.SYS = MYHELP HELP !PARM1 !PARM2 RESET CICAT.PUB.
A GENCAT Error Messages The following messages are returned from GENCAT: 1 2 3 4 MESSAGE FREAD ERROR ON SOURCE FILE. CAUSE ACTION A failure by FREAD when reading a source message catalog. Re-create the source message catalog. MESSAGE INPUT FILE MUST HAVE AT LEAST ONE RECORD. CAUSE ACTION The le has an EOF of zero (0). Place at least one record in the le. MESSAGE INPUT FILE MUST CONTAIN FIXED LENGTH RECORDS ONLY. CAUSE ACTION File does not have a xed record length.
6 8 9 MESSAGE SET NUMBERS MUST BE BETWEEN 1 AND 255. CAUSE ACTION A set number in a maintenance or source le is not greater than or equal to 1, or not less than or equal to 255. The set number may be negative or it may not be numeric. Change set number to a value between 1 and 255 inclusive. MESSAGE SET NUMBERS MUST BE IN ASCENDING SEQUENCE. CAUSE ACTION A set number is less than or equal to the previous set number in the source le.
12 MESSAGE MESSAGE CONTAINS NON-BLANK CHARACTER IMMEDIATELY FOLLOWING MESSAGE NUMBER. NON-BLANK CHARACTER ASSUMED TO BE A BLANK. CAUSE GENCAT detected a non-blank character immediately following the message number in a message. GENCAT replaces this character with a blank. Insert a blank between the message number and the message text. ACTION 13 MESSAGE EXPECTED ONE OF THE FOLLOWING INPUTS: 0, 1, 2, 3, 4, OR A RETURN.
17 MESSAGE EXPECTED A RESPONSE OF "YES" OR "NO" AS INPUT. CAUSE GENCAT requires a response of either YES, yes, NO, or no to the prompt of SAVE COLLISIONS?. Respond with YES, yes, NO, or no. ACTION 18 MESSAGE INPUT FILES MUST HAVE EQUAL RECORD SIZES FOR THIS FUNCTION. CAUSE Source and maintenance les must have equal record sizes if the maintenance le is to modify the source le. Create a maintenance le that has a record size equal to the record size of the source le.
23 MESSAGE SOURCE FILE MUST BE NUMBERED FOR LINE-NUMBER MERGES. CAUSE The source le is an unnumbered le. The source le must be a numbered le if it is to be used in a line-number merge. Number the source le if the le is to be used in a line-number merge. ACTION 24 MESSAGE SOURCE FILE CANNOT CONTAIN FORMS OF $EDIT. CAUSE During a line-number merge, GENCAT examines the source le for $EDIT and $EDIT VOID= constructs.
28 MESSAGE VALUE IN RIGHT BYTE OF KANJI CHARACTER IS INVALID. CAUSE Your message contains special escape sequences provided by HP that are used for research and development activities. These special escape sequences are not supported by Hewlett-Packard and Hewlett-Packard assumes no responsibility for their use. For messages 28 through 32, consult your Hewlett-Packard representative, or remove all occurrences of the form esc$ or ESC( from your message catalog.
B Catalogs Formatted With MAKECAT Some older catalogs have been built using the MAKECAT.PUB.SYS program. Although that method is not the most e cient or convenient, the catalogs may still be used under MPE XL. The following information is included for your convenience. If you are going to create a catalog, refer to Chapters 2-4 for information about application message catalogs. Creating a Formatted Catalog To create a catalog, you must rst create a source le and then format it with the MAKECAT utility.
Modifying the Message Catalog To modify your message catalog: 1. Text your source le into the editor 2. Make the desired changes. 3. Keep the le under a new name and exit the Editor 4. If SOURCE1 is the name of your new source le, enter: :FILE INPUT=SOURCE1 :RUN MAKECAT.PUB.SYS VALID MESSAGE CATALOG :SAVE CATALOG Converting MAKECAT Formatted Catalogs To increase the e ciency of message catalog accessing, you may want to convert your MAKECAT formatted message catalog to a GENCAT formatted catalog.
GENCAT MAKECAT Comparison To allow you to compare the GENCAT and the MAKECAT utilities, the di erences between GENCAT and MAKECAT are listed in tabular form below. Table B-1. MAKECAT/GENCAT Comparison FEATURES MAKECAT GENCAT The FOPEN, GENMESSAGE, and FCLOSE intrinsics open, access, and close formatted MAKECAT catalogs. CATOPEN, CATREAD , and CATCLOSE intrinsics open, Formatting Places an internal directory in the le's user labels. The le is formatted in place without creating a new le.
Table B-1. MAKECAT/GENCAT Comparison (Cont.) FEATURES MAKECAT GENCAT Output Saves the formatted le as a temporary le with the name CATALOG. GENCAT prompts the user for the name of the formatted le. The le is saved as a permanent le. Processing Formats more quickly than GENCAT. GENCAT veri es each message for correct parameter substitution characters. Manipulates two temporary les while formatting the source le.
C COBOL Progam Examples Example of Accessing an Application Message Catalog This example shows the access of the sample catalog called FORMAT (created in the Chapter 2); the source of this sample catalog (SOURCE) is listed below. $SET 1 Prompts 1 ENTER FIRST NAME 2 ENTER LAST NAME $ $ $set 2 Error Messages 1 NAME NOT ON DATA BASE 2 ILLEGAL INPUT 3 AN ERROR OCCURRED DURING THE LOADING % OF THE DATA BASE. 98 THE NUMBER OF FILES & DOES NOT MATCH THE & SYSTEM'S CALCULATIONS.
001019 77 MSGDESTINATION PIC S9(4) COMP. 001020* 001021 PROCEDURE DIVISION. 001022* 001023 START-OF-PROGRAM. 001024 PERFORM OPEN-A-CATATLOG. 001025 PERFORM READ-A-CATATLOG. 001026 PERFORM CLOSE-A-CATATLOG. 001027 STOP RUN. 001028* 001029 OPEN-A-CATATLOG. 001030 MOVE "FORMAT%" TO CAT-FILE. 001031 CALL INTRINSIC "CATOPEN" USING CAT-FILE, 001032 CAT-STATUS 001033 GIVING CAT-INDEX. 001034* 001035* CHECK CAT-STATUS FOR SUCCESS 001036* 001037 READ-A-CATATLOG. 001038 MOVE 1 TO SETNUM. 001039 MOVE 1 TO MSGNUM.
001071* CHECK CONDITION CODE FOR SUCCESS 001072* When this program is executed, the output is: ENTER FIRST NAME MARY INPUT FROM MARY ON TERMINAL NUMBER 3 Example of Accessing the CM Error Message Catalog The following listing is a COBOL program that inserts the value 95 into message number 201 in message set 1 in the message catalog CATALOG.PUB.SYS. The message is output to $STDLIST. The accessed portion of the message catalog is: $SET 1 . . .
003800* 003900 PROCEDURE DIVISION. 004000* 004100 START-OF-PROGRAM. 004200 PERFORM OPEN-CATALOG. 004300 PERFORM READ-CATALOG. 004400 PERFORM CLOSE-CATALOG. 004500 STOP RUN. 004600* 004700 OPEN-CATALOG. 004900 MOVE "%CATALOG.PUB.SYS%" TO HPFOPEN-FILE. 005000 MOVE 1 TO PERM-DOMAIN. 005100 MOVE 1 TO MULTIREC-ON. 005200 MOVE 1 TO INHIBITED. 005300 MOVE 1 TO ASCII-FILE.
008800 MOVE 0 TO CLOSE-SECURITY. 008900 CALL INTRINSIC "FCLOSE" USING FILE-NUM, 009000 DISPOSITION, 009100 CLOSE-SECURITY. 009200* 009300* CHECK CONDITION CODE FOR SUCCESS 009400* When this program is executed, the output is: SYSTEM LOG FILE NUMBER 92 IS ON Example of Accessing the NM Error Message Catalog The following listing is a COBOL program that inserts the value 42 into message number 8 in message set 201 in the message catalog SYSCAT.PUB.SYS. The message is output to $STDLIST.
001260* 001270 OPEN-SYSCAT. 001280 MOVE "SYSCAT.PUB.SYS%" TO CAT-FILE. 001290 CALL INTRINSIC "CATOPEN" USING CAT-FILE, 001300 CAT-STATUS 001310 GIVING CAT-INDEX. 001320* 001330* CHECK CAT-STATUS FOR SUCCESS 001340* 001350 READ-SYSCAT. 001360 MOVE 221 TO SETNUM. 001370 MOVE 8 TO MSGNUM. 001380 MOVE 0 TO MSGDESTINATION. 001390 MOVE "42" TO PARM-1.
D FORTRAN Progam Examples Example of Accessing an Application Message Catalog This example shows the access of the sample catalog called FORMAT (created in the Chapter 2); the source of this sample catalog (SOURCE) is listed below. $SET 1 Prompts 1 ENTER FIRST NAME 2 ENTER LAST NAME $ $ $set 2 Error Messages 1 NAME NOT ON DATA BASE 2 ILLEGAL INPUT 3 AN ERROR OCCURRED DURING THE LOADING % OF THE DATA BASE. 98 THE NUMBER OF FILES & DOES NOT MATCH THE & SYSTEM'S CALCULATIONS.
* * * 10 call READ_A_CATALOG (STATUS_RETURN) if (STATUS_RETURN) go to 20 print *,'READ_A_CATALOG Failed. call QUIT (2) Terminating.' 20 call CLOSE_A_CATALOG (STATUS_RETURN) if (STATUS_RETURN) go to 30 print *,'CLOSE_A_CATALOG Failed. Terminating' call QUIT (3) 30 stop end * ******************************************************* * subroutine OPEN_A_CATALOG (STATUS_RETURN) * system intrinsic CATOPEN * integer CATINDEX 2 ,CATSTATUS(2) * logical STATUS_RETURN * character DESIGNATOR*20 * STATUS_RETURN = .
* * * * logical STATUS_RETURN character PARM1*6 2 ,PARM2*2 STATUS_RETURN = .true. SETNUM = 1 MSGNUM = 1 MSGDEST = 0 MSGLENGTH = CATREAD (CATINDEX 2 ,SETNUM 3 ,MSGNUM 4 ,CATSTATUS,,, 5 ,,,,,MSGDEST) if (CATSTATUS(1) .ne. 0) STATUS_RETURN = .false. SETNUM = 13 MSGNUM = 400 read *,PARM1(1:5) write (PARM1(6:6),15) 0b PARM2(1:1) = '3' write (PARM2(2:2),15) 0b 15 format (r1) MSGLENGTH = CATREAD (CATINDEX 2 ,SETNUM 3 ,MSGNUM 4 ,CATSTATUS 5 ,,,PARM1 6 ,PARM2 7 ,,,,MSGDEST) if (CATSTATUS(1) .ne.
if (CATSTATUS(1) .ne. 0) STATUS_RETURN = .false. return end When this program is executed, the output is: ENTER FIRST NAME MARY INPUT FROM MARY ON TERMINAL NUMBER 3 Example of Accessing the CM Error Message Catalog The following listing is a FORTRAN program that inserts the value 95 into message number 201 in message set 1 in the message catalog CATALOG.PUB.SYS. The message is output to $STDLIST. The accessed portion of the message catalog is: $SET 1 . . .
* 2 3 if (STATUS_RETURN) go to 10 print *,'Open failed. Terminating.' call QUIT (1) * * * * * * Initialize variables to read message. 10 SETNUM MSGNUM DESTINATION PARMASK PARAM1 STATUS_RETURN * * * = = = = = = 1 201 0 13333B 95 .true. Generate the message, which will be displayed on $STDLIST 2 3 4 5 6 7 * * * ,FILENUM ,STATUS_RETURN) call READ_CATALOG (FILENUM ,SETNUM ,MSGNUM ,DESTINATION ,PARMASK ,PARAM1 ,STATUS_RETURN) if (STATUS_RETURN) go to 20 print *,'Read failed. Terminating.
* 2 3 4 5 6 7 8 9 A B logical STATUS_RETURN * character*20 FILENAME * * * Initialize variables DESIGNATOR = 2 DOMAIN = 3 MULTIREC = 15 BUFFERING = 46 ASCII_BINARY = 53 PERM = 1 ON = 1 INHIBITED = 1 ASCII_ENTITY = 1 STATUS_RETURN = .true.
* 6 7 system intrinsic GENMESSAGE * * * * * * * * * * * ,PARAM1 ,STATUS_RETURN) 2 3 4 5 6 integer*2 MSGLENGTH ,SETNUM ,MSGNUM ,PARMASK ,DESTINATION ,ERRORNUM 2 integer*4 PARAM1 ,FILENUM logical STATUS_RETURN Initialize variables STATUS_RETURN = .true. Generate the message MSGLENGTH = GENMESSAGE (FILENUM 2 ,SETNUM 3 ,MSGNUM 4 ,,,PARMASK 5 ,PARAM1 6 ,,,,,DESTINATION 7 ,ERRORNUM) if (ERRORNUM .ne. 0) STATUS_RETURN = .false.
* DISPOSITION = 0 SECURITYCODE = 0 STATUS_RETURN = .true. * * * * * Close file 2 3 call FCLOSE (FILENUM ,DISPOSITION ,SECURITYCODE) if (ccode()) 10,20,10 10 STATUS_RETURN = .false. 20 return end When this program is executed, the output is: SYSTEM LOG FILE NUMBER 92 IS ON Example of Accessing the NM Error Message Catalog The following listing is a FORTRAN program that inserts the value 42 into message number 8 in message set 201 in the message catalog SYSCAT.PUB.SYS.
* * * * * * 2 ,PARM1*3 DESIGNATOR = 'SYSCAT.PUB.SYS' call OPEN_SYSCAT (DESIGNATOR 2 ,CATINDEX 3 ,STATUS_RETURN) if (STATUS_RETURN) go to 10 print *,'OPEN_SYSCAT Failed. Terminating.' call QUIT (1) 10 SETNUM = 221 MSGNUM = 8 PARM1(1:2) = '42' write (PARM1(3:3),15) 0b 15 format (r1) MSGDEST = 0 2 3 4 5 6 call READ_SYSCAT (CATINDEX ,SETNUM ,MSGNUM ,PARM1 ,MSGDEST ,STATUS_RETURN) if (STATUS_RETURN) go to 20 print *,'READ_SYSCAT Failed. call QUIT (2) Terminating.
character DESIGNATOR*20 * STATUS_RETURN = .true. CATINDEX = CATOPEN (DESIGNATOR, CATSTATUS) if (CATSTATUS(1) .ne. 0) STATUS_RETURN = .false. * return end * ******************************************************* * subroutine READ_SYSCAT (CATINDEX 2 ,SETNUM 3 ,MSGNUM 4 ,PARM1 5 ,MSGDEST 6 ,STATUS_RETURN) * system intrinsic CATREAD * * * * * integer*2 SETNUM 2 ,MSGNUM 3 ,MSGDEST 4 ,MSGLENGTH 5 ,CATSTATUS(2) 2 integer*4 CATINDEX ,DUMY logical STATUS_RETURN character PARM1*3 STATUS_RETURN = .true.
* * * * integer*2 CATSTATUS(2) integer*4 CATINDEX logical STATUS_RETURN STATUS_RETURN = .true. call CATCLOSE (CATINDEX 2 ,CATSTATUS) if (CATSTATUS(1) .ne. 0) STATUS_RETURN = .false.
Index Special characters ! , 2-5, 5-3 $ , 5-3 % , 2-4, 2-5, 5-3 : , 2-4, 2-5, 5-3 ~ , 2-5, 5-3 A Accessing an application message catalog, FORTRAN example , D-1 an application message catalog, Pascal example , 3-4 application message catalog, COBOL example , C-1 application message catalogs , 3-1 syscat.pub.
CATCLOSE , 1-3, 3-4, 5-1, 5-11, 5-13 CATOPEN , 1-3, 3-2, 5-1, 5-10, 5-13 CATREAD , 1-3, 3-2, 5-1, 5-10, 5-13 Catalog Intrinsics , 1-3 Catalog, Message closing with CATCLOSE , 3-4, 5-11 closing with FCLOSE , 5-7 HELP , 1-4 opening with CATOPEN , 3-2, 5-10 opening with HPFOPEN , 5-4 reading messages with CATREAD , 3-2, 5-10 reading messages with GENMESSAGE , 5-5 CATALOG.PUB.SYS opening , 5-4 CATALOG.PUB.
expanding a GENCAT formatted catalog , 4-2 formatting a source le with GENCAT , 2-8 using GENCAT to merge source and maintenance les , 4-7 Directive $, comment reocrds , 2-3 $DELSET , 4-6 $EDIT , 4-5 $EDIT VOID = XXXXXXXX , 4-5 message numbers , 2-4 $SET , 2-3 Directive , 2-3, 5-3 Dividing a Message into Several Lines , 2-5 Drawbacks to Editing the Source File , 4-3 E $EDIT directive , 4-5 Editing the Source File , 4-3 $EDIT VOID = XXXXXXXX directive , 4-5 ENTRY HELP Command , 6-2 Error Messages GENCAT , 2-
with the GENCAT utility , 1-3 Formatting a Source File With GENCAT (Figure 2-1) , 2-8 FORTRAN Example accessing an application message catalog (MSGCAT) , D-1 accessing the CM message catalog (CM MSGCAT) , D-4 accessing the NM message catalog (NM MSGCAT) , D-8 G GCEXPAND GENCAT JCW , 2-3 GCFORMAT GENCAT JCW , 2-3 GCMAINT GENCAT JCW , 2-3 GENCAT, Utility collision le description , 2-2 conversion from MAKECAT formatted les , B-2 error messages , 2-2, A-1 example of expanding a formatted catalog , 4-2 example o
example , 4-5 modifying a record , 4-5 Line Number Merging , 4-4 Literal Character, ~ , 5-3 Literal Character,~ , 2-5 Localizing Catalogs naming , 2-7 Localizing Catalogs , 2-1 M MAINT example le , 2-2 example le used in example dialog , 4-7 Maintenance File example using merging by line number , 4-5 example using set and message number merge , 4-7 Maintenance File , 4-4 Maintenance File Description , 2-2 MAKECAT/GENCAT Comparison (Table B-1) , B-3 MAKECAT, Utility Conversion to GENCAT formatted les , B-2 c
Message File Format example , 5-2 Message Numbers , 2-4 Message Output , 3-3 Message Output to a File or Bu er , 5-6 Message Output to File or Bu er , 5-10 Message Record Addition line number merging , 4-5 Message Record Deletion line number merging , 4-5 Message Record Modi cation line number merging , 4-5 Message Records , 2-4 Messages reading with CATREAD , 5-10 reading with GENMESSAGE , 5-5 Modifying a comment record using line number merging , 4-5 a comment record using set and message number merge , 4
Error Checking , 1-4 FORTRAN , 1-4 FORTRAN, accessing an application message catalog , D-1 FORTRAN, accessing the CM message catalog , D-4 FORTRAN, accessing the NM message catalog , D-8 Pascal , 1-4 Pascal, accessing an application message catalog , 3-4 Pascal, accessing the CM error message catalog , 5-7 Pascal, accessing the NM message catalog , 5-12 Program Example , 1-4 Program MSGCAT COBOL , C-1 FORTRAN , D-1 Pascal , 3-4 Program NM MSGCAT COBOL , C-5 FORTRAN , D-8 Pascal , 5-12 R Reading Messages fro
n , 2-4, 2-5, 5-3 ~ , 2-5, 5-3 Special Character , 2-5, 5-3 STARTHELP HELP command , 6-3 STOPHELP HELP command , 6-3 SUBITEM HELP command , 6-2 SUBSET HELP command , 6-3 Substituting Run-Time Parameters , 2-6, 3-2, 5-5, 5-10 Subsystem Mode Access Help facility , 6-4 SYSCAT.PUB.SYS accessing , 5-9 SYSCAT.PUB.
