# IBM TPNS

Teleprocessing Network Simulator (TPNS) is an IBM licensed program, first released in 1976 as a test automation tool to simulate the end-user activity of network terminal(s) to a mainframe computer system, for functional testing, regression testing, system testing, capacity management, benchmarking and stress testing.$^{:19–22}$
In 2002, IBM re-packaged TPNS and released
Workload Simulator for z/OS and S/390 (WSim) as a successor product.

## History

* Teleprocessing Network Simulator (TPNS) Version 1 Release 1 (V1R1) was introduced as Program Product 5740-XT4 in February 1976, followed by four additional releases up to V1R5 (1981).$^{:29–30}$
* In August 1981, IBM announced TPNS Version 2 Release 1 (V2R1) as Program Product 5662-262, followed by three additional releases up to V2R4 (1987).$^{:30–31}$
* In January 1989, IBM announced TPNS Version 3 Release 1 (V3R1) as Program Product 5688-121, followed by four additional releases up to V3R5 (1996).$^{:31–32}$
* In December 1997, IBM announced a TPNS V3R5 Service Level 9711 Functional and Service Enhancements release.
* In September 1998, IBM announced the TPNS Test Manager (for TPNS V3R5) as a usability enhancement to automate the test process further in order to improve productivity through a logical flow, and to streamline TPNS-based testing of IBM 3270 applications or CPI-C transaction programs.
* In December 2001, IBM announced a TPNS V3R5 Service Level 0110 Functional and Service Enhancements release.
* In August 2002, IBM announced Workload Simulator for z/OS and S/390 (WSim) V1.1 as Program Number 5655-I39, a re-packaged successor product to TPNS, alongside the WSim Test Manager V1.1, a re-packaged successor to the TPNS Test Manager.
* In November 2012, IBM announced a maintenance update of Workload Simulator for z/OS and S/390 (WSim) V1.1, to simplify the installation of updates to the product.
* In December 2015, IBM announced enhancements to Workload Simulator for z/OS and S/390 (WSim) V1.1, providing new utilities for TCP/IP data capture and script generation.

## Features
### Simulation support
#### Teleprocessing Network Simulator (TPNS)

TPNS supports the simulation of a wide range of networking protocols and devices: SNA/SDLC, start-stop, BSC, TWX, TTY, X.25 Packet Switching Network, Token Ring Local Area Networking, and TCP/IP servers and clients (Telnet 3270 & 5250, Telnet Line Mode Network Virtual Terminal, FTP and simple UDP clients). TPNS can also simulate devices using the Airline Line Control (ALC) and the HDLC protocols. The full implementation of SNA in TPNS enables it to simulate all LU types (including LU6.2 and CPI-C), PU types (including PU2.1), and SSCP functions. Finally, TPNS also provides extensive user exit access to its internal processes to enable the simulation of user-defined (home-grown) line disciplines, communications protocols, devices (terminals and printers) and programs.
TPNS is therefore the appropriate test tool for installations that need to test:
* either the entire system configuration path of hardware and software components, from the teleprocessing line interface (modem, for example) all the way to the subsystem (CICS, IMS, DB2, TSO/ISPF, etc.), the application and finally to the file or database record (disk I/O) and back;
    Note: In this configuration, TPNS transmits its generated data traffic from its MVS address space, first across a channel-adapter to its TPNS Control Program (TPNCP) running in a dedicated IBM 37x5 Communications Controller, and then across teleprocessing lines connected back-to-back between the TPNCP and the target IBM 37x5 channel-attached to the host system (server) under test and its subsystems, applications and databases/files.
* or only application systems and their hardware and software components, from the networking access method API (either the VTAM API or the TCP/IP High Performance Native Sockets, or Macro, API) to the subsystem (CICS, IMS, DB2, TSO/ISPF, etc.), the application and finally to the file or database record (disk I/O) and back;
    Note: In this configuration, TPNS transmits its generated data traffic from its MVS address space to the target application directly across the networking access method's API and does not, therefore, require a dedicated IBM 37x5 Communications Controller to run its TPNCP, or any other networking hardware and software components except the networking access method (VTAM or IBM TCP/IP for MVS) that already runs in—or is already network-connected to—the host system (server) under test.
