xcall MIAMEX, MX_LITMSG, cat, msgno {, row, col, var, msgfile, arg, default'msg}

MX_LITMSG is mainly used within LIT utilities to display language-independent messages, although you can add use it to reference your own (properly formatted) message files as well. A "properly formatted" message file consists of lines in the following format:

<cat>,<msgno>,<message>{,<arg>}

<cat>,<msgno>,<message>{,<arg>}

etc

<cat> and <msgno> are typically formatted as three digit numbers, as in the example below. Any message may optionally be followed by a comma a numeric value which can optionally be returned to the calling program for whatever purpose. Comments are typically inserted by using <cat> and/or <msgno> values of 000. The lines of the file must be sorted, first by <cat> and then by <msgno>.

When a message file is accessed, it is loaded into user memory (for efficiency in handling subsequent accesses). When testing/updating the message file, remember to use DEL * to clear the user memory in order to get a fresh copy of the message file.

Parameters

cat  (Num)

is the message category number (corresponding to <cat> in the example above). In the case of the LITMSG.xxx files, each LIT utility would have its own cat value, as shown in the following table.

msgno  (Num)

is the message number within the cat category (corresponding to <msgno> in the example).

row, col  (Num)

may be optionally specified to have the message displayed at the given row and column position. If either is zero, or they are omitted, then the message will be displayed at the current cursor position. If row is negative, then the message is not displayed but instead only returned in the var parameter.

var  (String)

will return the text of the message if specified. The maximum supported line length for message files was 100 in A-Shell 5.0; it was increased to 256 in A-Shell 5.1.1106.

msgfile  (String)

may optionally give the complete filespec of the message file. If the extension is missing, it will be set to match the current language (as defined in the LDF or language definition file specified in the LANGUAGE statement in miame.ini, e.g. USA, SPA, FRE, etc.). If the parameter is blank or omitted, the default is "DSK0:LITMSG[1,4]" (with the extension being supplied as just described).

arg  (Num)

if specified, will return the optional <arg> field of the current message, if any.

default'msg  (String)

specifies the default message text to be used if the message is not located in the message (or the message file does not exist). Often, for maximum program readability, this parameter is specified as a literal string to make it obvious what the expected text of the message is. See the example below.

Example

Here is an excerpt from the LITMSG.USA file:

000,000,#

000,000,# A-Shell LIT command message table

000,000,# Language: English (US Only)

000,000,#

000,000,# Following 000,### messages are generic lit/cmdlin messages

000,000,#           001,### messages are from about.lit

000,000,#           002,### message are from telset.lit, etc.

000,001,?Exceeded maximum number of devices

000,002,?Cannot read

000,003,greater than

000,004,^ Specification error

000,005,?Device not found or mounted

000,006,file

000,007,disk block

000,008,Total of

000,009,%No files transferred

000,010,transferred

000,011,%No files deleted

000,012,deleted

001,000,# ABOUT.LIT messages...

001,001,Serial #

001,002,Licensed to:

001,003,Nodes Licensed:

001,004,Nodes in Use:

001,005,Jobs in Use:

xcall MIAMEX, MX_LITMSG, 1, 2, -1, -1, msg$, msgfil$, 0, "License Issued to"

The above call, assuming that msgfil$ was blank or set to "SYS:LITMSG" and the current language extension was "USA", and the above file was stored as SYS:LITMSG.USA, would return msg$ = "Licensed to". If the file was not found, then it would return "License Issued to" (because of the default'msg$ parameter).