github.com/moshix.mvs
1
0
Fork 0
mirror of https://github.com/moshix/mvs.git synced 2026-01-22 18:21:25 +00:00
Code Issues Releases Wiki Activity
moshix.mvs/PC370_orig/Diskette/full/DOC/SYSTEM.DOC

635 lines
29 KiB
Plaintext
Raw Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

SYSTEM.DOC PC/370 release 4.1 system services documentation
Chapter table of contents:
1. Introduction
2. File input and output services
3. Program load and execution services
4. SVC documentation in SVC # order
4. Floating point system documentation
*********
Chapter 1. Introduction
*********
The PC/370 system 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.
In supervisor state, svc's 1-7 provide a set of input and output
facilities using MS-DOS file handle I/O and an extended data control
block defined by the user which allows access to sequential and random
files. Svc's 10-11 provide virtual memory dynamic management. In
addition to the other misc. functions provided, svc 34 provides a
general purpose interrupt interface which can be used to map PC/370
area into PC registers and issue any MS-DOS function call or BIOS
interrupt. Svc's 128-191 map into BIOS interrupts using simple
register to register mapping. Svc's 200-241 map into MS-DOS function
calls 0-41 using simple register to register mapping. Note function
calls above 41 can be issued using svc 34 interface which is the
preferred method for future releases.
*********
Chapter 2. File input and output services
*********
The PC/370 supervisor 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
The PC/370 system 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 CPY\IHADCB.CPY and
demonstrated in UTIL\PRINTDOC.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
verified 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. If the DFTRAN (X'08') bit is set, input
records are translated to EBCDIC in the record area.
Output records are translated to ASCII in the record
area, written, and then translated back to EBCDIC.
The entire LRECL area is translated. For text mode,
each record must end with EBCDIC line feed.
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, 2 for RECFM=T or 1 for
RECFM=F.
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. If register 2 does not point to a valid
DCBDCB ID field not exit is taken and interactive debug
is invoked. If exit is taken, register 0 contains
error code and register 1 contains function code which
can be used by to produce error message by calling
subroutine LIB\SYNERROR.ALC which is in the default
system relocatable library L370.LIB.
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
override 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 UTIL\PRINTDOC.ALC for
example of file access method.
*********
Chapter 3. 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 return, 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 attached address space, exit to next
instruction after attach in mother address space
else exit to MS-DOS
36 RELOAD Reload file int memory at location in reg 0.
Reg 1 must have file address and reg 15 must have
maximum length of file allowed to be loaded into
preallocated area.
The PC/370 system 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
DEMOSVC.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 CPY\IHASCB.CPY 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
DEMO\MVS.ALC and DEMO\DEMOPSW.ALC demo programs.
The virtual address space established 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 CPY\IHASCB.CPY.
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 MVS PARM AREA POINTED TO BY REGISTER 1 AT ENTRY (A,H,EBCDIC TEXT)
100 SVC ATTACH INSTRUCTION
102 SVC DETACH INSTRUCTION POINTED TO 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.
*********
Chapter 4. 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 (see I/O section
documentation)
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
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 contains instruction
length in high 16 bits, interruption code in
low 16 bits, reg 1 contains interruption
address, and reg 2 contains program
interruption element block (see
CPY\IHAPIE.CPY).
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 length
27 detach program none (return to instruction after attach)
28 svc 209 EBCDIC set EBCDIC to ASCII trans. for WTO svc 209
(default)
29 svc 209 ASCII turn off EBCDIC to ASCII translation
30 svc 209 CR turn on carriage return and line feed
(default)
31 svc 209 no CR turn off carriage return and line feed
32 VA to SEG:OFF convert virtual address in R1 to
segment:offset in R0
33 SEG:OFF to VA convert segment:offset in R0 to virtual
address in R1
34 interrupt general purpose interrupt facility which
supports all MS-DOS and BIOS interrupts using
PC register vector table pointed to by R1
must be defined as follows (see
CPY\IHAPCB.CPY):
0 PCVT DC C'PCVT' ID REQUIRED BY SVC 34
4 PCIN DS H INTERRUPT # (0-255)
6 PCPF DS H PF FLAGS REGISTER
8 PCAX DS H AX
10 PCBX DS H BX
12 PCCX DS H CX
14 PCDX DS H DX
16 PCDS DS H DS
18 PCSI DS H SI
20 PCES DS H ES
22 PCDI DS H DI
PC registers are loaded from PCVT for
interrupt. PC register results are also
stored in PCVT area immediately after
interrupt. Note segment:offset addresses
such as DS:DX, DS:SI, or ES:DI required
by interrupts can be calculated via SVC 32.
Likewise returned segment:offset results can
be translated back to PC/370 virtual
addresses via SVC 33. This is a very
powerful and therefore dangerous instruction.
SVC's 128-191 and SVC's 200-241 should be
used in place of this more general SVC when
possible since they are a little faster (they
don't load and store all PC registers and
don't require PCVT setup). They are also
much safer since an error in PCVT setup could
invoke wrong interrupt or pass bad registers
to any function including reboot interrupt,
write to disk, etc SVC 34 does verify PCVT
identifier and range of PCIN within 0-255.
If verify fails, program interruption
19 occurs. If carry bit is set by interrupt,
condition code 3 is set, else condition code
0 is set.
35 80x87 assist Scientific subroutine function assist via
80x87. Register 1 contains function # and
values are passed via floating point
registers. See chapter on floating
point for more information.
36 RELOAD Load file into memory at address in reg 0.
Reg 1 must have file address and reg 15 must
have maximum file length allowed to be loaded
in preallocated area.
37 SVCTRAP Define svc trap table via register 1 which
contains address of user exit routine to be
used with each svc. If register 1 is zero
current svc trap table is cancelled. After
table is defined, each svc call functions as
follows:
1. If table+4*(svc #) contains zero,
execute real PC/370 svc normally.
2. If svc trap active mode is set,
execute real PC/370 svc normally.
3. If table+4*(svc #) is not zero,
store current psw at old svc psw x'20',
set trap active mode, and branch to
trap exit address in table entry.
LPSW instruction will always reset trap
active mode, and normal exit from trap
is via LPSW OLDSVC. All svc calls within
trap routine including the svc which
invoked trap will process as real svcs
normally without storing psw. See DEMO\
DEMOTRAP.ALC program for examples.
128 - 191 issue BIOS interrupt number = svc # - X'80' with PC
registers mapped as follows before and after interrupt:
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 - 241 issue interrupt 21H with PC registers mapped as follows:
For all svc's 200-241:
AH - MS-DOS function call number = svc number -200
AL - low byte of register 0
BX - low bytes of register 1
for svc # 201-208, 211, 213, 214, and 225:
DL - low byte register 2
for svc 209, 210, 212, and 215-241:
DS:DS - segment:offset from virtual address in register 2
CX - returned in register 14
DX - returned in register 15
One of the most frequently used SVC's is 209 (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
The above example will print message on console and issue
carriage return and line feed following message ending with
$. To turn off automatic carriage return and line feed,
issue SVC 31 prior to SVC 209. To eliminate overhead of
converting from default EBCDIC strings to ASCII for 209,
issue SVC 29 prior to SVC 209 and use PC/370 assembler
extension for ASCII strings in double quotes. For
example, this is the most efficient method of issuing
messages:
SVC 29 TURN OFF EBCDIC TO ASCII CONVERSION FOR 209
.
.
LA R2,=C"THIS IS A DEMO WTO MESSAGE$"
SVC 209
*********
Chapter 5. Floating Point System Documentation
*********
A. Introduction
PC/370 release 4.0 contains support for the entire 370 floating
point instruction set using the Intel 80x87 co-processor. If the
co-processor is not installed, all floating point instructions
cause operation exceptions as they would on a 370 without the
floating point option. There is a new option in the L370 linkage
editor (option P) which can be used to force turning off floating
point option even when co-processor is installed. Default is to
support floating point if it is installed and 370 module has been
linked using release 3.0+ linkage editor. In addition to the
standard floating point instructions, two additional levels of
support have been added. Section F describes a set of SVC's
which invoke extended microcode functions on the 80x87 chip such
as square root, logs, etc. These SVC's are fast but most require
special scaling of arguments. DOC\USER.DOC describes a set of
scientific subroutines written in ALC which can be called to
efficiently calculate functions over extended range of real
numbers.
B. Data formats
The Intel 80x87 actually only supports one IEEE floating point
format which has 64 bit mantissa and exponent range of 10**4932
which exceeds both the 370 short and long (double precision)
formats of 24 and 56 bit mantissa's. Therefore, both the short
and long operations are done with extra precision. The 370
extended format instructions are all supported but the precision
actually available is only 64 bits versus the 112 on a 370. When
short and long numbers are loaded into the 80x87, they are padded
with zeros to the 64 bit length required. When an extended
number is loaded into the 80x87, the last 8 bits are obtained
from the second register in the specified extended register pair.
The PC/370 cross assembler now supports E, D, and L data formats
when the 80x87 is installed.
C. Data exceptions
The standard 370 exponent overflow, exponent underflow, and
floating point divide exceptions are all supported. The program
mask can be set to control whether program exception is allowed.
One deviation from standard 370 convention, is to return the
maximum floating point number with correct sign when overflow
occurs instead of an invalid number. This is consistent with
IEEE standard.
D. Floating point instructions
1. Note that all operations are normalized using 80x87 and that
the 370 unnormalized function identical to normalized
instructions.
2. Compare short and long include all 64 bits in comparison. To
round number to specific number of bits in short or long
format, use the LRER or LRDR instruction prior to compare.
E. Interactive debug facilities for floating point
1. When floating point support is active (i.e. option P is on
and the 80x87 co-processor is installed), the R command will
display third line with floating point register contents in
hex. Note that the actual floating point register areas in
memory are stored in 80x87 temporary real format to allow
register to register instructions to execute faster since no
conversion from or to 370 format is required.
F. Extended 80x87 microcoded arithmetic functions
The following extended arithmetic floating point functions are
supported via SVC 35 with the function number in register 1.
Arguments and results are in the floating point registers F0 and
F2.
# Formula: Notes:
1. F0 = LOG10(2) constant
2. F0 = LOGE(2) constant
3. F0 = LOG2(E) constant
4. F0 = LOG2(10) constant
5. F0 = PI constant 3.14159....
6. F0 = ARCTAN(F2/F0) 0 <= F2 <= F0 < IFI (infinity)
7. F2/F0 = TAN(F0) 0 <= F0 <= PI/4 (sets F0 and F2)
8. F0 = SQRT(F0) 0 <= F0 < IFI
9. F0 = F2 * LOG2(F0) 0 < F0 < IFI, -IFI < F2 < IFI
10. F0 = F2 * LOG2(F0+1) 0 <= F0 < (1-(SQRT(2)/2)), _IFI < F2
< IFI
11. F0 = 2**F0 -IFI < F0 < IFI (note 1)
12. F0 = R0 convert to real
13. R0 = F0 convert to integer
14. F0 = MOD(F0/F2) return fraction of F0 mod F2 in F0
(note 2)
15. F0 = SIN(F0) argument may be any real radian value
(note 3)
16. F0 = COS(F0) argument may be any real radian value
(note 3)
17. F0 = TAN(F0) argument may be any real radian value
(note 3)
Notes:
1. This function uses equivalence expression to derive 2**F0 for
all values of F0 rather than just the 0.0-0.5 range supported
via the F2XM1 80x87 instruction.
2. Note this uses FPREM 80x87 instruction repeatedly to
calculate exact remainder via successive subtraction.
3. Note 15-17 perform scaling of argument via FPREM 80x87
instruction and use FPTAN 80x87 instruction to derive
tangent, sine and cosine.
Register 15 is set to one of the following values at exit from svc:
hex
00 - no errors detected
80 - 80x87 not operational
40 - invalid function number in register 1
20 - 80x87 precision error (inexact result such as 1/3 etc.)
10 - 80x87 underflow error (zero returned)
08 - 80x87 overflow error (max 370 value returned)
04 - 80x87 zero divide (max 370 value returned)
02 - 80x87 denormalized operand error (should not occur)
01 - 80x87 invalid operation error (should not occur)
Reference in New Issue View Git Blame Copy Permalink