This document covers the following topics:
Transparency provides an automatic method of integrating the TPF component in an existing Natural CICS or TSO installation, as well as an easy way of implementing new transactions that invoke TPF.
In the CICS environment, two programs are primarily responsible for controlling TPF interaction: the ACCESS46 program and the Transfer program.
In the TSO environment, module TPFXFER includes the ACCESS program and the Transfer program.
In both environments, the function of these programs is the same.
The ACCESS46 program is responsible for all of the actual interaction with the TPF system. In order to startup a TPF session, four items must be defined to the ACCESS program:
The node ID of the Com-plete system to be accessed; this name is defined in the ACSTBL subtable;
The user ID with which to sign on to Com-plete;
A password.
Data to be interpreted by the target system.
Note:
See also the section User ID
Considerations for more information on user ID and
password.
The Transfer program (named TPFXF46) is responsible only for simplifying the startup of a Com-plete session. The Transfer program uses a table (the Transfer table, TPFXTAB subtable), defined by the system administrator to automatically determine the proper node ID and user ID, and invokes ACCESS, passing over these items, including a dummy password. This means that:
The user does not need to perform an extra logon to Com-plete (since a CICS or external security user ID may have been used);
Programs that invoke Com-plete need not be modified to determine these items.
Programs written in current 3GL (COBOL, Assembler, PL/1) that pass control directly to Natural under CICS or TSO need not be changed to pass control to Natural under Com-plete. The 3 GL programs continue to run in the CICS address space/partition, but instead of transferring control to Natural, they can pass control to the Transfer program. This can be implemented by installing the Transfer program with the same name as that used for Natural under CICS or TSO. Based on the data passed to it under these circumstances, the transfer control program can determine the following items:
The Natural program to be invoked;
The data to be passed to that program;
The name of a CICS or TSO program to which control is to be transferred when the Natural program has run. The node ID and user ID are determined using the definitions in the Transfer table. Thus, after the 3GL program transfers control to the Transfer program, Natural is invoked automatically under Com-plete, and the process is invisible (transparent) to the user and to the programmer.
A second function of the Transfer program is to simplify definition of new CICS transactions. If a transaction is defined in the PCT as invoking TPFXF46, and the proper information is placed into the Transfer table, a user can invoke TPFXF46 directly using that transaction code; the Transfer program determines all of the information needed to start up a Natural program under TPF. This eliminates the need for many 3GL front-ends.
Reverse Access is another feature of TPF transparency and is available for CICS sites only. Many Natural programs currently under CICS call 3GL subroutines to perform certain functions. If these subroutines do not directly use any CICS facilities, then they can simply be installed to run in the TPF address space/partition. However, if a 3GL subroutine uses CICS for any reason, then it must run in the CICS address space/partition.
A facility is required to arbitrate between the Natural program, running in the target system, and the subprogram, running in the host system. The Subprogram Transparency feature of TPF performs this function and thus simplifies the implementation of TPF in a Natural CICS implementation.
There are two variants of Reverse Access:
Reverse Access with Immediate Return
If a subroutine that returns immediately needs to be
invoked using Reverse Access, then a "stub program" with the same name as the
subroutine is installed in the TPF system. This stub program consists of two
lines of Assembler language and is used mainly to pass control.
When a Natural program calls the stub program, TPF passes information to the ACCESS program (running under CICS), which in turn invokes the actual subroutine. When the subroutine has completed, it returns control to ACCESS, which in turn will return control to TPF and the Natural program.
Reverse Access with Delayed Return
If a subroutine that performs non-conversational functions needs to
be invoked using Reverse Access, then a user-written "stub program" must be
called. This program must issue a pseudo screen I/O which is interpreted by
ACCESS to invoke the required subroutine. Before linking to the
user-subroutine, ACCESS saves its CICS environment in temporary storage and
passes to the user-subroutine the name of a program to be invoked by the
subroutine on termination. On being called, this program restores the ACCESS
environment and continues the Reverse Access calls, returning to the original
caller of the Reverse Access function.
- Installing TPFSTUBM
TPFSTUBM calls interface routines to perform TPF-specific functions. These subroutines were installed during the installation of the Com-plete target system. An example job to link TPFSTUBM is provided in the source library (member JCLLSTUB).
The linked program TPFSTUBM must exist in the residentpage space of Com-plete. This can be accomplished by including the following startup parameter in the sysparms:
RESIDENTPAGE=TPFSTUBM- CICS Subprogram Preparation
Transparency can be invoked for a given subprogram only if that subprogram exists in the CICS load library, and has an associated PPT entry.
- Stub Program
The source for the stub program consists of two lines of Assembler code:
The first line invokes the TPFSTUBC macro;
The second line is the END statement.
The label of the TPFSTUBC statement must be the name of the program. The syntax for the entire stub program is illustrated below: progname TPFSTUBC END
where progname is the program name.
This program must be assembled and linked into a library contained in the Com-plete COMPLIB concatenation.
- Determining Parameter Lengths
Using information passed by Natural, the stub program can determine parameter lengths.
However, sometimes the CALL statement may designate only the first field of a contiguous area which is being passed as a single parameter. Natural interprets the parameter length as that of the field specified on a CALL statement, and thus passes an incorrect length to the stub program.
When coding the TPFSTUBC statement for such a stub program, you can override the length information being passed by Natural by listing the various parameter lengths (enclosed by parentheses) after the TPFSTUBC designation.
For example:
Natural program call 01 PARM1 (A80) 01 PARM2 (A80) 01 PARM3 02 FLD1 (A2) 02 FLD2 (A5) 02 FLD3 (N7) 02 FLD4 (B4/1:2000) . . . CALL 'CICSPGM' PARM1 PARM2 PARM3 . . .The corresponding stub program definition is:
CICSPGM TPFSTUBC (80,80,2,5,7,8000)- Calling the Subprogram from Natural
Once the stub program is installed, Subprogram Transparency can be used to invoke the subprogram from Natural running under Com-plete. When Natural issues the CALL for the subprogram, the stub program is invoked:
CALL 'progname'The stub program, along with the TPFSTUBM program, determines the parameters passed by Natural and passes the appropriate data over to CICS, where the actual subprogram is invoked. When the subprogram is finished, control returns to Com-plete, and the Natural program continues.
Data can be passed in either direction.
Sample programs (TESTRE and TESTREV) are included on the source dataset. A sample Natural program is provided below:
0010 DEFINE DATA LOCAL 0020 01 ALLPARMS 0030 02 A(A250) 0040 02 REDEFINE A 0050 03 AA(A20) 0060 02 B(A250) 0070 02 REDEFINE B 0080 03 BB(A20) 0090 02 C(A250) 0100 02 REDEFINE C 0110 03 CC(A20) 0120 END-DEFINE 0130 MOVE ALL '1' TO A 0140 MOVE ALL '2' TO B 0150 MOVE ALL '3' TO C 0160 DISPLAY 'BEFORE CALL TO REVERSE ACCESS' 0170 DISPLAY AA BB CC 0180 CALL 'TESTRE' ALLPARMS 0190 DISPLAY 'AFTER CALL TO REVERSE ACCESS' 0200 DISPLAY AA BB CC 0210 END
If you need to call CICS subroutines (via Reverse Access) that use non-conversational functions under CICS, you must code and install an interface subroutine (a so-called "stub program").
An example Assembler program is supplied on the source data set (member ACSHXC). This program calls and passes data to a user program called USERPGM. The source data set also contains an example program with this name.
You must assemble this sample program and link it into a data set contained in the Com-plete COMPLIB concatenation.
Program USERPGM runs under CICS and can perform non-conversational screen I/Os. It ends with an EXEC CICS RETURN TRANSID(XTPF) or the transaction name you specified in the ACSDEF subtable for the internal continuation transaction.
The CICS application program USERPGM must be linked with the CICS stub programs DFHEAI and DFHEAI0 from the CICS loadlib. You must define the resulting module to CICS with CEDA, or include it in the PPT.
CICS program USERPGM obtains control with the following data:
4 byte ID 'HXCC' IDENTIFIER
8 byte pgmname 'ACCESS46' RETURN PROGRAM
user data