1. Introduction

ConPLAN is a software package developed by Austrosoft S.A. for the migration of ICL 1900/2900 PLAN assembler programs to Siemens-Nixdorf and IBM mainframe computers. 
The software was commissioned by a South African client for the conversion of a text processing package. Completed in 1992, it has since been in use to process and print the South African and Namibian telephone and fax directories.

Note   

In the following chapters all references to " target system" are made under the premise of Siemens hardware, the BS2000 operating system and the BS2000 assembler ASSEMBF. However, due to the high degree of assembler level compatibility between Siemens and IBM mainframe computers, the creation of an IBM version of ConPLAN would require only minor modifications to the product.

An important goal in the development of ConPLAN was to automate the conversion process to as high a degree as possible. Due to the widely differing hardware and system software architectures of source and target systems, a three-stage process was found necessary to achieve this result.

  • At stage one, BS2000 macro assembler code is generated from the PLAN source or more specifically, every PLAN machine instruction is converted into an ASSEMBF macro instruction, invoking the emulation macro $PLAN.
     
  • This is followed by a BS2000 Assembler run, in which BS2000 machine code is generated through the repeated expansion of the $PLAN-macro. At this point the transformation is as complete as in-line code substitution will allow; functions outside the scope of this technique - as with calls to the ICL operating system - are implemented through calls to run-time modules.
     
  • These are linked-in at stage three of the process. Besides being necessary for technical reasons, introducing an intermediate ASSEMBF code level allows for a choice of program maintenance on either the PLAN- or BS2000 Assembler level.

ConPLAN achieves a high degree of efficiency, considering that software emulation is employed. It was found that on average, 3-4 ASSEMBF instructions will replace 1 PLAN instruction. Given the significantly higher throughput of current BS2000 computers compared to the 1900/2900 models - and this combined with other ConPLAN design features, e.g. the substitution of disk files for tape files by default - has the net effect of markedly improved program run times, despite emulation.

ConPLAN design principles

ConPLAN-style emulation works by ensuring that the corresponding data segments of both PLAN- and assembler program, when considered in their entirety as strings of binary data, remain identical at every stage of processing, throughout the program run. This includes data in I/O buffers, originating from or destined for peripheral sources. Data on peripheral devices can however be stored in the native target format (EBCDIC) if so desired. In order to achieve full compatibility with the ICL 24-bit word/6-bit character architecture, it is necessary for ConPLAN to internally make use of octal code and ICL's 64 character set. To overcome problems that could arise from the use of such unfamiliar data types on a Siemens/IBM computer, a debug command is provided which will show ICL data in a readily understandable format when testing ConPLAN programs interactively (see $AID debug facility).

Code translation to or from EBCDIC is performed with all I/O-operations other than those on mass storage devices; there it is optional. The access to peripheral devices is managed by run-time system modules which build on the standard BS2000 access methods BTAM and SAM on the one hand and BS2000 I/O-macros (RDATA, WROUT, WRTRD, WRLST) on the other. The differences in printer control are taken care of - as a simple 1:1 conversion of printer control characters is not possible, the ICL printer is emulated via a run-time module.

PLAN programs running under the control of the standard ICL operating system are principally batch programs as no terminal support exists; if interactive input is required, it is requested from the operator console. With ConPLAN, a measure of dialog capability has been introduced; firstly by emulating the operator console as user terminal and secondly, by extending the PLAN display statements (SUSTY, SUSWT) to allow for short messages to be returned to the user program. Furthermore, by emulating the ICL card reader as the system file SYSDTA, it has become quite feasible to conduct a full dialog (DISTY/Out - PERI/In sequences) via a user terminal.

