S-Lang Run-Time Library Reference: Version 1.4.0: Message and Error Functions

Next Previous Contents

## 7. Message and Error Functions

## 7.1 error

Synopsis

  Generate an error condition

Usage

  `error (String_Type msg`

Description

  The `error` function generates a S-lang error condition causing the interpreter to start unwinding to top-level. It takes a single string parameter which is displayed on the stderr output device. The error condition may be cleared via an `ERROR_BLOCK` with the `_clear_error` function. Consult A Guide to the S-Lang Language for more information.

Example

  > `

  >         define add_txt_extension (file)
  >         {
  >            if (typeof (file) != String_Type)
  >              error ("add_extension: parameter must be a string");
  >            file += ".txt";
  >            return file;
  >         }

  > `

See Also

  `verror, _clear_error, message`

## 7.2 message

Synopsis

  Print a string onto the message device

Usage

  `message (String_Type s`

Description

  The `message` function will print the string specified by `s` onto the message device.

Example

  > `

  >          define print_current_time ()
  >          {
  >            message (time ());
  >          }

  > `

Notes

  The message device will depend upon the application. For example, the output message device for the `jed` editor correspond to the line at the bottom of the display window. The default message device is the standard output device.

See Also

  `vmessage, sprintf, error`

## 7.3 usage

Synopsis

  Generate a usage error

Usage

  `usage (String_Type msg)`

Description

  The `usage` function generates a usage exception and displays `msg` to the message device.

Example

  Suppose that some function `plot` plots an array of `x` and `y` values. The such a function could be written to issue a usage message if the wrong number of arguments were passed:

  > `

  >         define plot ()
  >         {
  >            variable x, y;

  >            if (_NARGS != 2)
  >              usage ("plot (x, y)");

  >            (x, y) = ();
  >            % Now do the hard part
  >               .
  >               .
  >         }

  > `

See Also

  `error, message`

## 7.4 verror

Synopsis

  Generate an error condition

Usage

  `verror (String_Type fmt, ...)`

Description

  The `verror` function performs the same role as the `error` function. The only difference is that instead of a single string argument, `verror` takes a sprintf style argument list.

Example

  > `

  >         define open_file (file)
  >         {
  >            variable fp;

  >            fp = fopen (file, "r");
  >            if (fp == NULL) verror ("Unable to open %s", file);
  >            return fp;
  >         }

  > `

Notes

  In the current implementation, strictly speaking, the `verror` function is not an intrinsic function. Rather it is a predefined S-lang function using a combination of `Sprintf` and `error`.

See Also

  `error, Sprintf, vmessage`

## 7.5 vmessage

Synopsis

  Print a formatted string onto the message device

Usage

  `vmessage (String_Type fmt, ...)`

Description

  The `vmessage` function formats a sprintf style argument list and displays the resulting string onto the message device.

Notes

  In the current implementation, strictly speaking, the `vmessage` function is not an intrinsic function. Rather it is a predefined S-lang function using a combination of `Sprintf` and `message`.

See Also

  `message, Sprintf, verror`

Next Previous Contents