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