1 SIGNAL
 Writes the specified VMS message(s) to SYS$OUTPUT (and SYS$ERROR if
 different) and returns the status code of the first message in the list.

 Format

   SIGNAL message_code[,...]
2 Parameter
 message_code[,...]

 Integer value that uniquely identifies the message.  See the VMS
 Message Utility Manual for information on how to create your own
 message codes.

 Message codes are longword values that are divided into four fields. 
 The following diagram depicts the longword message code.

  31    28 27                    16 15                       3 2    0
 +-------------------------------------------------------------------+
 |  cntl  |     facility number    |      message number      | sev  |
 +-------------------------------------------------------------------+

  cntl

     The control bits are ignored by this utility.


  facility number

     Facility numbers in the range of 0-2047 are system facilities. 
     Facility 0 is reserved for SYSTEM messages.  Facility 1 is reserved
     for RMS messages.

     Facility numbers greater then 2048 are reserved for general use.


  message number

     A number in the range 0-8191 that uniquely identifies the message
     within the specified facility.


  sev

     Severity of the message.

        0 = WARNING
        1 = SUCCESS
        2 = ERROR
        3 = INFORMATIONAL
        4 = FATAL ERROR
        5 = undefined
        6 = undefined
        7 = undefined




2 Qualifiers
/FACILITY

  /FACILITY=string

  Command qualifier

    Overrides the default facility name for the first message written. 
    Facility names can be any string  from 1 to 9 characters in length.



/FAO_PARAMETERS

  /FAO_PARAMETERS=fao_list

  Message_code qualifier

    Allows you to pass parameters to messages that accept parameters. 
    Enclose the parameter list in parentheses and separate with commas. 
    Each parameter in the list must be preceded by one of the following
    keywords and either a colon (:) or an equal sign (=).  The parameters
    must be specified in the order that the message is expecting them. 


   STRING

     Specifies that the parameter is to be passed is a string.  If the
     string contains spaces, lowercase letters, or special characters, it 
     must be enclosed in quotes.


   INTEGER

     Specifies that the parameter is to be passed is an integer. 
     Integers are assumed to be decimal values unless preceded by one of
     the DCL radix operators (%x or %o).


   Example:

      /FAO_PARAMETERS=(STRING:"This is a string",INTEGER:123,STRING:XYZ)


   NOTE:  For messages with a facility code of 1 (RMS messages), the
          /FAO_PARAMETERS qualifier is ignored.  Instead, use the
          /RMS_STATUS qualifier.

          For messages with a facility code of 0 (system messages), the
          /FAO_PARAMETERS qualifiers may produce unwanted results.  The
          $PUTMSG system service only accepts parameters on system 
          exception messages (of which there are only 32 messages).



/FORMAT

  /FORMAT=message_options

  Positional qualifier

    Overrides the default message options for the process.  If placed on
    the command verb, /FORMAT will cause the specified fields to be
    printed for all messages in the list or until another /FORMAT is
    encounted.  If placed on a message code, then /FORMAT only affects
    that message and subsequent messages.  Any messages prior to that
    are not affected. 

    /FORMAT is ignored if placed on a message code with a facility
    number of 0 or 1.  To change the format of a message with a facility
    of 0 or 1 the qualifier must be placed either on the command verb or
    on another message preceding it.


   message_options

     The following options may be specified in the /FORMAT qualifier. 
     Enclose options in parentheses and separate with commas.  If only
     one option is specified, the parentheses may be ommitted. 


     FACILITY

       Causes the facility field of the message to be printed.  The
       facility field is the first field in a message.


     SEVERITY

       Causes the severity field of the message to be printed.  The
       severity field is a one letter field containing one of the
       following letters: W, S, E, I, F, or ?.  It is the second field
       in a message.


     IDENTIFICATION

       Causes the identification field of the message to be printed. 
       The identification field is the third field in a mesage and is a
       mneumonic for the text of the message.


     TEXT

       Causes the text field of the message to be printed.  The text
       field is the last field in a message and is a textual description
       of the status code.




/LOG

  /LOG    (default)
  /NOLOG

  Command qualifier

    Causes the message(s) to be written (/LOG) or not written (/NOLOG)
    to SYS$OUTPUT.  The default is /LOG.



/RMS_STATUS

  /RMS_STATUS[=status_code]
  /NORMS_STATUS

  Message_code qualifier

    Specifies the RMS status code for messages that require a value.  The
    status code must be specified as an decimal integer unless prefixed
    with one of the DCL radix operators (%x or %o).  The /RMS_STATUS
    qualifier is ignored for RMS messages that do not require a value and
    for messages with a facility code other than 1.  If you do not specify 
    /RMS_STATUS or specify it without a value the value defaults to 0.  Use
    the /NORMS_STATUS qualifier for RMS messages codes that return a message 
    of "%NONAME-W-NOMSG, Message number 00000000" in addition to the specified
    message (usually these meesages have a code like 0001Cxxx).




/SEVERITY

  /SEVERITY[=severity_code]

  Positional qualifier

    If placed on the command verb, /SEVERITY overides the severity field
    with the specified severity for all messages in the list.  If placed
    on a message code, /SEVERITY overides the severity field for that
    message only.


   severity_code

     The following options may be specified with the /SEVERITY
     qualifier:


     WARNING

       Produces a message with a severity of WARNING.


     SUCCESS

       Produces a message with a severity of SUCCESS.


     ERROR (default)

       Produces a message with a severity of ERROR.  This is the default
       if you do not specify a severity_code with the /SEVERITY
       qualifier.


     INFORMATIONAL

       Produces a message with a severity of INFORMATIONAL.


     FATAL

       Produces a message with a severity of FATAL.




2 Examples

    $ signal 20
    %SYSTEM-F-BADPARAM, bad parameter value
    $ signal 20/sev=inform
    %SYSTEM-I-BADPARAM, bad parameter value

    This example shows how you can overide the severity code for a
    message.



    $ signal %x3109A/fao=s:test.dat, %x18292/fac=dcl
    %DCL-E-OPENIN, error opening TEST.DAT as input
    -RMS-E-FNF, file not found
    $ show symbol $STATUS
      $STATUS == "%X1003109A"

    This example shows how to call multiple messages, pass fao
    parameters, and overide the default facility name.  It also shows
    that the status is set to the value of the first message (with the
    first control bit set).  



    $ set message/nofacility/noidentification/noseverity/notext
    $ signal %x3109A/fao=s:test.dat,%x18292/fac=dcl
    $ signal/form=(t,f) %x3109A/fao=s:test.dat,%x18292/fac=dcl
    %DCL,error opening TEST.DAT as input
    -RMS, file not found

    This example shows how to override the process default settings for
    messages.



    $ signal %x18824/rms=1827
    %RMS-F-DTFACC, error accessing file; reason code %X00000723

    This example shows how to pass an RMS status code to an RMS message.
