home *** CD-ROM | disk | FTP | other *** search
/ Programmer 7500 / MAX_PROGRAMMERS.iso / INFO / ASMUTL / PC370.ZIP / PC370.DOC < prev    next >
Encoding:
Text File  |  1987-05-03  |  12.3 KB  |  315 lines
  1.  TITLE 'PC/370 User Documentation Summary'
  2.  
  3. Copyright (c) 1987 Donald S. Higgins
  4.  
  5. This is the user documentation for the PC/370 Virtual Machine.
  6. The PC/370 package provides the capability to assemble, link,
  7. and execute IBM 370 assembler programs on any 80x86 MSDOS 2.0+ micro
  8. computer such as the IBM PC, XT, AT, PS/2, Compaq, etc.
  9.  
  10. You are encouraged to copy and share PC/370 with other users on
  11. the condition that the programs and documentation are not distributed
  12. in modified form, that no fee or consideration is charged, and that
  13. this notice is not changed or bypassed.  If you find this package
  14. useful, would like to help support continued enhancements, and would
  15. like to receive future update notices, please send $45. to:
  16.  
  17.     Don Higgins
  18.     6365 - 32 Avenue, North
  19.     St. Petersburg, Florida 33710
  20.  
  21. If you would like to correspond via electronic mail, you may send me
  22. messages via CompuServe Easy-mail ID 73047,1113.  You may also call during
  23. 7 PM to 9 PM at 813-345-1607.
  24.  
  25.  EJECT
  26.  
  27. TABLE OF CONTENTS
  28.  
  29. A. PC/370 PRODUCT OVERVIEW
  30.  
  31. B. A370.EXE ASSEMBLER
  32.  
  33. C. L370.EXE LINKAGE EDITOR
  34.  
  35. D. E370R20.EXE EMULATOR
  36.  
  37. E. TECHNICAL REFERENCE INFORMATION
  38.  
  39. F. SEPARATE APPENDIX FILES
  40.  
  41.    1. ASSIST EXTENDED INSTRUCTIONS - ASSIST.DOC
  42.    2. SUPERVISOR SERVICES          - SVC.DOC
  43.    3. INTERACTIVE DEBUG            - DEBUG.DOC
  44.    4. EXTENDED ARCHITECTURE (XA)   - XA.DOC
  45.    5. OPERATING SYSTEM VIA PSWS    - PSW.DOC
  46.    6. REFERENCE PUBLICATIONS       - REF.DOC
  47.    7. UTILITY PROGRAMS             - UTILITY.DOC
  48.    8. PC/370 RELEASE HISTORY       - HISTORY.DOC
  49.    9. LATEST RELEASE CHANGES       - PC370R20.DOC
  50.  
  51.  EJECT
  52.  
  53. A. PC/370 PRODUCT OVERVIEW
  54.  
  55. PC/370 is a software package designed to run on any 80X86 micro-
  56. computer using the MS-DOS 2.0+ operating system.  PC/370 provides the
  57. capability to assemble, link, and execute IBM 370 assembler
  58. programs directly on any 80X86 microcomputer such as the IBM PC,
  59. XT, AT, PS/2, Compaq with 256K of memory and one floppy disk drive.
  60.  
  61. PC/370 has a number of possible uses including:
  62.  
  63.   1.  Allow students to code, assemble, and execute IBM 370
  64.       assembler programs on a PC instead of having to share an
  65.       IBM 370 mainframe.
  66.  
  67.   2.  Provide IBM 370 assembler programmer work station support
  68.       to allow the development and unit testing of 370 ALC programs.
  69.  
  70.   3.  Provide capability to down load existing or new IBM 370
  71.       assembler applications to run on PC's.
  72.  
  73. The PC/370 product currently consists of three components:
  74.  
  75.   1.  A370.EXE is an IBM 370 assembler which reads source code file
  76.       and produces object code file plus optional listing file.
  77.  
  78.   2.  L370.EXE is an IBM 370 linkage editor which reads object
  79.       code and produces a directly executable 80x86 machine code file
  80.       plus optional CSECT listing file. (L370 also has capability to
  81.       load and go without creating executable file output).
  82.  
  83.   3.  E370R20.EXE is an IBM 370 machine code emulator which is
  84.       dynamically loaded at execution time to support
  85.       execution of 370 code.  The emulator supports the following
  86.       extended functions at execution:
  87.  
  88.         1.  All MS-DOS supervisor calls and BIOS calls are supported
  89.         2.  Logical buffered file access method (like QSAM and BDAM)
  90.         3.  Dynamic memory allocation (like GETMAIN and FREEMAIN)
  91.         4.  Interactive debug and trace facility (better than ABEND dump)
  92.         5.  Program interrupt user exit (like SPIE)
  93.         6.  User microcode (80x86) subroutine call (like user SVC)
  94.         7.  Extended ASSIST instructions to simplify I/O.
  95.         8.  Extended Architecture (XA) instructions to allow
  96.             unit testing of 31 bit addressing programs.
  97.         9.  Date, time, and instruction count services
  98.        10.  Cross memory services to allow full access of all 80x86
  99.             real memory via MVCP and MVCS privileged instructions.
  100.        11.  Load, attach, and detach facilities to run modules in
  101.             separate address spaces with memory protection.
  102.        12.  Multiple operating system interfaces can be supported via
  103.             user written interrupt handlers to support 370 standard supervisor
  104.             call, program check, and external interrupts.  Models for MVS,
  105.             DOS, and VM are included (see PSW.DOC).
  106.  
  107. 8086  is trademark of Intel Inc.
  108. MS-DOS is trademark of Microsoft Corp.
  109. IBM  is trademark of International Business Machines
  110.  
  111.  EJECT
  112.  
  113. B.  A370 ASSEMBLER
  114.  
  115. The A370 assembler has the following command format:
  116.  
  117. A>A370 file/options
  118.  
  119. where file is the name of a source program file which has the
  120. suffix (.ALC).  The source file must be in ASCII text
  121. format with each line terminated by a line feed character.
  122. Any number of editors including SEE can be used to create ALC files.
  123. An optional drive and path may be specified such as B:\dir\file.
  124. The options which can be specified are as follows:
  125.  
  126.   L - produce listing file (.PRN). Default is none.
  127.   X - produce symbol and literal cross reference. Default is none.
  128.   A - alignment option. Default is on.
  129.   C - object code option. Default is on.
  130.   T - trace assembler execution. Default is off.
  131.  
  132. If an option is on by default, specifying it will turn it off.
  133. For example:
  134.  
  135. A>A370 B:DEMOPNUM/LX
  136.  
  137. will read the source file B:DEMOPNUM.ALC and produce the object
  138. code file B:DEMOPNUM.OBJ and the listing file B:DEMOPNUM.PRN.
  139.  
  140. The A370 assembler conforms to the OS/VS IBM 370 Assembly
  141. Language as defined in the IBM manual GC33-4010 with the
  142. following limitations:
  143.  
  144.   1.  No continuation lines.
  145.   2.  No copy facility. (Use COPY to concatenate source files).
  146.   3.  Maximum control sections and dummy sections is 255.
  147.   4.  Macros and system variable symbols are not supported.
  148.   5.  Data constant types E, D, L, and Q are not fully supported.
  149.   6.  OPSYN statement not supported.
  150.   7.  EQU third operand (type attribute) not supported.
  151.   8.  Scale, exponent, and bit length data modifiers not supported.
  152.  
  153. Extended features include the following:
  154.  
  155.   1.  Data constant types F and H may use arithmetic expressions.
  156.   2.  Extended ASSIST instruction set including XREAD, XPRNT,
  157.       XDECI, XDECO, AND XDUMP as defined in the book Assembler
  158.       Language with ASSIST by Ross A. Overbeek.  Also 2 more
  159.       instructions XFILI and XFILO are added to allow changing
  160.       default ASSIST input and output files at execution time.
  161.  
  162.  EJECT
  163.  
  164. C.  L370 LINKAGE EDITOR
  165.  
  166. The L370 linkage editor has the following command format:
  167.  
  168. A>L370 file/options
  169.  
  170. where file is the name of an A370 object code file (.OBJ) and
  171. may specify a specific drive.  The options supported by the
  172. linkage editor are as follows:
  173.  
  174.   L - external symbol listing file (.LST). Default is off
  175.   X - cross reference of external symbols. Default is off.
  176.   D - set debug mode for emulator. Default is off.
  177.   O - dump input object code records in hex. Default is off.
  178.   G - load and execute with no file output. Default is off.
  179.   T - trace linkage editor execution. Default is off.
  180.   M - create 370 code module without COM prefix code.
  181.  
  182. For example:
  183.  
  184. A>L370 B:DEMOPNUM/LX
  185.  
  186. will read the object code file B:DEMOPNUM.OBJ and produce the binary
  187. command file B:DEMOPNUM.COM, and the listing and cross-reference file
  188. B:DEMOPNUM.LST.  Note that since DEMOPNUM calls two external subroutines
  189. DAT and TOD, the subroutine library L370.LIB must be available.
  190. The binary command file B:DEMOPNUM.COM may be directly
  191. executed by the MSDOS command:
  192.  
  193. A>B:DEMOPNUM
  194.  
  195. When the above command is executed, the program will load at X'0200'
  196. and the fetch routine linked with the program will load the
  197. emulator E370.EXE in high memory and transfer control to it.
  198.  
  199. The linkage editor uses two concatenated subroutine library
  200. files.  The first file is named file.LIB and may contain
  201. any number of A370 subroutine object modules which
  202. are called by the modules in file.obj.  This file is optional
  203. and only called modules are included.  The second file is
  204. named L370.LIB and may contain any number of A370 subroutine
  205. object modules which are commonly used by multiple
  206. programs.  An L370.OBJ file is included with the PC/370 package
  207. and contains sample time and date routines.
  208. COPY may be used with option /B to
  209. concatenate A370 object modules in either library file.
  210.  
  211. The linkage editor listing file (.LST) shows relative entry point
  212. and segment lengths and optional cross reference by segment.  The
  213. last line of the listing contains ENT/LNG which is the 370 relative
  214. entry point of the module and the length of the entire module.
  215.  
  216.  EJECT
  217.  
  218. D.  E370R20 EMULATOR
  219.  
  220. The E370R20 emulator is transparent to the user when using A370
  221. and L370 to create MSDOS command files.  The emulator which
  222. is stored in E370R20.EXE as a binary module, is automatically
  223. loaded in high real memory.  The execution of the A370
  224. object code will start at the specified relative start address
  225. plus hex 200 with that absolute address in register 15.
  226. If a program check occurs, the interactive debug facility
  227. will be invoked and will initially display the general
  228. registers and the program status word at the time
  229. of the interruption.  See DEBUG.DOC for additional information on
  230. debugging facilities.
  231.  
  232.  EJECT
  233.  
  234. E. TECHNICAL REFERENCE INFORMATION
  235.  
  236.    1.  A370 requires 192k memory to execute and can handle source
  237.        programs with over 1000 labels and up to 60k bytes long.
  238.    2.  L370 requires 192k memory and can handle load modules up to
  239.        60k bytes long.
  240.    3.  E370R20 requires 64k which includes the emulator, and
  241.        the extended SVC support functions, and interactive debug.
  242.    4.  E370R20 supports all the non-supervisor state IBM 370
  243.        instructions as defined in the IBM/370 XA Principals
  244.        of Operation manual SA22-7085 except the conditional
  245.        swapping feature instructions and the floating point feature
  246.        instructions (these instructions are correctly assembled by
  247.        A370).
  248.    5.  The minimum configuration for PC/370 is as follows:
  249.        a.  80x86 processor.
  250.        b.  256k RAM memory which allows execution of 370 program in
  251.            128k virtual address space.  Maximum virtual address space
  252.            is 512k on 640k machine.
  253.        c.  1 floppy disk drive.
  254.  
  255.    6.  A benchmark program consisting of calculating the first
  256.        100 prime numbers was run in interpretive BASIC using
  257.        16 bit integer arithmetic.  It took 67 seconds on a
  258.        4.77 MHZ 8086 system.  The same program was rewritten in
  259.        370 assembler using 32 bit fixed point arithmetic.  It
  260.        took 25 seconds to execute on the same system.  This
  261.        benchmark program is included on the distribution disk
  262.        as a demo called DEMOPNUM.ALC.
  263.  
  264.        The demo may be run with the following commands:
  265.  
  266.          A>A370 DEMOPNUM/LX  (create DEMOPNUM.OBJ)
  267.          A>L370 DEMOPNUM/LX  (create DEMOPNUM.COM)
  268.          A>DEMOPNUM
  269.  
  270.    7.  The following error messages are supported:
  271.  
  272.        A370/L370
  273.  
  274.         E01 - DUPLICATE LABEL
  275.         E02 - INVALID LABEL
  276.         E03 - SYMBOL TABLE FULL
  277.         E04 - INVALID OPERATION CODE
  278.         E05 - UNDEFINED OPERATION CODE
  279.         E06 - UNDEFINED LABEL
  280.         E07 - INVALID OPERAND
  281.         E08 - MEMORY FULL
  282.         E09 - EXPRESSION INVALID
  283.         E10 - SELF DEFINING TERM INVALID
  284.         E11 - ARITHMETIC OVERFLOW IN EXPRESSION
  285.         E12 - TOO MANY EXTERNAL SYMBOLS
  286.         E13 - NO BASE REGISTER AVAILABLE
  287.         E14 - LENGTH ERROR
  288.         E15 - OPERAND ERROR
  289.         E16 - DATA CONSTANT DUPLICATION FACTOR ERROR
  290.         E17 - DATA CONSTANT TYPE ERROR
  291.         E18 - DATA CONSTANT LENGTH ERROR
  292.         E19 - DATA CONSTANT DATA ERROR
  293.         E20 - START SEQUENCE ERROR
  294.         E21 - LTORG SEQUENCE ERROR
  295.         E22 - LOCATION COUNTER ERROR BETWEEN PASS 1 AND 2
  296.  
  297.    8.  IOS LOGICAL ACCESS METHOD USED BY A370, L370, AND E370
  298.  
  299.       IOS001 - NO DISK SPACE
  300.       IOS001 - FILE NOT FOUND
  301.       IOS001 - NO BUFFER SPACE
  302.       IOS001 - OPEN FAILED
  303.       IOS002 - CLOSE FAILED
  304.       IOS003 - READING UNWRITTEN DATA
  305.       IOS003 - INVALID REQUEST
  306.       IOS004 - ERROR IN EXTENDING FILE
  307.       IOS004 - END OF DISK DATA AREA
  308.       IOS004 - NO MORE DIRECTORY SPACE
  309.       IOS004 - INVALID REQUEST
  310.       IOS005 - INVALID RECORD TYPE
  311.       IOS005 - INVALID RECORD LENGTH
  312.       IOS006 - INVALID RECORD TYPE
  313.       IOS006 - INVALID RECORD LENGTH
  314.       IOS007 - DELETE FAILED
  315.