Copyright © 1986 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.
This implementation of ML/I contains all the features described in the ML/I User's Manual, 5th Edition, 1986, including New Features 1 to 6 as described in that manual.
ML/I uses seven datasets, which are specified in the usual
way with DD statements. The PARM field is not used;
all control of ML/I is done via the internal system variables
(S-variables).
Three input datasets are used; they are referenced with the
DDnames INPUT1, INPUT2 and INPUT3.
Concatenated datasets are not supported;
it is more appropriate to perform this function via
the internal ML/I input mechanisms. Any legal dataset may be
specified for input, as long as its format is F, FB,
V or VB.
Two processing output datasets are used; they are referenced with the
DDnames OUTPUT1 and OUTPUT2.
A single listing dataset is supported; it is referenced with the
DDname LISTING.
A single dataset, referenced with the DDname DEBFILE, is used for
the ML/I debugging file; nearly all error messages are sent
to this, except for messages indicating fatal errors
connected with the debugging file dataset itself. No record
output to the debugging file ever exceeds 72 characters in
length.
All output datasets must be different, and they must also be different from
any of the input datasets. The default format for any output
dataset is LRECL=80, BLKSIZE=80, RECFM=F.
allocate dataset(*) file(input1)
allocate dataset(*) file(input2)
allocate dataset(*) file(input3)
allocate dataset(*) file(output1)
allocate dataset(*) file(output2)
allocate dataset(*) file(listing)
allocate dataset(*) file(debfile)
call ml1
This is sufficient for working through the Simple Introductory Guide.
PIG and DOG, and
output to FOO and BAZ.
The listing is sent to LIST, with messages to SYSOUT.
Note the use of the third dummy dataset INPUT3.
//GO EXEC PGM=ML1
//INPUT1 DD DSNAME=PIG,...
//INPUT2 DD DSNAME=DOG,...
//INPUT3 DD *
/*
//OUTPUT1 DD DSNAME=FOO,...
//OUTPUT2 DD DSNAME=BAZ,...
//LISTING DD DSNAME=LIST,...
//DEBFILE DD SYSOUT=*
ML/I sets its return code to various values in order to indicate the relative success of a particular processing run; there are three possible ways in which this return code can be set.
First, if the value of S11 is nonzero then this is used as the
return code. This overrides any setting obtained by other means,
and allows the ML/I user to indicate, via JCL, conditions
detected during macro processing.
Second (if S11 is zero), various errors detected by the ML/I I/O
system are indicated by appropriate return code settings. These
override the third method detailed below. The possible values are:
8
12
16
20
Lastly, any error detected during processing (output of
Error(s) to the debugging file) causes the contents of S5 to
be incremented by one. A nonzero value of S5 at the end of
processing will cause a return code of 4 to be generated.
The user is at liberty to alter the value of S5 during macro
processing, in order to obtain special effects.
If none of the above three conditions are met, a return code of zero is used, indicating normal completion of the run.
Input may be taken from any one of the input datasets, also referred to
here as streams. The value
of S10 controls the selection, and its possible values are:
S10 = 1
INPUT1.
S10 = 2
INPUT2.
S10 = 3
INPUT3.
If S10 is set to zero, ML/I treats this as "end of data" and
ceases processing. If S10 is set to any illegal value (negative
or greater than three) then the run 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 one; its value is held in S23 and
may be altered by the user if required.
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 EBCDIC code of the character to be translated,
and S17 to the EBCDIC code of the character that is
to replace it. For example, if $ (EBCDIC 91) was to
represent a tab (EBCDIC 5), S16 and S17
should be set in the following way:
MCSET S16 = 91 MCSET S17 = 5
Initially, S16 has the value -1, which (since it does
not correspond to a valid EBCDIC code) will not cause
any translations to be made.
Many datasets presented to ML/I will contain fields which should be ignored; the most common example of this is the presence of sequence numbers in columns 73 to 80.
It is possible to specify the last column at which input should be
recognised; this is done by setting S14 to the number of the column
in question. For example, to remove normal sequence numbers:
MCSET S14 = 72
Initially, S14 is set to 32767; this should enable all columns of
supported dataset types to be read.
On many occasions, an input dataset will contain records with
trailing blank characters. Some kinds of ML/I processing are
seriously upset by this, so ML/I normally removes all trailing
blanks from input records. However, it is possible to suppress
this action by changing the value of S15. If S15 is zero,
trailing blanks are not removed. If S15 is one, trailing blanks
are removed; this is the initial setting.
The ordering of input operations is as follows:
S10 equal to zero.
S10.
S14.
S16 and S17.
Output may be directed to either, both or neither of OUTPUT1 and
OUTPUT2. The values of S21 and S22 control
the selection; S21 controls OUTPUT1,
and S22 controls OUTPUT2. In both cases, a
value of zero means that no output is to take place, and a value of
one means that output is to take place.
Null output records are converted to records containing a single blank character.
A listing of the output from ML/I may be directed to the listing
dataset LISTING. Output to this 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.
Null listing records are converted to records containing a single blank character.
ML/I uses all available virtual store in its allocated region. To obtain additional workspace, simply increase the size of the region.
Limits are set on the workspace size, however; ML/I will not run with less than 5000 bytes of workspace, and will never request more than 100000 bytes.
The character set used by ML/I is basically IBM EBCDIC (codes from 0 to 255 decimal). There are no illegal characters.
However, ML/I uses three character codes internally for special purposes, and appearance of these codes in the input will lead to possible strange effects. These reserved codes have the decimal values 37, 254 and 255.
Error messages are output to the debugging file dataset DEBFILE.
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.
An output lines limit is imposed on the debugging file, to curb
excessive output from a process that has gone badly wrong. The
limit is implemented by holding a quota of "lines left" in S12;
if S12 ever goes negative, the process is aborted.
S12 is initially 500, but may be changed by the user.
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, followed (if S18 equals one)
by a list of the currently defined constructions.
All datasets are opened as soon as ML/I is entered. Failure to open any dataset causes an appropriate message to be output, and ML/I immediately exits.
The following run-time messages are peculiar to this implementation. They may be followed by other, advisory, messages which are self-explanatory.
Message
Debugging file lines quota exhausted
Description
The value of S12 (the quota of remaining lines allowed to the
debugging file) has become negative.
System Action
The current process is aborted.
Message
S10 has illegal value, viz n
Description
S10has been set to the value n, which is outside the range 0-3. Note that this error may be caused byS23(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.
Message
Primary output failure
Description
An error was detected while attempting to write to the primary output
dataset OUTPUT1.
System Action
The current process is aborted.
Message
Secondary output failure
Description
An error was detected while attempting to write to the secondary output
dataset OUTPUT2.
System Action
The current process is aborted.
Message
Listing output failure
Description
An error was detected while attempting to write to the listing dataset
LISTING.
System Action
The current process is aborted.
Message
xxxxxx dataset - unsupported record format
Description
The specified dataset can not be used for input or output because it is notF,FB,VorVBformat. Note that this includesDUMMYdatasets unless a suitableDCBparameter is included.
System Action
The current process is aborted.
Message
xxxxxx dataset - input open failure
Description
The specified dataset cannot be opened for input.
System Action
The current process is aborted.
Message
xxxxxx dataset - output open failure
Description
The specified dataset cannot be opened for output.
System Action
The current process is aborted.
Message
xxxxxx dataset - error on close
Description
An error was detected while trying to flush remaining output to the specified dataset at the end of a run.
System Action
The current process is aborted.
Message
xxxxxxxx dataset - no virtual store for buffer
Description
Virtual store could not be allocated for use as a record buffer for the specified output dataset.
System Action
The current process is aborted.
Message
Error reading from input
Description
An unexpected error was experienced
while reading from the current input stream (the system took a
SYNAD exit).
System Action
The current process is aborted.
Message
Insufficient virtual store
Description
ML/I was unable to obtain the minimum acceptable area of virtual store during initialisation.
System Action
The current process is aborted.
Message
Cannot open debugging file dataset
Description
ML/I was unable to open
the DEBFILE dataset for output. This message (and any further
explanation) is output as a "write-to-programmer" message.
System Action
The current process is aborted.
Message
Debugging file output failure
Description
An error was detected while
attempting to write to the debugging file dataset DEBFILE.
This message is output as a "write-to-programmer" message.
System Action
The current process is aborted.
The initial environment contains ten permanent variables, all set to zero. All integers in, or derived from, macro expressions should be less than 2147483647 in magnitude. Overflow is not detected, except in the case of division by zero, and its effect is undefined.
The following are the layout keywords for this implementation:
SPACE
NL
TAB
SL
SPACES
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 run to be terminated).
S1-S9S1
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
S2; it may be changed at any time.
S3
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
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
S6
S7
S8
S9
S10-S26S10
S10 is one.
S11
S12
S12 contains the quota of lines on the debugging file. It is
initially 500, and every time ML/I outputs a line to the debugging file
(whether via an error message or a MCNOTE) it decreases
S12 by one. If S12 ever becomes negative, the process is
aborted. The user is at liberty to adjust the value of S12 at any
time.
S13
S14
S14 is 32767.
S15
S15 is one (the initial value), trailing blanks are deleted;
if it is zero, trailing blanks are not deleted.
S16
S16 are translated to characters with the code given by
S17, on input. Initially S16 is -1, so no
translations are performed.
S17
S16 above.
S18
S18 is one at the end of a process,
a list is given of all currently defined
constructions.
This is output to the debugging file (and is not subject
to the quota of lines imposed by S12).
If S18 is zero, the list is not produced.
The initial value of S18 is one.
S19
S19,
and is updated when the first character is output to each new line.
It may be changed if desired.
S20
S20 controls output to the listing dataset.
See Section T.2 for details.
S21
S21 controls output to the primary output stream,
and is initially set to one. See Section T.2 for details.
S22
S22 controls output to the secondary output stream,
and is initially set to zero. See Section T.2 for details.
S23
S23 contains the current revert stream, and is initially set to one.
See Section T.2 for details.
S24
S24 contains the number of bytes of workspace allocated to
ML/I when it was started; this will depend on the size of the
region in which ML/I is running.