HP 3000 Manuals

Message Catalogs:Programmer's Guide

Accessing the NM Error Message Catalog 

To open, read, and close the NM error message catalog, SYSCAT.PUB.SYS,
use the catalog intrinsics:  CATOPEN, CATREAD, and CATCLOSE. Accessing
any catalog that was formatted with GENCAT.PUB.SYS is similar to
accessing SYSCAT.PUB.SYS. Figure 5.3 shows the intrinsics used to access
the NM system error catalog.


          Figure 5.3.  Accessing SYSCAT.PUB.SYS

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 file number.  The
formaldesignator parameter contains a string that identifies the catalog
file to open; catstatus returns the error number.  If the first element
of catstatus is zero, the intrinsic call was successful, if this element
is not zero, its value indicates the error that occurred.  Opening
SYSCAT.PUB.SYS is done as follows:

          var
            Designator : packed array [1..20] of CHAR;
            Catstatus  : packed array [1..2] of SHORTINT;
            Catindex   : INTEGER;

            Designator := 'SYSCAT.PUB.SYS ';
            Catindex := CATOPEN (Designator, Catstatus);

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

Reading Messages With CATREAD 

The CATREAD intrinsic reads the message specified by set and message
numbers from the catalog specified by catindex.  When you use CATREAD 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 CATREAD is:
  msglength :=CATREAD (catindex, setnum, msgnum, catstatus, 
  buffer, buffersize, parm1, parm2, parm3, parm4, 
  parm5, msgdest);

The parameters parm1 ...  parm5 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 an ldev number or a
session name.  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.  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).  Parameters are
passed as strings that must have the ASCII null character appended.

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 (returned from HPFOPEN) and message length with the
msgdest and the buffersize parameters.  To output to $STDLIST, use a file
number of 0 (zero).

To output message #8 from set #221 to $STDLIST, a call to the CATREAD
intrinsic is done as follows:

          var
            Catindex  : INTEGER;
            Catstatus : packed array [1..2] of SHORTINT;
            Setnum    : SHORTINT;
            Msgnum    : SHORTINT;
            Parm1     : STRING [ 3 ];
            Dumy      : INTEGER:
            Msgdest   : SHORTINT;
            Msglength : SHORTINT;

            Setnum := 221;
            Msgnum := 8;
            Parm1  := '42';
               {Append ASCII null}
            STRWRITE (Parm1, STRLEN(Parm1)+1, Dumy, CHR(0);
            Msgdest  := 0;  {Output to $STDLIST}
            Msglength := CATREAD (Catindex, Setnum, Msgnum,
               Catstatus,,, Parm1,,,,, Msgdest);

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

Closing the NM Error Message Catalog 

CATCLOSE closes the message catalog specified by the catindex parameter.
The syntax for CATCLOSE is:
  CATCLOSE (catindex, catstatus)

The catindex parameter contains the value returned by the CATOPEN
intrinsic that identifies the message catalog.  The first element of
catstatus returns the error number that tells if the call was successful.

An example of the CATCLOSE intrinsic follows:

          var
            Catstatus  : packed array [1..2] of SHORTINT;
            Catindex   : INTEGER;  {Returned by CATOPEN}

            CATCLOSE (Catindex, Catstatus);

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

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..2] of SHORTINT;

     Function CATOPEN:  INTEGER; intrinsic;
     Function CATREAD: SHORTINT; intrinsic;
     Procedure CATCLOSE        ; intrinsic;

     Procedure OPEN_SYSCAT;
     {This procedure opens SYSCAT.PUB.SYS}

     var
       Designator : packed array [1..20] of CHAR;

     begin
       Designator := 'SYSCAT.PUB.SYS ';
       Catindex := CATOPEN (Designator, Catstatus);

       {Call procedure to check Catstatus for errors}
     end;

     Procedure READ_SYSCAT;
     {This procedure reads a message from SYSCAT.PUB.SYS}
     {and prints it to $STDLIST                         }

     var
       Setnum    : SHORTINT;
       Msgnum    : SHORTINT;
       Parm1     : STRING [ 3 ];
       Dumy      : INTEGER;
       Msgdest   : SHORTINT;
       Msglength : SHORTINT;

     begin
       Setnum := 221;
       Msgnum := 8;
       Parm1 :='42';
       STRWRITE (Parm1, STRLEN(Parm1)+1, Dumy, CHR(0));
       {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.

MPE/iX 5.0 Documentation