* or both.

#### Workload Simulator for z/OS and S/390 (WSim)

WSim fully supports a subset of TPNS-simulated devices and programmed resources: CPI-C,$^{:61–72}$ TCP/IP servers and clients (Telnet 3270 & 5250, Telnet Line Mode Network Virtual Terminal, FTP and simple UDP clients),$^{:91–108}$ and SNA LU simulation.$^{:73–87}$ WSim relies solely on software interfaces to communicate with the system under test.
WSim is therefore the appropriate test tool for installations that need to test application systems and their hardware and software components, from the networking access method API (either the VTAM API or the TCP/IP High Performance Native Sockets, or Macro, API) to the subsystem (CICS, IMS, DB2, TSO/ISPF, etc.), the application and finally to the file or database record (disk I/O) and back; that is to say, without the need to install any networking hardware and software components except the networking access method (VTAM or IBM TCP/IP for MVS) that already runs in—or is already network-connected to—the host system (server) under test.

#### Other uses

In addition to its use as a test tool exchanging message traffic with a system under test, TPNS/Wsim has been deployed:
* as a systems management tool — to monitor the availability of an online system, from the end-user's perspective;$^{:361–433}$
* as a software development tool — for prototyping software programs during the development process.

### Scripting languages
#### TPNS language

TPNS initially provided its own 'TPNS language', a high-level, macro assembler-like language with programming statements and operands that a test programmer would use to define:
* the configuration of the network device(s) to be simulated (NTWRK definitions, simply called the network),$^{:11–60}$ typically one or more terminal(s), such as IBM 3270 display screen(s);
* one or more message text script(s) (MSGTXT definitions, simply called scripts),$^{:109–230}$ corresponding to the keystrokes and data transmission activity of the simulated user(s) at the simulated terminal(s). Separate scripts could be written to perform specific test scenarios, such as: 'login', 'data enquiry', 'data entry' and 'logout', for example;
* the sequence in which scripts are to be executed by each (or all) simulated terminal(s):
** in the NTWRK, one or more PATH statement(s) define(s) the order in which MSGTXTs are executed,$^{:52}$
** each NTWRK terminal has a PATH operand that names the PATH statement(s) assigned to the terminal.$^{:69,93,100}$
Once defined, these test scripts are executed during the simulation run, when the TPNS program ITPENTER (the simulator) processes the submitted statements and creates data streams in the required formats and protocols, prior to sending them to the system under test as if they had originated from real user(s) operating real terminal(s). In turn, the target application(s) running in the system under test respond(s) to the simulated terminal(s) and, if the simulation is successful, these exchanges would continue until the programmed scripts reach the end of the simulation run—i.e., when the simulated users have all completed their scripted activity and logged off, for example—at which time ITPENTER is terminated by the test programmer.
During the simulation, ITPENTER keeps a log (on tape or disk) of all messages exchanged between the simulated device(s) and the real application(s) under test. After the simulation has completed, the test programmer can therefore run any of three TPNS-supplied log analysis utilities to list and review the data exchanges in detail (ITPLL),$^{:31–86}$ to calculate and print response times reports (ITPRESP),$^{:147–172}$ or to compare the 3270 screen images logged during two simulation runs of the same script(s) and report on differences between them (ITPCOMP).$^{:87–146}$
When TPNS was re-packaged and renamed 'WSim' in 2002, the term 'TPNS language' was changed to 'WSim language' in the product publications; however, the existing nomenclature was maintained and all TPNS components re-packaged into WSim—such as the TPNS program names and message numbers (ITPxxxxx), for example—retained their existing identity.

#### Structured Translator Language (STL)

