ML/I User's Manual --- Appendix U --- Implementation on MS-DOS


Node:Top, Next:, Up:(dir)

ML/I User's Manual -- Appendix U

This implementation is based on version AJB of ML/I.

Copyright © 1988 R.D. Eager

Permission is granted to copy and/or modify this document for private use only. Machine readable versions must not be placed on public web sites or FTP sites, or otherwise made generally accessible in an electronic form. Instead, please provide a link to the original document on the official ML/I web site.


Node:Restrictions and Additions, Next:, Previous:Top, Up:Top

U.1 Restrictions and Additions

This implementation of ML/I contains all the features described in the ML/I User's Manual, Fifth Edition, including New Features 1 to 6 as described in that manual.

This implementation is a 16 bit DOS program; as such, it will run on even the most basic PC, with an 8086 or 8088 processor.


Node:Operating instructions, Next:, Previous:Restrictions and Additions, Up:Top

U.2 Operating instructions and I/O

U.2.1 Parameters

The call of ML/I takes the form

   ml1 input1,input2,input3 output1,output2,listing,debuggingfile
   

The parameters have the following meanings:

input1
This specifies the first input file. If this parameter is omitted or is null, CON: is used.
input2
This specifies the second input file. If this parameter is omitted or is null, any attempt to read from the second input file is illegal.
input3
This specifies the third input file. If this parameter is omitted or is null, any attempt to read from the third input file is illegal.
output1
This specifies the name of the file to receive the primary output from the ML/I process. If this parameter is omitted, CON: is used.
output2
This specifies the name of the file to receive the secondary output from the ML/I process. If this parameter is omitted or is null, all output to the secondary output stream is discarded.
listing
This specifies the name of the file to receive the listing output from the ML/I process. If this parameter is omitted or is null, all listing output is discarded.
debuggingfile
This specifies the name of the ML/I debugging file. If this parameter is omitted or is null, CON: is used.

All output files must be different, and they must also be different from any of the input files. Any legal DOS file or device name may be specified for any file.

Any attempt to use an input file (except input1) not specified in the call of ML/I will cause the process to be aborted, after the output of a suitable message.

U.2.2 Example calls

  1. To run ML/I with just input from the keyboard and output to the display, the only command needed is:
          ml1
          

    This is sufficient for working through the Simple Introductory Guide.

  2. To run with two input files called PIG.TXT and DOG.ASM, and output to FOO.DAT, with listing to BAZ.LST:
          ml1 pig.txt,dog.asm foo.dat,,baz.lst
          

U.2.3 Control of input

Input may be taken from any one of the input files (or streams, as they will be referred to from now on). The value of S10 controls the selection. The possible values are:

S10 = 1
Input is taken from input1.
S10 = 2
Input is taken from input2.
S10 = 3
Input is taken from input3.

If S10 is set to zero, ML/I treats this as "end of file" and ceases processing. If S10 is set to any illegal value (negative, greater than three, or a value between one and three associated with an input stream which has not been specified) then the process is aborted.

If a change of input stream is made, the original stream is not "forgotten". Any attempt to read from this stream again will cause ML/I to carry on where it left off. When the end of an input stream is reached, ML/I checks to see if it is the revert stream. If it is, the process is terminated; otherwise input is switched to the revert stream, and processing continues. The revert stream is initially 1; its value is held in S23 and may be altered by the user if required.

U.2.3.1 Input translation facility

It is possible to designate that one character be translated to another on input. This makes it possible to input a character that a device does not support. However, only one character code can be translated in this way.

If it is desired to perform a translation, S16 should be set to the ASCII code of the character to be translated, and S17 to the ASCII code of the character that is to replace it. For example, if % (ASCII 37) was to represent a tab (ASCII 9), S16 and S17 should be set in the following way:

   MCSET S16 = 37
   MCSET S17 = 9
   

Initially, S16 has the value -1, which since it does not correspond to a valid internal code, will not cause any translations to be made.

U.2.3.2 Ordering of input operations

The ordering of input operations is as follows:

  1. Checking for S10 equal to zero.
  2. Checking for invalid values of S10.
  3. Check for end of file (if the revert stream is selected as a consequence of this check, return to b)).
  4. Translation using S16 and S17.

U.2.4 Control of output

Output may be directed to either, both or neither of the primary output and the secondary output. The values of S21 and S22 control the selection; S21 controls the primary output, and S22 controls the secondary output. In both cases, a value of 0 means that no output is to take place, and a value of 1 means that output is to take place.

U.2.5 Control of listing

A listing of the output from ML/I may be directed to the listing output file specified in the call of ML/I. Listing is controlled by the value of S20. If S20 is zero, no listing is produced at all. If S20 is one, a listing without line numbers is generated; if S20 is two, line numbers are included in the listing. S20 has an initial value of zero.


