Programmer 7500/MAX_PROGRAMMERS.iso/INFO/ASMUTL/PC370.ZIP/SVC.DOC

Text File | 1987-04-25 | 14.9 KB | 334 lines

 TITLE 'PC/370 supervisor services documentation'

Table of Contents

  A.  Introduction
  B.  File input and output services
  C.  Program load and execution services
  D.  All supervisor services in SVC order

 EJECT

  A.  Introduction

PC/370 release 2 supports a number of supervisor services through
the standard 370 SVC interface.  In supervisor state, each SVC invokes
pseudo microcode which performs the function requested at native
processor speed.  In problem state each SVC causes a standard SVC
interrupt storing the current PSW at location X'20' and loading the
new PSW from location X'60'.  Supervisor call routines can be user
written to map any SVC into any desired function in problem state.

 EJECT

  B.  File input and output services

The PC/370 supervior calls to the I/O supervisor all require register
2 to point to the DCB.  The SVC's are as follows:

 SVC  FUNCTION  OPTIONS

   1  OPEN
   2  CLOSE
   3  READ      register 1 must be address of block or zero
   4  WRITE     register 1 must be address of block or zero
   5  GET       register 1 must be address of area or zero
   6  PUT       register 1 must be address of area or zero
   7  DELETE
   8  SEARCH
  23  RENAME

PC/370 Release 2 supports sequential and random access to
files using MS-DOS file handle I/O with directory pathing.
To access a file, a data control block (DCB) must be defined
in the program with fields defined as shown in the dummy
section (DSECT) called IHADCB found in IHADCB.ALC and
demonstrated in TESTIO.ALC.   All fields must be defined
prior to open and cannot be changed while the file is open
with the exception of RCD, BUF, and RBA as described below.

An explanation of each field in the DCB follows:

  1.  DCBDCB - DCB identifier consisting of the four EBCDIC
               characters ADCB.  These characters are
               varified each time an I/O routine is called
               with the address of the DCB in register 2.
               An attempt is made to exit to the synchronous
               error exit address if there is no match.

  2.  DCBDSN - address of up to 64 character EBCDIC path and
               file name followed by a zero byte.  This field
               is automatically translated to ASCII as
               required.

  3.  DCBFID - MS-DOS assigned file handle at open time.
               This field must be initialized to high values
               or open routine will assume file is already
               open and take SYNAD exit.

  4.  DCBFLG - file condition flags used by I/O routines.
               This field must be initialized to zero except
               user defined buffer bit DFUBUF and user
               requested ASCII file conversion bit DFTRAN may
               be turned on.  No other bits may be modified
               by user.

  5.  DSORG  - data set organization EBCDIC code:

                 S for sequential
                 R for random file access.

  6.  MACRF  - data set access EBCDIC code:

                 R for read block with length of BLKSZ
                 W for write block with length of BLKSZ
                 (note PRECL can override BLKSZ on write)
                 G for get logical record into RCD area
                 P for put logical record form RCD area

  7.  RECFM  - data set record format EBCDIC code:

                 F - fixed length records with length LRECL
                     for get/put sequential access or length
                     BLKSZ for read/write random or
                     sequential access.
                 V - variable length records with length
                     stored in first 2 bytes (valid lengths
                     range from 3 to 64k).  Maximum length
                     allowed for a file is LRECL and only
                     sequential get/put modes supported.
                 T - text records ending with end of record
                     code (EOR usually X'0A' line feed).
                     Maximum length allowed for a file is
                     LRECL and only sequential get/put modes
                     supported.

  8.  EOR    - end of record code for text (default NL X'0A')

  9.  EOF    - end of file code for text (default X'1A')

 10.  LRECL  - length of logical record. Maximum is 64K less
               17 bytes.  Minimum is 3 for RECFM=V or 1 for
               RECFM=F/T.

 11.  BLKSZ  - length of block.  Maximum is 64K less 17 bytes
               and minimum is 3.  If zero is specified, a
               default block of 8k will be dynamically
               allocated and deallocated at open and close
               respectively.  BLKSZ should be specified for
               read/write access.  For sequential access,
               larger block size reduces contention between
               multiple files by reading or writing entire
               blocks at one time rather than for each
               record.  If insufficient memory is available,
               the maximum available will be allocated.

 12.  EODAD  - end of file exit address. This cannot be changed
               while file is open.

 13.  SYNAD  - synchronous error exit.  This cannot be changed while
               file is open.

 14.  RCD    - record area address for get/put only.  This
               address may be changed on each get or put by
               placing new address in register 1.  If register 1
               contains zero, then current DCB area will be used.

 15.  BLK    - block area address used for direct I/O via MS-
               DOS.  If DFUBUF is not set at open, this area
               is dynamically allocated and deallocated using
               BLKSZ or default for length.  If DFUBUF is set, then
               new block address can be set for each read or write
               by placing new address in register 1.  If register 1
               contains zero, then current DCB block will be used.

 16.  RBA   -  relative byte address for random access
               read/write.  First byte of file is zero.  This field
               must be reset for each random read or write.

 17.  REN   -  address of file rename followed by zero.
               Only used by RENAME SVC.  Both DCBDSN and REN must be
               initialized in a closed DCB prior to RENAME SVC 23.

 18.  IOCNT -  physical I/O count since open.  Larger
               BLKSZ will reduce physical I/O count for
               sequential file access.

 19.  PRECL -  physical record length on last read or
               write.  This field is initialized to zero
               at open.  On write, BLKSZ will be calculated
               if this field is zero, else this field will
               overide length allowing short blocks to be
               written.  This is useful in processing files
               of unknown length with fixed block logic.
               The last block read may be short, and the
               corresponding last block written may be short.