With TPNS V3R1 (1989), IBM added the Structured Translator Language—or 'STL', a TPNS high-level scripting language with a syntax based on REXX—to make it easier for test scripts to be written by programmers familiar with REXX or similar structured programming languages.$^{:231–564}$ STL therefore made it possible to write test scripts, not only for the usual activity of simulated terminal operators, but also for exchanges between TPNS-simulated programs and real application programs or, for example, to prototype elements of an ATM shared network. Scripts written in STL must be translated into the TPNS language before the simulation run and a translator utility (ITPSTL) is supplied for that purpose.
Another way of defining STL would be as a 'script generation language'; its programming clauses are identical to REXX, but they need to be translated (i.e. 'script-generated') into the TPNS language in order to be executable during the simulation run.

#### Script coding facilities

Both scripting languages provide a comprehensive set of coding facilities that enable the test programmer to:
* specify the input data entered by the simulated user(s), along with related actions: counting down think time delays, pressing keys to send data, then waiting for responses from the application under test;$^{:107–136}$
* logic-test the content of incoming and/or outgoing messages and taking one of a wide range of optional actions according to the results of the evaluation;$^{:165–194,92–95}$$^{:27–41,150–164,217}$
* set up test verification clauses that create log records for 'predicted good'/'predicted bad' conditions;$^{:176–177}$
* group message text data in user data tables, to make scripts more generic and data-independent;$^{:88–89,121–125}$
* invoke an extensive range of data field options, to create test data dynamically into messages;$^{:118–119}$$^{:199–207}$
* collect real-time data into save areas, during the simulation run, to re-use as 'on the fly' test data;$^{:129–136}$
* generate random numbers;$^{:119–120}$
* maintain a wide range of counters and switches;$^{:202–209}$
* set up events to synchronise the activity of simulated users;$^{:209–217}$$^{:24,28,145,151,172,194,303–304,433}$
* set up named queues to provide a queuing method for passing data between simulated resources;$^{:76–79}$
* perform sequential file I/O (QSAM) operations from a script to a user-defined, external dataset;$^{:87–91}$
* select script debugging facilities, including a message generation trace (MSGTRACE) which logs the step-by-step flow of all logic tests, actions (taken and ignored), and data exchanges occurring during the execution of scripts;$^{:87}$$^{:19–30}$
* log message traffic during the simulation run,$^{:90–92}$ for post-processing analysis (including message generation tracing, data transmitted/received, printing screen images, test data verification, response time calculation, and screen image comparison across repeated simulations of the same scripts);
* define and alter the rate at which message traffic is generated during the simulation run;$^{:86–90,173–184}$
* specify the protocols for session initiation and termination between simulated programmed resources and real programs, as well as for data exchanges between them;$^{:26–56}$
* and many more.
WSim supports the same scripting language facilities as TPNS, except that its network configuration (NTWRK) definitions require only those statements provided for CPI-C, TCP/IP servers and clients (Telnet 3270 & 5250, Telnet Line Mode Network Virtual Terminal, FTP and simple UDP clients), and SNA LU simulation.

#### Syntax checking preprocessor

The simulator program ITPENTER can also be run as a preprocessor (when submitted with parameter PARM='PREP'), simply to check the syntax of networks and scripts before they are submitted for a simulation run. This enables test personnel to ensure that a subsequent simulation run will not fail because of coding errors in the scripts themselves.$^{:11–24}$

#### Repeatability

One of the benefits of using test scripts is that they can be run repeatedly throughout the test cycle, as functional errors in the application under test and/or system-wide defects are gradually resolved over time, in order to improve the reliability, capacity or performance of any, or all, hardware or software components in the system under test. For functional and regression testing, test programmers would typically define a network of just one simulated terminal executing test scripts tailored to evaluate a comprehensive set of transactions (database enquiry or data entry) serially, and at slow or average rates of message traffic. For system testing, performance/capacity testing, stress testing and benchmarking, the same test programmers would define large networks of dozens or even thousands of simulated terminals, each running—for example—a range of these functional test scripts, now grouped together to exercise as many system components as possible at high rates of message traffic.$^{:17–24}$

### Script generation

TPNS provides a number of solutions to automate the creation of test scripts. The script generation facilities described in the next three sections are also available in Workload Simulator for z/OS and S/390 (WSim).

