ML/I User's Manual --- Appendix T --- Implementation on IBM System/370 under MVS


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

ML/I User's Manual -- Appendix T

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

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.


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

T.1 Restrictions and Additions

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.


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

T.2 Operating instructions and I/O

T.2.1 Job control

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.

T.2.2 Example JCL

  1. To run ML/I with just input from and output to a TSO terminal, the only commands needed are:
          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.

  2. The following job step could be used to run ML/I with two input files called 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=*
          

T.2.3 Return codes

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
Invalid value for system variable 10.
12
Error while reading input or writing output, or while closing output dataset.
16
Failure to open input or output dataset.
20
Failure to open debugging file dataset, or debugging file output failure, or insufficient virtual store.

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.

T.2.4 Control of input

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
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 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.

T.2.4.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 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.

T.2.4.2 Input column limit

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.

T.2.4.3 Treatment of trailing blanks

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.

T.2.4.4 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 data (if the revert stream is selected as a consequence of this check, return to b)).
  4. Truncation of record to value specified by S14.
  5. Deletion of trailing blanks (if enabled).
  6. Translation using S16 and S17.

T.2.5 Control of output

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.

T.2.6 Control of listing

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.

T.2.7 Workspace

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.


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

T.3 Character set

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.


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

T.4 Error messages

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.

T.4.1 I/O errors

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.

T.4.1.1 Too many lines to the debugging file

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.
T.4.1.2 Illegal input stream

Message

   S10 has illegal value, viz n
   

Description

S10 has been set to the value n, which is outside the range 0-3. 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.
T.4.1.3 Primary output failure

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.
T.4.1.4 Secondary output failure

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.
T.4.1.5 Listing output failure

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.
T.4.1.6 Unsupported record format

Message

   xxxxxx dataset - unsupported record format
   

Description

The specified dataset can not be used for input or output because it is not F, FB, V or VB format. Note that this includes DUMMY datasets unless a suitable DCB parameter is included.

System Action

The current process is aborted.
T.4.1.7 Failure to open input dataset

Message

   xxxxxx dataset - input open failure
   

Description

The specified dataset cannot be opened for input.

System Action

The current process is aborted.
T.4.1.8 Failure to open output dataset

Message

   xxxxxx dataset - output open failure
   

Description

The specified dataset cannot be opened for output.

System Action

The current process is aborted.
T.4.1.9 Failure to flush output dataset

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.
T.4.1.10 No virtual store for buffer

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.
T.4.1.11 Input error

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.
T.4.1.12 Insufficient virtual store

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.
T.4.1.13 Debugging file open failure

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.
T.4.1.14 Debugging file output error

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.


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

T.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 2147483647 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

T.6 Layout keywords

The following are the layout keywords for this implementation:

SPACE
meaning a space.
NL
meaning a newline.
TAB
meaning a tab. Note that many devices do not support tabs; nevertheless, ML/I supports this keyword for those that do.
SL
meaning the imaginary startline character.
SPACES
meaning a sequence of one or more spaces.


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

T.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 run to be terminated).

T.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
Count of processing errors.
S6
Not currently used.
S7
Not currently used.
S8
Not currently used.
S9
Not currently used.

T.7.2 Use of S10-S26

S10
Controls input selection; a value of zero forces end of all input. Values between 1 and 3 select the appropriate input stream; other values cause an error. The initial value of S10 is one.
S11
Not currently used.
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
Not currently used.
S14
Contains the highest column number from which input is read; all input appearing at higher column numbers is discarded. The initial value of S14 is 32767.
S15
Controls the deletion of trailing blanks on input records. If S15 is one (the initial value), trailing blanks are deleted; if it is zero, trailing blanks are not deleted.
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
If 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
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 dataset. See Section T.2 for details.
S21
The value of S21 controls output to the primary output stream, and is initially set to one. See Section T.2 for details.
S22
The value of 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.