Do not modify the reserved areas which are only used by
PC/370 IOS while file is open.  See TESTIO.ALC for test
of each access method and error conditions.

 EJECT

C.  Program load and execution services

    SVC  FUNCTION  OPTIONS

     15  USEREXIT  transfer control to native code user exit at
                   relative address in reg 15 via far call

     25  LOAD      reg 1 points to ASCIIZ path/filename
                   on retrun, reg 0 has file address, reg 1 has length

     26  ATTACH    reg 0 must have file address of COM file and
                   reg 1 must have desired length of attached addr. space

     27  DETACH    if in attacded address space, exit to next instruction
                   after attach in mother address space else exit to MS-DOS


PC/370 release 2 includes support for dynamic loading and execution
of 370 modules assembled and linked by A370.EXE and L370.EXE.
Any file including COM and MOD type files can be loaded into free
memory by use of the LOAD SVC 25.  The only argument required is
the address of the path and file name in register 1.  The file name
must end with a suffix of the form .XXX or a zero byte.  The largest
free memory area will be allocated and the file loaded into it.
Register 0 will be set to the address of the area, and register 1 will
be set to the length of the file.  The unused portion of the allocated
area will be freed.  If the load operation was successful, register 15
will be set to zero, else it will be set to 1.  Demo test program
TESTSVC.ALC illustrates the use of the load function to load an 8086
assembly language subroutine and execute it via user exit SVC 15.

Any 370 COM file created by L370.EXE and loaded via the load SVC 25 above,
can be executed it its own address space via the attach SVC 26.  Register
0 must be set to point to the COM file (set by load SVC 25) and register 1
must be set to address space size (minimum set by load SVC 25),  If additional
space is to be included in the attached address space for dynamic use via
GETMAIN/FREEMAIN SVC's 10/11, then the area to be added must be allocated
in the mother address space prior to issuing attach SVC 26 and the total
length of the COM file plus the allocated free space placed in register 1.
A COM file can be executed multiple times via attach by reloading registers
0 and 1 and reissuing SVC 26.  On second and following calls, the same
address space control block built on the first call in the COM prefix area
is reused (See ASCB.DOC for layout) since it overlays original COM prefix
data.

Execution of the attached address space can be terminated via a detach
SVC 27 which restores the mother address space and continues execution at
the next instruction following the attach SVC 26.  The only other way to
terminate the attached address space normally is to issue an exit SVC 0
which exits directly to MS-DOS.  A detach SVC 27 in an address space which
has no mother, will cause exit to MS-DOS.

An alternative to using attach/detach to execute dynamically loaded 370
code is to use simple branch and link.  For 370 code linked into COM file,
the 370 code starts X'210' from the beginning of the COM file.  For code
linked into MOD type file by L370.EXE using option M,  the 370 code starts
immediately at the beginning of the file (i.e. the file load address
returned in register 0 by load SVC 25).

For example of each type program loading and execution, see TEST25ML.ALC,
Z86SUB.ASM, TEST25S1.ALC, TEST25S2.ALC, and TEST25S3.ALC.

