/
README.HRAF
150 lines (101 loc) · 6.3 KB
/
README.HRAF
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
Host Resource Access Facility
The Host Resource Access Facility (HRAF) provides direct access to host resources
by a Hercules guest program operating in privileged operation state via a Hercules
supplied DIAGNOSE code X'F18'.
DIAGNOSE X'F18' utilizes a set of subcodes for selection of the type of resource and
the mechanism in use by the program. Additionally, a subcode allows the DIAGNOSE
X'F18' functionality to be queried for the capabilitites provided. As the
functionality is enhanced over time, the query subcode will report a new version
number.
General Register Usage - DIAGNOSE Rx,Ry,X'F18'
The first operand of the DIAGNOSE, Rx, must be an even-odd pair of registers. The
second operand, Ry, may be any register. The contents of the registers are:
Rx Contains the subcode, a 32-bit unsigned value.
Rx+1 Contains the operational options used by the DIAGNOSE, if required by the
subcode
Ry Conatains the real address of the subcode's parameter block. All subcodes
require a parameter block.
Two mechanisms are provided for accessing host resources: compatibility mode and
native mode. The primary difference between the two modes is the structure and size
of the parameter block associated with the host resource being accessed.
Compatibility mode is intended to ease the migration from the original Jason Winter
general instructions to the privileged DIAGNOSE code. The compatibility parameter
block is essentially a 32-bit register save area corresponding to the values that
would have been encountered had the Jason Winter general instruction been used.
The native mode parameter block will use a different format allowing functional
extensions and compatibility mode limitations to be eliminated.
Enabling the Host Resouce Access Facility
By default, the Host Resource Access Facility is disabled. Use the 'archlvl'
command to enable the facility:
archlvl enable HOST_RESOURCE_ACCESS
DIAGNOSE X'F18' Subcodes
The following subcodes are supported or planned. The DIAGNOSE version in which the
subcode has been made available is identified. An '*' indicates a future planned
subcode.
Subcode Version Description
X'00000000' 1 Query DIAGNOSE X'F18' available functionality
X'00000001' * Perform a compatibility mode host socket function
X'00000002' 1 Perform a compatibility mode host file system operation
X'00000003' * Perform a native mode host socket function
X'00000004' * Perform a native mode host file system operation
Subcode X'00000000' - Query DIAGNOSE X'F18'
The query subcode provides the following information in its response parameter block:
1. The version of DIAGNOSE X'F18' provided by the executing Hercules emulator
2. Available facilities and modes of operation
3. Whether large file system support is available
4. The host platform to which resource access is being provided
5. Addressing modes supported
6. Additional information specific to subcodes.
Subcode X'00000001' - Compatibility Mode TCP Socket Access
Planned for future implementation, incorporates functionality comparable to that
offered by the dyn75 package Hercules module.
Subcode X'00000002' - Compatibility Mode File System Access
The following operations are provided, as identified by the operation field of the
parameter block:
Operation Description
0 Rename a file
1 Unlink the file (delete)
2 Open a file
3 Close a file based upon it's name
4 Read from a file in either binary or text modes
5 Write to a file in either binary or text modes
6 Seek to a position in a file
7 Commit any pending writes to the file
8 Close a file using its file handle
9 Set the file read/write mode to binary or text
Subcode X'00000002' - Limitations
Compatibility mode access to the host file system is restricted in the following
ways:
1. Large file system support is not available.
2. Use of subcode X'00000002' in z/Architecture mode requires the current PSW
addressing mode to be set to either 24- or 31-bit before execution of
DIAGNOSE X'F18', otherwise a specification exception occurs.
3. Dynamic Address Translation using secondary space, home space or access
register modes are not available. Only DAT-off and DAT-on primary-space modes
are supported, as specified in the operation options parameter in the odd
register of the pair.
Subcode X'00000003' - Native Mode TCP Socket Access
While eliminating limitations that may exist in the compatibility mode TCP socket
access, the native mode subcode is expected to implement IPv6 capability as well as
IPv4. This subcode is planned for future implementation.
Subcode X'00000004' - Native Mode File System Access
Primarily intended to eliminate some or all of the restrictions identified above
for the compatibility mode subcode.
Documentation
This file is intended to provide general information about the Host Resource Access
Facility and is not intended to provide detaled information about DIAGNOSE X'F18'.
Until this documentation is made available by the Hercules project, contact the
author on the main Hercules email list for access.
Giving credit where credit is due
Jason Winter developed the original support providing users access to host
facilities. This support for many years has been provided as externally loaded
functionality into Hercules as two different packages: dyn76, for access to the
host file system, and dyn75, for access to host TCP sockets.
The compatibility functionality offered by the Host Resource Access Facility is based
upon Jason Winter's original code, the licensing to which has been generously
provided by Jason to the Hercules community. See file license_dyn76.txt for the
licensing of the Hercules host file system functionality provided by the dyn76
package. Currently, Hercules has only incorporated the dyn76 Hercules functionality.
Dyn75 is planned for future Hercules incorporation. Thank you, Jason Winter.
-- Harold Grovesteen
Apr 23, 2011