TSO/ISPF client gateway

ISPF provides a thin gateway service that allows applications to start a TSO address space, send a TSO or ISPF command as input, and receive a response as output. Callers of this service are typically applications that are serving remote clients that want to issue TSO or ISPF commands. This section describes how the gateway works, how to install and customize the gateway, and how client applications can use the gateway.

Starting from z/OS® V2R2, the “Interactive ISPF Gateway” provides an improved ISPF gateway service for callers to start a TSO address space. The new service provides all of the same capabilities as the existing “Legacy ISPF Gateway” and many more. While the Legacy ISPF Gateway is still provided, users should consider migrating to the Interactive ISPF Gateway to benefit from the new features. Future enhancements for the TSO/ISPF client gateway will be made to the Interactive ISPF Gateway.

Advantages of using the Interactive ISPF Gateway:

  • The TSO/E address spaces are started by using a TSO logon procedure. Sites can choose to use their existing TSO logon procedures for TSO/E address spaces started through the gateway.
  • There is support for callers to execute programs that are interactive, using a conversational pattern.
  • Attention interrupts can be sent to terminate commands in progress.
  • The Interactive ISPF Gateway uses z/OS Common Event Adapter (CEA) TSO/E address space services to start and manage TSO/E address spaces. The z/OS CEA TSO/E address space services provide support for the reuse of TSO/E address spaces, improving performance when a single TSO/E address space is used to issue multiple TSO or ISPF commands.
  • The gateway can capture, and return to the client, messages that are issued using the TPUT and WTO macros and messages issued by TSO/E REXX.
  • TSO/E address spaces that are started using CEA TSO/E address space services have the same characteristics as TSO/E address spaces for users who have logged in through the TSO/E logon screen. Therefore, existing processes used to manage TSO/E address spaces also apply to address spaces that are started using CEA TSO/E address space services. For example the operator command:
    C U=user-id,A=asid
    can be used to cancel an address space that is started using CEA TSO/E address space services.

Requirements for using the Interactive ISPF Gateway:

  • Callers must define the CGI_CEATSO environment variable and set it to the value TRUE.
  • Callers must use Amode 64 because this is required by the underlying CEA TSO/E address space services.
  • A system administrator must configure and start the z/OS CEA address space.

For more information on CEA TSO/E address space services, refer to CEA TSO/E address space services in z/OS MVS™ Programming: Callable Services for High-Level Languages. For information on preparing to use the Interactive ISPF Gateway, see Preparing to use the Interactive ISPF Gateway.

Table 1 describes the load modules that comprise the TSO/ISPF client gateway. The footnotes indicate the required load modules for using the Interactive ISPF Gateway and the required load modules for using the Legacy ISPF Gateway.

Table 1. Load modules comprising the gateway
Name Library Description
ISPZINT ISP.SISPLPA Gateway initialization - routes processing to ISPZINO or ISPZINL. (1,2)
ISPZINO ISP.SISPLPA Legacy ISPF Gateway - manages TSO sessions using spawned processes, routes command requests to these sessions. (2)
ISPZINL SYS1.SIEALNKE Interactive ISPF Gateway – manages TSO sessions by using CEA TSO/E address space services and routing command requests to these sessions. (1)
ISPZTSO SYS1.LINKLIB TSO initialization - attaches a TSO session to run a command. ISPZTSO must run APF-authorized. (2)
ISPZCNT ISP.SISPLOAD ISPF initialization - allocates data sets and starts an ISPF session. (2)
ISPZCMD ISP.SISPLOAD ISPF command interface - invokes an ISPF command. (1,2)
ISPZTMO ISP.SISPLOAD Reusable session time-out processor. (2)
1 – Load module is used by the Interactive ISPF Gateway.
2 – Load module is used by the Legacy ISPF Gateway.

Table 2 describes the TSO/ISPF client gateway files installed into the z/OS UNIX file system. The footnotes indicate the required files for using the Interactive ISPF Gateway and the required files for using the Legacy ISPF Gateway.

Table 2. Gateway files installed into the z/OS UNIX file system
Name Description
/usr/lpp/ispf/bin/ISPZINL A stub file with the sticky bit set on to enable invocation of the Interactive ISPF Gateway load module ISPZINL. (1)
/usr/lpp/ispf/bin/ISPZINO A stub file with the sticky bit set on to enable invocation of the Legacy ISPF Gateway load module ISPZINO. (2)
/usr/lpp/ispf/bin/ISPZINT A stub file with the sticky bit set on to enable invocation of the gateway initialization load module ISPZINT. (1,2)
/usr/lpp/ispf/bin/ISPZTSO A stub file with the sticky bit set on to enable invocation of the TSO initialization load module ISPZTSO. (2)
/usr/lpp/ispf/bin/ISPZXENV A REXX routine called by the gateway XML API routine, ISPZXML, to set up environment variables. (1,2)
/usr/lpp/ispf/bin/ISPZXML A REXX routine that is the XML API for the gateway. (1,2)
1 – File is used by the Interactive ISPF Gateway.
2 – File is used by the Legacy ISPF Gateway.

If you are using the Interactive ISPF Gateway, see Interactive ISPF Gateway for additional information.

If you are using the Legacy ISPF Gateway, see Legacy ISPF Gateway for additional information.