#### The Interactive Data Capture (IDC) script generator (ITPIDC)

The Interactive Data Capture (IDC) script generator$^{:175–212}$ is a 'pass-through & data intercept' VTAM application (ITPIDC) controlled by the test programmer from one real 3270 display screen in session with a target application for which a script is required. ITPIDC maintains two SNA sessions simultaneously: a primary LU session with the real 3270 terminal operated by the test programmer, and a secondary LU session with the target application. During the data capture–or 'recording'–session, ITPIDC logs the data traffic exchanged between the test programmer's real 3270 device and the target application, and then uses that log to generate the equivalent script, in either of the two scripting languages (TPNS language or STL).
Since the IDC log dataset is in exactly the same format as the log dataset TPNS creates during a simulation run, it can be used as input to the TPNS post-processing utilities to print its contents, to calculate response times of the IDC session, or to compare the screen images of the data capture session with the TPNS log obtained by running the IDC-generated script.

#### The 3270 trace reformatter and script generator (ITPLU2RF & ITPLSGEN)

When capturing the activity of a production network consisting of one or many 3270 devices, the 3270 trace reformatter and script generator$^{:213–230}$ processes the trace dataset produced by the IBM Network Performance Monitor (NPM V1R4 or later) VTAM PIU log (FNMVLOG), or by the IBM VTAM (V4R1 or later) Full Buffer Trace. When the tracing activity is completed, a utility (ITPLU2RF) reformats the trace dataset into a log dataset in the format required as input to the IDC script generator (see previous section), which can also create scripts in batch mode (ITPLSGEN). This reformatted IDC log can also be analyzed by the three post-processing utilities (list the log's contents, calculate response times or compare screen images).

#### The script generator (ITPSGEN)

The script generator$^{:231–269}$ processes the trace dataset produced by the IBM Network Performance Monitor (NPM), or by the IBM VTAM Buffer Trace in conjunction with the IBM Generalized Trace Facility (GTF), when tracing a production network of one or many 3270 devices, as well as devices of various types and protocols, including LU0, LU1, LU2, LU4, LU 6.2 and CPI-C resources. For CPI-C script generation, it is also possible to use the LU 6.2 trace dataset created by the OS/2 Communications Manager (CM/2) or the IBM Communications Server. Different TPNS-supplied utilities reformat any of these various trace datasets into a single-format dataset used as input to the script generator (ITPSGEN), which produces scripts:
* optionally in either language (TPNS language or STL) for all supported device types except CPI-C programmed resources;
* only in STL for CPI-C programmed resources.$^{:309}$

#### The TCP/IP script generator (ITPIPGEN)

The TCP/IP script generator$^{:277–282}$ is unique to WSim and was introduced in December 2015. It processes a TCP/IP trace dataset produced by the WSim-supplied TCP/IP Trace Utility (ITPIPTRX),$^{:167–170}$ which invokes the z/OS Communication Server real-time, application-controlled TCP/IP trace Network Management Interface (NMI) to capture TCP/IP data trace records. These trace records contain HTTP messages (packets and data) exchanged between a server and client. The TCP/IP script generator (ITPIPGEN) then processes this trace dataset and creates a script, in the STL language, which replicates the communication that occurred between the server and client. After translation from STL into the WSim language and when running the simulation (ITPENTER), the generated script sends the client messages—obtained from the trace—to the server port, and waits to receive a message from the server.$^{:277}$ A separate utility (ITPIPFMT)$^{:171–172}$ is also supplied to format and print the contents of the trace dataset created by the TCP/IP Trace Utility (ITPIPTRX).

#### The TPNS Test Manager

It is established practice that a script obtained from a script generator is subsequently edited by test programmers in order to make such scripts more generally reusable. This editing process consists in adding advanced script-programming clauses that script generators cannot supply, such as re-locating hard-coded data into user data tables that can then be expanded with more test data, for example. This editing can be done directly into the NTWRK and MSGTXT datasets, or through the services of the TPNS Test Manager (or its affiliated WSim Test Manager) which, like TPNS (and WSim), also runs under TSO/ISPF. The Test Manager is a knowledge-based, interactive usability tool designed to boost the productivity of test personnel, and to optimize the test cycle by enabling test projects to be organized methodically during the development and execution of test cases, and in the subsequent analysis of test results.

### Run-time interfaces
#### Operator commands

Once the TPNS program ITPENTER (the simulator) has been submitted for execution and is up and running,$^{:66–70}$ test personnel can use a range of TPNS-specific operator commands to initialise, start, alter, and stop the execution of one or more TPNS networks and their associated scripts.$^{:99–116}$ It is also possible to query the activity of a simulated device and its current script,$^{:103–111}$ and to intervene in real time, by altering the rate of message traffic, for example.$^{:113–114}$

#### Running as a MVS procedure

In its early releases, ITPENTER ran as a MVS procedure controlled from the MVS operator console.$^{:91–93}$ Its generated data traffic was transmitted from its MVS address space, first across a channel-adapter to its TPNS Control Program (TPNCP) running in a dedicated IBM 37x5 Communications Controller, and then across teleprocessing lines connected back-to-back between the TPNCP and the target IBM 37x5 channel-attached to the host system under test and its application subsystems (CICS, IMS, DB2, TSO/ISPF, etc.).

#### Running under TSO

With TPNS V1R5 (1979), ITPENTER was enhanced to run from a TSO command list (in the TSO user address space) and therefore to operate simulations from a remote display terminal in the VTAM network instead of the MVS system console.$^{:30}$

#### Running as a VTAM application

With TPNS V2R3 (1985), ITPENTER was enhanced to run as a VTAM application, thus sending the data traffic generated by its simulated terminals or programmed resources (now defined as VTAM logical units) via the VTAM API to the application under test.$^{:30}$ This removed the requirement for a 37x5 and other dedicated teleprocessing hardware when using TPNS to test applications systems running under VTAM, such as CICS, IMS, DB2, ISPF, and other online transaction processing systems.

#### Display Monitor

With TPNS V2R4 (1987), ITPENTER was enhanced with the Display Monitor, so that the screen images of a simulated 3270 display could be externalized onto a real 3270 terminal, thus enabling test personnel to monitor the ongoing, live execution of a script during the simulation run, in real time. It also became possible to operate TPNS from the NetView console and, in turn, to automate TPNS simulation runs from NetView by means of TPNS-supplied NetView command lists.$^{:31}$

#### Running under ISPF

With TPNS V3R3 (1992), all TPNS programs and utilities (ITPxxxxx) could be operated entirely from ISPF in a panel-driven fashion, instead of through the TSO command line or through discrete JCL job streams.$^{:32}$

#### Running as a TCP/IP for MVS application

With TPNS V3R5 (1997), ITPENTER was enhanced to run as a TCP/IP for MVS application, thus sending the data traffic generated by its simulated terminals and/or programmed resources (clients) to the application(s) (servers) under test via the IBM TCP/IP V3R2 for MVS High Performance Native Sockets (HPNS) API, subsequently renamed 'the Macro API'.$^{:17–28}$

#### TPNS Test Manager

In 1998, IBM introduced the Test Manager for TPNS V3R5 which added substantial automation features that streamline many repetitive tasks associated with planning, preparing, operating and analyzing a TPNS-based simulation run, while still enabling the test programmer optionally to retain full awareness, in real-time, of the events unfolding at every step and to intervene if necessary.

### Post-processing utilities

During the simulation, ITPENTER keeps a log (on tape or disk) of all messages exchanged between the simulated device(s) and the real application(s) under test. After the simulation has completed, the test programmer can therefore run any of three TPNS-supplied log analysis utilities.

#### Log list (ITPLL)

The log list utility (ITPLL) is used to list and review the logged data in detail, including operator commands, data transmitted and received, screen images, message generation tracing, and test data verification.$^{:25–61}$

#### Response time calculator (ITPRESP)

The response time calculator (ITPRESP) is used to calculate and print response times reports.$^{:107–149}$

#### Log compare (ITPCOMP)

The log compare utility (ITPCOMP) is used to compare the 3270 screen images logged during two simulation runs of the same script(s) and report on differences between them.$^{:63–106}$

### Additional facilities
#### The Echo program (ITPECHO)

The Echo program (ITPECHO)$^{:151–159}$ is supplied with TPNS (and WSim) as a ready-made VTAM application that runs in the system under test as a target for messages sent by real or simulated 3270 display device(s). Using ITPECHO enables network connectivity and load testing to be carried out without the need to set up a copy of a production-level application and its databases, thereby saving test personnel the effort of writing scripts or allocating disk space for such an application and its datasets. As its name implies, ITPECHO will return exactly the message it has just received (when sent with the 'Enter' key), but it can also return the amount of data that was requested in the previous message (when sent with the 'PF5' key), from real or simulated display device(s). The latter feature is useful for creating test conditions where the 'send' and 'receive' messages need to be of different and variable lengths. To provide the amount of data requested, ITPECHO pads its message with as many occurrences of the alphabet as necessary, or a fraction of it if the amount of data requested in less than 26 characters.

#### The AVailability MONitor (AVMON) facility

Rather than applying TPNS as a test tool, AVMON (AVailability MONitor)$^{:319–367}$ is a TPNS implementation designed to monitor the availability and performance of real network subsystems running in production (NetView and TSO). The TPNS-supplied sample AVMON scripts monitor only NetView and TSO, but a user installation may add support for monitoring more subsystems (CICS, IMS, DB2, etc.) and any of their applications, by modifying or extending the AVMON scripts, perhaps through the use of the Interactive Data Capture script generator mentioned above to create the new script(s). During the TPNS simulation run, AVMON updates the TPNS log dataset, which can therefore be processed by the three TPNS log analysis utilities (log list, response times calculator and log compare).
AVMON monitors availability by simulating a single terminal user in session with a real subsystem, periodically sending a brief probing message, and sensing when the subsystem becomes unavailable. When the simulated user detects unavailability, it sends a message to the operator console alerting the operator to the problem. AVMON also tracks the time it takes for the monitored subsystem to return a response, and reports whenever a user-specified performance threshold is exceeded. By using the TPNS Response Time utility, the performance statistics of the entire monitoring run can be compiled into a single report, thus providing an installation with evidence of the end-to-end response times experienced by the subsystem's end-users. For automated operations, AVMON may also be modified to perform operator functions when it senses that a real resource has become inoperative and therefore requires an operator intervention, such as restarting the resource for example.

## Publications library
### Teleprocessing Network Simulator (TPNS) library

* TPNS Samples SC30-3454
* TPNS Operation SC30-3289
* TPNS Messages and Codes SC30-3310
* TPNS General Utilities SC30-3290
* TPNS Script Generating Utilities SC30-3453
* TPNS Planning and Installation SH20-2488
* TPNS Language Reference SH20-2489
* Defining TPNS Networks SC31-6008
* Creating TPNS Message Generation Decks SC31-6009
* Using TPNS Structured Translator Language (STL) and STL Translator SC31-6013
* TPNS STL Reference Card SX75-0065
* TPNS User Exits SC31-6071
* TPNS Licensed Program Specifications GH20-5323
* TPNS General Information GH20-2487
* TPNS Primer SC31-6043
* TPNS Master Index GC31-6059
* TPNS Function and Service Enhancements V3R5 (1997) SC31-8654-00
* TPNS Function and Service Enhancements V3R5 (2001) SC31-8654-02

### Workload Simulator (WSim) library

* Creating Workload Simulator Scripts SC31-8945
* Workload Simulator Script Guide and Reference SC31-8946
* Workload Simulator Utilities Guide SC31-8947
* Workload Simulator User's Guide SC31-8948
* Workload Simulator Test Manager User's Guide and Reference SC31-8949
* Workload Simulator User Exits SC31-8950
* Workload Simulator Messages and Codes SC31-8951