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. Title not available 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/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 
        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/iX 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