Node:Character set, Next:, Previous:Operating instructions, Up:Top

U.3 Character set

The character set used by ML/I is 7-bit ASCII (codes from 0 to 127 decimal). However, the character code 26 decimal (1A hexadecimal) is used internally to indicate end of file, and will cause unpredictable effects if it appears in the input to ML/I.


Node:Error handling, Next:, Previous:Character set, Up:Top

U.4 Error handling

Error messages are output to the debugging file specified in the call of ML/I; this defaults to CON:. With reference to Chapter 6 of the ML/I User's Manual, the number 2N (the maximum number of characters inserted into an error message without truncation) is 64. The error character is question mark (?).

At the end of a process, a message of the form

   At end of process: N lines, M calls
   

is output to the debugging file.

All files are opened as soon as ML/I is entered. Failure to open any file causes an appropriate message to be output, and ML/I immediately exits.

U.4.1 Error messages

The following run-time messages are peculiar to this implementation.

U.4.1.1 Illegal input stream

Message

   S10 has illegal value, viz n
   

Description

S10 has been set to the value n, which is either outside the range 0-3, or is associated with an input stream that was not specified in the call of ML/I. Note that this error may be caused by S23 (the revert stream) being set to an illegal value, and end of file then being reached on another input stream.

System Action

The current process is aborted.
U.4.1.2 Primary output failure

Message

   Primary output failure
   

Description

An error has occurred while writing to the primary output file.

System Action

The current process is aborted.
U.4.1.2 Secondary output failure

Message

   Secondary output failure
   

Description

An error has occurred while writing to the secondary output file.

System Action

The current process is aborted.
U.4.1.3 Listing output failure

Message

   Listing output failure
   

Description

An error has occurred while writing to the listing file.

System Action

The current process is aborted.
U.4.1.4 Debugging file output failure

Message

   Debugging file output failure
   

Description

An error has occurred while writing to the debugging file.

System Action

The current process is aborted.


Node:Integer calculations, Next:, Previous:Error handling, Up:Top

U.5 Integer calculations

The initial environment contains ten permanent variables, all set to zero. All integers in, or derived from, macro expressions should be less than 32767 in magnitude. Overflow is not detected, except in the case of division by zero, and its effect is undefined.


Node:Layout keywords, Next:, Previous:Integer calculations, Up:Top

U.6 Layout keywords

The following are the layout keywords for this implementation:

SPACE meaning a space.
NL meaning a newline.
TAB meaning a tab.
SL meaning the imaginary startline character.
SPACES meaning a sequence of one or more spaces.


Node:S-variables, Previous:Layout keywords, Up:Top

U.7 S-variables

There are 24 system variables. S1 to S9 are independent of the implementation, and are used to control and monitor ML/I itself. S10 to S23 are implementation dependent, and are used to control input/output, etc. If an S-variable is set to any value other than those given below, the effect is undefined (except for invalid values of S10, which always cause the process to be terminated).

U.7.1 Use of S1-S9

S1
If S1 is one, the imaginary startline character is inserted on input. If S1 is zero, no startlines are inserted; this is the initial setting.
S2
The current source text line number is held in S2; it may be changed at any time.
S3
If S3 is one, the error message normally generated if a warning marker is not followed by a macro name is suppressed. If S3 is zero (the initial value), the message is produced.
S4
If S4 is one, the context print-out normally given after a call of MCNOTE is suppressed. If S4 is zero, the context print-out is given; this is the initial setting.
S5
Not currently used.
S6
Not currently used.
S7
Not currently used.
S8
Not currently used.
S9
Not currently used.

U.7.2 Use of S10-S26

S10
Controls input selection; a value of zero forces end of all input. Values between one and three select the appropriate input stream; other values cause an error. The initial value of S10 is one.
S11
Contains the exit code from the run of ML/I. It is initially set to zero, but may be changed by the user in order to pass back information to the command processor.
S12
Not currently used.
S13
Not currently used.
S14
Not currently used.
S15
Not currently used.
S16
Used to control character code translation. Characters with the code given by S16 are translated to characters with the code given by S17, on input. Initially S16 is -1, so no translations are performed.
S17
See S16 above.
S18
Not currently used.
S19
The current line number of the output text is held in S19, and is updated when the first character is output to each new line. It may be changed if desired.
S20
The value of S20 controls output to the listing file. See Section U.2.5 for details.
S21
The value of S21 controls output to the primary output stream, and is initially set to one. See Section U.2.4 for details.
S22
The value of S22 controls output to the secondary output stream, and is initially set to zero. See Section U.2.4 for details.
S23
S23 contains the current revert stream. See Section U.2.3 for details.
S24
S24 contains the number of bytes of macro storage and workspace available in this version of ML/I.