Written in BS2000 Assembler and Macro-Assembler, the ConPLAN package consists of three components:

  • The compiler ConPLAN, which compiles PLAN source into ASSEMBF. 
    Data declarations (#LOWER, #UPPER) are directly converted into ASSEMBF data definition statements (DS, DC), whereas PLAN macros, machine instructions and calls to ICL system routines (e.g. 'housekeeping') are converted into calls to the emulation macro $PLAN. Other functions comprise the conversion of PLAN directives, PLAN literals and the substitution of relative branches (*-addresses) with branches to symbolic address labels.
  • The emulation macros @PLAN/$PLAN, which cooperatively generate the BS2000 assembler program based on the macro calls generated by ConPLAN. @PLAN establishes the basic program skeleton while $PLAN generates coding for either the in-line execution of a required function or the call of the appropriate ConPLAN run-time module.
  • A run-time system, which is invoked through coding generated by the macro $PLAN. It consists of modules for the execution of service calls (executive, I/0-system) and certain machine-instructions which cannot be executed efficiently in-line.

 

1.1 ConPLAN Software Contents

All components of the converter ConPLAN are contained on a BS2000 ARCHIVE-tape. The bulk of components is contained in the PLAM-library LIB.LMS.ConPLAN.

ELEMENTPLAM-TYPEAPPLICATION
   
$PLAN(M)Emulation macro (instructions)
@PLAN(M)Program skeleton generation 
$PCIA(M)Internal macro
$PBAS(M)Internal macro
$PEND(M)Internal macro
$ORG(M)Internal macro
$AID(M)Internal macro
$XXCBD(R)Machine instruction
$XXCDB(R)Machine instruction
$XXDCH(R)Machine instruction
$XXLDCH(R)Machine instruction
$XXADD(R)Machine instruction
$XXSUB(R)Machine instruction
$XXDIV(R)Machine instruction
$XXMULT(R)Machine instruction
$XXMOVE(R)Machine instruction
$XMDISDL(R)Display message (short)
$XMDISTY(R)Display message (long)
$XMSUSWT(R)Display message (short and wait)
$XMSUSTY(R)Display message (long and wait)
$IOSDDEF(R)Logical I/O run-time module
$IOREAD(R)Logical I/O run-time module
$IOSDWR(R)Logical I/O run-time module
$IOSDCLB(R)Logical I/O run-time module
$IOSDEND(R)Logical I/O run-time module
$IOEXIT(R)Logical I/O run-time module
$IOPERI(R)Physical I/O run-time module
$IOPLAN(R)Initialization
$PTERM(R)Program start and termination
$ITRAID(R)Interactive debugging aid
$ITR6TO8(R)Data translation
$ITR8TO6(R)Data translation
$ICL64TT(R)Data translation tables

PLAM types:
   M ... macro element
   R ...  relocatable module

In addition to the PLAM-library LIB.LMS.ConPLAN, a number of cataloged files form part of ConPLAN. These are:

Executable Programs

C.ConPLANPre-Compiler
C.SPINSpooling in of ICL data tapes
C.DEMOPLAN test program

Plan Sources

SRC.PLAN.SPINPLAN source of program SPIN
SRC.PLAN.DEMOPLAN source of program DEMO

Procedures

P.PLANWrapper for the execution of ConPLAN
P.SPINExecute SPIN
P.DEMOExecute DEMO


1.2 Copyright Protection

  • Load all files from the TSOSMT-tape provided into a BS2000 user-id
  • Do not change any file attributes in the catalog entries of the ConPLAN files at this stage
  • Execute the program C.ConPLAN by starting the procedure P.PLAN. C.ConPLAN will display an alphanumerical 18-digit lock word. The lock word should be submitted to the supplier of the software, who will then issue a numerical 7-digit init key. ConPLAN is  initialized by entering this key. (ConPLAN can however be terminated if instead of the init key, 'END' is entered. Execute P.PLAN again after obtaining the init key to complete the initialization)

Warning:  Care has to be taken when entering the init key as its validity will not be checked immediately - ConPLAN and the converted PLAN programs will produce incorrect results if the key was incorrect. If a wrong init key had been entered, the initialization procedure can be repeated by simply starting ConPLAN (P.PLAN) again. The user will be prompted for an init key as long as ConPLAN identifies the stored key as incorrect.

Note   

After initialization it will not be possible to move ConPLAN to another BS2000 user-id without re-entering the init key.
ConPLAN will also request a new key if significant changes to hardware or operating system environment have been made (e.g. a mainframe or operating system upgrade).