The virtual address space estabished for the execution of COM files created
by L370.EXE has the following memory layout.  For a sample DSECT of the
address space control block, see ASCB.ALC.

 000 INITIAL PROGRAM LOAD PSW
 008 INITIAL PROGRAM LOAD CCW1
 010 INITIAL PROGRAM LOAD CCW2
 018 EXTERNAL OLD PSW
 020 SUPERVISOR CALL OLD PSW
 028 PROGRAM OLD PSW
 030 MACHINE CHECK OLD PSW
 038 INPUT/OUTPUT OLD PSW
 040 CHANNEL STATUS WORD
 048 CHANNEL ADDRESS WORD
 050 INTERVAL TIMER
 058 EXTERNAL NEW PSW
 060 SUPERVISOR CALL NEW PSW
 068 PROGRAM NEW PSW
 070 MACHINE CHECK NEW PSW
 078 INPUT/OUTPUT NEW PSW
 080 MS-DOS COMMAND LINE WITH LEADING LENGTH BYTE IN BINARY
 100 SVC ATTACH instruction
 102 SVC DETACH instruction pointed by reg 14 at entry
 104 address space control block ASCB for current COM program
 124 reserved
 138 save area pointed to by reg 13 at entry
 180 PC/370 package identification record
 200 beginning of 370 code and default entry pointed to by reg 15
     at entry if no other entry point specified on ALC END statement.

 EJECT

D.  All PC/370 supervisor services in SVC order

    SVC  FUNCTION        REGISTERS input/output

      0  exit to MS-DOS  none
      1  open file       reg 2 = DCB address
      2  close file      reg 2 = DCB address
      3  read block      reg 2 = DCB, reg 1 must be address of block or zero
      4  write block     reg 2 = DCB, reg 1 must be address of block or zero
      5  get record      reg 2 = DCB, reg 1 must be address of area or zero
      6  put record      reg 2 = DCB, reg 1 must be address of area or zero
      7  delete file     reg 2 = DCB address
      8  search file     reg 2 = DCB address/reg 0 = return code 0 if found
      9  program trace   3 character trace ID follows SVC (see DEBUG.DOC)
     10  get memory      reg 1 = length/reg 2 = address, reg 0 = 0 if ok
                         if reg 0 > 0, then reg 1 = maximum memory available
     11  free memory     reg 1 = length and reg 2 = address/reg 0 = 0 if ok
     12  ASCII to EBCDIC reg 1 = address and reg 2 = length
     13  EBCDIC to ASCII reg 1 = address and reg 2 = length
     14  set SPIE        if reg 1 = 0, remove SPIE else set SPIE exit to reg 1
                         at SPIE entry, reg 0 and 1 contain current PSW
     15  user exit       reg 15 = entry point to COM 80x86 code via far call
     16  instr. count    /reg 1 = current 370 instruction count
     17  load user exit  reg 1 = ASCIIZ path/file name/reg 0=addr.reg 1=len.
     18  time of date    /reg 0 = hour, minute, second, 100th second,
                         reg 1 = year, reg 2 = day, month, day of week
     19  allocate memory reg 1 = address of MS-DOS real block, reg 2 = length
                         /if reg 0 not zero, then reg 2 = max. available
     20  deallocate mem. reg 1 = address of MS-DOS real block
     21  input byte      reg 1 = device address, reg 0 = byte
     22  output byte     reg 1 = device, reg 0 = byte
     23  rename file     reg 2 = DCB address
     24  display line    reg 1 = attributes, reg 2 = address, reg 15 = row/col
     25  load file       reg 1 = path/filename/reg 0 = address, reg 1 = length
     26  attach program  reg 0 = COM file address, reg 1 = address space lenth
     27  detach program  none (return to instruction after attach)

    128 - 191 issue BIOS interrupt call with function = SVC # - X'80'

        AX - low bytes of register 0
        BX - low bytes of register 1
        CX - low bytes of register 14
        DX - low bytes of register 15

        If carry set by call, then CC =3 else CC = 0.
        8086 flags returned in high bytes of R0.

    200 - 256 issue MS-DOS function call using function = SVC # - 200

        AX - low bytes of register 0
        BX - low bytes of register 1
        DX - low bytes of register 2
        CL - set to (SVC number - 200) at entry

        MS-DOS svcs 9 and 10 support automatic
        EBCDIC and ASCII conversion.

        One of the most frequently used SVC's is write to operator.
        For example, to print message on standard output device via
        MS-DOS function call 9, the following 2 PC/370 instructions can
        be used:

           LA  R2,=C'THIS IS A DEMO WTO MESSAGE$'
           SVC 209

Please send any suggestions for improving this documention.  I tend to
assume that everyone loves to read technical manuals.