🚀 go-pugleaf

Writing authorized cross-memory servers that do not create system
integrity loopholes is difficult and very time-consuming.  I've
written several such servers, but I first implemented a common
authorized cross-memory (AXM) server infrastructure which I used
for all of them.

My general scheme for cross-memory servers is as follows:

1.  Provide a set of system-wide authorized services (like a set
    of additional SVC functions) which are used to enable and
    connect to authorized cross-memory servers, each of which is
    identified by a specific name and type.  This includes RACF
    checks that the server job is allowed to make itself
    available as the named server and that each client job is
    allowed to connect to the named server.

    These services are implemented via a non-space-switch PC
    using a single system LX.  They include functions such as
    setting up resource managers to handle abnormal termination
    of a connected server and validating that a client request
    has been made from a TCB that has a valid server connection.

    They are owned by the master address space.  They are
    initialized via the start-up routine for a dummy subsystem,
    either dynamically (when the system services are first
    installed) or statically, but the subsystem must be started
    in a way which performs the start-up in the master address
    space.  At present, the subsystem itself is never actually
    activated or used.

    The initialization routine loads the system services module
    using GLOBAL=YES into ECSA (if not already available in LPA)
    and calls the initialization routine within that module to
    establish the PC tables and environment for the service
    routines.  For integrity reasons, there is no way to withdraw
    or refresh the system services in a production environment
    without a re-IPL, although for testing purposes on a
    non-production MVS system I also have a program which
    initializes a test version of system services from a batch
    job and terminates them when a STOP command is issued for the
    job.

    The system-wide services are located via a system level
    name/token which contains the address of a data area in ECSA
    (subpool 241 key 0) containing callable entry points in ELPA
    or ECSA for all of the specific services.  Most of these
    entry points point to stub routines which extract the PC
    number from the data area and issue the relevant PC.

2.  Individual servers use these system-level services to make
    cross-memory servers available (again subject to RACF checks),
    using a non-system LX for each server.  Servers can be started
    up and closed down as often as necessary.

3.  Individual clients use the system-level services to connect
    client TCBs to cross-memory servers (again subject to RACF
    checks) and to issue cross-memory requests using a token
    returned by the connection request to identify the target
    server.  Cross-memory requests are normally issued via a tiny
    non-space-switch problem state front-end PC routine (provided
    with the system services) which uses an ARR to trap and
    filter out any abends caused by the server terminating and
    convert them to a return code indicating that the server is
    no longer available.  However, if the client interface has
    its own recovery routine, it can avoid the slight overhead of
    this front-end PC by issuing the server space-switch PC
    directly and using its own recovery logic to check for abends
    caused by the server going away.

My servers do not use any AX or EAX manipulation.  They are
called using stacking PC routines.  They normally run in
supervisor state but key 8.  They only support direct calling
from a client region, not "daisy-chained" calls in cross-memory
mode on behalf of a secondary client region.  They use a home
address space ALET (value 2) in AR mode to access client storage.
They only support connections and calls from callers running in
problem state in key 8 (or public storage key 9).  Storage in the
server region is mostly allocated using cell pool techniques.

Most of the request processing runs under the caller TCB in
cross-memory mode, optionally returning control to the client
address space when a wait occurs, in which case an ECB in the
client address space is posted via a cross-memory POST when the
server event completes, and the client can then reissue the
cross-memory call to resume the waiting request.  The method of
ensuring the integrity of that cross-memory POST is a complex
subject in itself, and involves holding the cross memory services
(CMS) lock across code which validates the request then issues
the POST, and ensuring that the ECB is in key 8 storage but in an
authorized subpool (subpool 230) so it cannot be FREEMAINed by
user code between validation and completion of the request.
If your server does not need to support the concept of
asynchronous requests which allow the client TCB to perform other
processing while waiting for a request to complete, that makes it
an order of magnitude easier to implement.

Many operating system services are subject to various
restrictions in cross-memory mode.  One minor complication was
that any WTO message issued in cross-memory mode was not
associated with the client job and in particularly did not appear
in the job log of the client job, so I had to provide a means of
passing back a message to the client region with a special return
code telling the interface to issue the WTO and issue the PC
again to resume cross-memory processing.  For printing out debug
messages, statistics and so in cross-memory mode, it was necessary
to write a routine to pass records via a queue to a subtask in the
server region itself which would then write them out.

This of course doesn't even begin to touch on the complexity of
writing a cross-memory server itself, which typically involves
advanced reentrant and concurrent programming techniques to
manage shared resources in the server address space.  Again, for
my own servers I implemented a common infrastructure to provide
services such as storage management, task management, resource
tracking, abend handling, cross-memory data movement and so on.

As this is such a complex area, I would suggest that you check
out all possible alternatives first.  Is there some existing
standard infrastructure you could use instead, even if it is not
an exact match for the requirements?  If the reason that you need
a server may also apply to other IBM customers, you could try
placing a requirement with IBM either to implement such a server
or to eliminate the need for it in some other way.

Jonathan Scott
CICS Development
IBM UK Labs, Hursley