HP 3000 Manuals

Message Catalogs:Programmer's Guide

Accessing the CM Error Message Catalog 

The CM error message catalog, CATALOG.PUB.SYS, is read with the
GENMESSAGE intrinsic; the catalog file 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.SYS must be opened as a permanent ASCII file with buffering
inhibited and multirecord mode (PERMANENT (OLD), ASCII, NOBUF, MULTI).
You use HPFOPEN to open the catalog.  HPFOPEN returns the file number for
CATALOG.PUB.SYS. This file number is a required parameter for the
GENMESSAGE intrinsic.

The HPFOPEN intrinsic is the most efficient way to open a file for
access.  When using the HPFOPEN intrinsic, the parameters are:

  domain option (item#3) = 1 (PERMANENT)

  multirecord option (item#15) = 1 (MULTI)

  inhibit buffering option (item#46) = 1 (NOBUF)

  ASCII/Binary option (item#53) = 1 (ASCII)

To open CATALOG with HPFOPEN:

          const   {These are the item numbers for HPFOPEN}
            Designator   = 2;
            Domain       = 3:
            MultiRec     = 15;
            Buffering    = 46;
            ASCII/Binary = 53;

          var  {These are the parameters and options}
               { for HPFOPEN                        }
            Filenum      : INTEGER;   {Returned by HPFOPEN}
            Status       : INTEGER;   {Returned by HPFOPEN}
            FileName     : packed array [1..20] of CHAR;
            Perm         : INTEGER;
            On           : INTEGER;
            Inhibited    : INTEGER;
            ASCII        : 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 file 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.

For detailed information about the HPFOPEN intrinsic, refer to the MPE XL
Intrinsics Reference Manual (32650-90028).

Reading Messages With GENMESSAGE 

Use the GENMESSAGE intrinsic to read messages from CATALOG.PUB.SYS. Call
GENMESSAGE with the file number for CATALOG.PUB.SYS, a set number, a
message number, and any values to be substituted in the message.

When you use GENMESSAGE to read messages, the message facility fetches
the message from a message catalog, inserts parameters (if specified),
and then routes the message to a file or returns the message in a buffer
to the calling program.  The syntax for the GENMESSAGE intrinsic is:
  msglength := GENMESSAGE (filenum, setnum, msgnum, buffer, 
  buffersize, parmask, param1, param2, param3, param4, 
  param5, msgdestination, errornum);

The parameters param1 ...  param5 are used to substitute values in the
message at run time.

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, such as a ldev number or a
session name.  Parameters are passed to the message with the param1,
param2, param3, param4, and param5 parameters in the GENMESSAGE intrinsic
and are inserted in the message wherever a "!" is found.  Parameters are
inserted in the following order:  param1 substitutes for the leftmost "!"
in the message, param2 for the next !  to the right, and so forth.  If
param(n) is present, param(n-1) must be present (that is, you cannot
specify param3 unless param1 and param2 are specified).

To specify the format of each of your parameters, use the parmask 
parameter of the GENMESSAGE intrinsic.

The parmask parameter indicates the format of each of the five
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.

010              Parameter is a 32-bit signed integer by reference.

011              Parameter is ignored.

The positions of the bit values given above, indicate which substitution
parameter's data type is being specified.  For example, parmask= OCTAL
('13333') denotes that the first parameter is passed as a 16-bit signed
integer, and all other parameters are ignored.


NOTE  If a substitutional parameter (param1 through param5) is not
      specified, the value in the parmask for its format is ignored.


Message Output.  Messages may be output to a buffer or a file.  If you
output to a buffer, you specify the buffer and a buffer size with the
buffer and the buffersize parameters.  To output to a file, you specify
the file number and message the buffersize parameters.  To output to
$STDLIST, use a file number of 0 (zero).

To output message #210 from set #1 to $STDLIST, use GENMESSAGE to access
CATALOG.PUB.SYS in the following manner:

          var
             Msglength  : SHORTINT; {Returns length of message}
             Filenum    : SHORTINT; {Value assigned by HPFOPEN}
             Setnum     : SHORTINT;
             Msgnum     : SHORTINT;
             Parmask    : SHORTINT;
             Param1     : INTEGER;
             Msgdestination  : SHORTINT;
             Errornum   : SHORTINT;

             Setnum := 1;
             Msgnum := 201;
             Parmask := OCTAL ('13333');
             Param1 := 95;
             Msglength := GENMESSAGE (Filenum, Setnum, Msgnum,,,
                Parmask, Param1,,,,, Msgdestingaion, Errornum);

For detailed information about the GENMESSAGE intrinsic, refer to the MPE
XL 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
             Filenum      : INTEGER;  {Returned by HPFOPEN}
             Disposition  : SHORTINT;
             Securitycode : SHORTINT;

             Disposition := 0;   {No changes in domain }
                                 {or disc space}
             Securitycode := 0;  {Unrestricted access}
             FCLOSE (Filenum, Disposition, Securitycode)

For detailed information about the FCLOSE intrinsic, refer to the MPE XL
Intrinsics Reference Manual (32650-90028).

Example of Accessing the CM Error Message Catalog 

The following listing is a Pascal 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
             .
             .
             .
          201 SYSTEM LOG FILE NUMBER ! IS ON

     Program CM_MSGCAT (input,output);
     {This program reads a message from CATALOG.PUB.SYS   }
     {and writes it to $STDLIST                           }

     var
       Filenum      : INTEGER;

     Procedure HPFOPEN       ; intrinsic;
     Function GENMESSAGE: SHORTINT; intrinsic;
     Procedure FCLOSE             ; intrinsic;

     Procedure OPEN_CATALOG;
     {This procedure opens CATALOG.PUB.SYS }

     const   {These are the item numbers for HPFOPEN}
       Designator   = 2;
       Domain       = 3;
       MultiRec     = 15;
       Buffering    = 46;
       ASCII_Binary = 53;

     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.SYS%';
       Perm := 1;
       On := 1;
       Inhibited := 1;
       ASCII_file := 1;
       HPFOPEN (Filenum, Status, Designator, FileName,
          Domain, Perm, MultiRec, On, Buffering, Inhibited,
          ASCII_Binary, ASCII_file);

       {Call procedure to check Status for errors}
     end;

     Procedure READ_CATALOG;
     {This procedure reads and outputs a message from }
     {CATALOG.PUB.SYS and outputs it to $STDLIST     }

     var
        msglength  : SHORTINT;  {Returns length of message}
        Setnum     : SHORTINT;
        Msgnum     : SHORTINT;
        Parmask    : SHORTINT;
        Param1     : integer;
        Msgdestination  : SHORTINT;
        Errornum   : SHORTINT;

     begin
        Setnum  := 1;
        Msgnum  := 201;
        Msgdestination := 0;
        Parmask := Octal('13333');
        Param1  := 95;
        msglength := GENMESSAGE (Filenum, Setnum, Msgnum,,,
           Parmask, Param1,,,,, Msgdestination, Errornum);

        {Call procedure to check Errornum for errors}
     end;

     Procedure CLOSE_CATALOG;
     {This procedure closes CATALOG.PUB.SYS}

     var
        Disposition  : SHORTINT;
        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

MPE/iX 5.0 Documentation