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