TN3270 terminal emulation testing

The TN3270 protocol is the foundation of IBM mainframe green-screen terminal access. When your CICS or IMS transactions are accessed through a terminal emulator rather than a web or API interface, performance testing them requires a tool that speaks TN3270 at the protocol level — filling fields, sending attention keys, and waiting for the host to respond, exactly as a real user would. The JMeter RTE plugin provides this capability. This page covers how to author a realistic TN3270 load test in JMeter and run it at scale through MaxoPerf.

Before you start

• Read JMeter plugins for mainframe to understand how to install the RTE plugin in JMeter Desktop and how MaxoPerf uses it.
• You need a TN3270 server accessible from MaxoPerf runners — either the mainframe IP/hostname directly or via a TN3270 gateway (such as IBM’s z/OS Communications Server port, or a third-party gateway).
• Coordinate with your mainframe operations team to confirm the test window, authorized VU count, and MIPS headroom available.

Understanding TN3270 load testing

The green-screen transaction model

A TN3270 green-screen transaction follows a fixed pattern:

1. A user connects to the TN3270 server and reaches a sign-on panel.
2. The user enters credentials and presses Enter (AID key).
3. The host processes the input, renders a new panel, and transmits it to the terminal.
4. The user navigates to the target application (e.g., CICS CESN → application menu → transaction).
5. The user fills one or more fields and presses Enter or a PF key to submit the transaction.
6. The host responds with a result or confirmation panel.
7. The user reads the result, optionally navigates to the next step, and repeats.

Each complete cycle from submission to response is one transaction, and its elapsed time is the metric you care about.

What the RTE sampler measures

The JMeter RTE sampler measures end-to-end elapsed time for each action sequence you configure. It starts timing when it sends the AID (attention key) that submits the screen, and stops timing when the configured wait condition is satisfied (for example: wait for the host to UNLOCK the keyboard, or wait for a specific string to appear at a specific screen position). This closely models the user-perceived response time for that transaction.

Configuring the RTE sampler

Connection setup

Add an RTE Config element at the Thread Group level to share the connection settings across all samplers in the group:

• Server — the TN3270 hostname or IP (the mainframe LPAR or TN3270 gateway).
• Port — commonly port 23, but often a dedicated non-standard port on a gateway. Confirm with your mainframe team.
• Protocol — select TN3270 for IBM Z workloads (use TN5250 for IBM i / AS/400).
• Terminal type — IBM-3278-2 is the most common 3270 model 2 (24x80 screen). Use the model your application was tested against.
• SSL/TLS — enable if your TN3270 gateway requires an encrypted connection (TELNET SSL).

Structuring a transaction as RTE actions

Each RTE sampler represents one screen interaction. Within a sampler, you define a sequence of actions:

Action type	What it does
Fill	Places a string value into a specific screen field (by coordinates or by field index)
Send keys	Sends an AID (attention identifier) key: ENTER, CLEAR, or PF1–PF24
Wait for	Halts the sampler until a condition is met before recording the response time

A typical login-and-transaction sequence uses multiple RTE samplers chained in a Thread Group:

1. Sampler: Connect and sign on — fill the User ID field, fill the Password field, send ENTER, wait for keyboard UNLOCK.
2. Sampler: Navigate to transaction — fill the command field with the CICS transaction code (e.g., ACCT), send ENTER, wait for the account inquiry panel text.
3. Sampler: Submit transaction — fill the account number field, send ENTER, wait for the result panel.
4. Sampler: Sign off — send the sign-off command, send ENTER, wait for disconnect.

Wait conditions

The wait condition is critical for accurate timing and test stability. The three most commonly used wait types in the RTE plugin are:

• Wait for UNLOCK — waits until the keyboard is no longer inhibited (the host has finished processing). This is the most reliable general-purpose condition.
• Wait for text — waits until a specific string appears at a specific row/column position on the screen. Use this to confirm you have reached the expected panel before continuing.
• Wait for cursor — waits until the cursor moves to a specific position, which some applications use to signal readiness for input.

Combine wait conditions

For robust tests, combine wait-for-text and wait-for-UNLOCK: wait for UNLOCK first (the host is done processing), then assert that the expected panel text is present. If the text is missing, the assertion fails rather than the sampler continuing with an incorrect panel state.

Assertions on screen content

Add a Response Assertion to each RTE sampler to verify the host returned the expected panel. The RTE sampler exposes the screen content as the response body (plain text, 24×80 characters). Assert on a substring that is unique to the correct response panel — for example, the panel title or a field label. If the host returns an error panel instead, the assertion fails and the sampler is counted as an error in MaxoPerf’s results.

Think time and pacing

Real users pause between actions. Add Constant Timer or Gaussian Random Timer elements between samplers to model the think time. A common CICS terminal user think time is 3–8 seconds between panel submissions. Without think time, your VU model will apply far more load per VU than real users generate, leading to an unrealistic test.

See Ramp-up, think time, and pacing for general guidance.

Running the test in MaxoPerf

1. In JMeter Desktop, complete your test plan with the RTE Config, sampler chain, assertions, and timers. Remove all listener elements (View Results Tree, Summary Report) — they add overhead and MaxoPerf does not use them.

2. Validate the plan locally: run it for 1–2 minutes with a single thread against your test LPAR to confirm all panels load and assertions pass.

3. Save the plan as cics-tn3270-load.jmx.

4. In the MaxoPerf console, open your test → Files tab.

5. Upload cics-tn3270-load.jmx. MaxoPerf marks it as Entrypoint and sets the engine to JMeter.

6. Upload any CSV data files (account numbers, user IDs) as Test assets, using the same relative filenames the JMX references.

7. Click Run.

Reading the results

After the run, MaxoPerf’s Overview tab shows:

• Throughput — transactions per second (RPS). For a TN3270 test, this is the number of screen submissions per second across all VUs.
• p95 latency — the 95th percentile response time for each sampler. Compare against your SLA for that transaction.
• Error rate — the percentage of sampler executions that resulted in an assertion failure or a connection error. Any non-zero error rate deserves investigation: it may indicate CICS is rejecting sessions, returning error panels, or the TN3270 gateway is throttling connections.
• Per-sampler breakdown — the Overview tab’s endpoint panel shows each named RTE sampler separately (sign-on, transaction submit, etc.), so you can see which step in the flow is the latency bottleneck.

Connection limits

TN3270 servers have a finite number of configured terminal sessions. If your VU count exceeds the session limit on the LPAR, new connections will be refused and you will see connection errors — not application performance data. Confirm the session limit with your mainframe team before setting your VU count.

Do / don’t

Do:

• Use meaningful sampler names (Sign on, Submit ACCT inquiry, Sign off) — they appear in MaxoPerf’s per-endpoint breakdown and make results readable.
• Model realistic think times. Terminal transactions have natural pauses; removing them will over-stress the LPAR.
• Assert on screen text in every sampler — catching error panels is as important as measuring response time.
• Start with a low VU count (5–10) and confirm the session flow is clean before scaling up.

Don’t:

• Run against production LPARs without explicit sign-off from mainframe operations. TN3270 sessions consume MIPS.
• Omit think time — raw TN3270 hammering without pauses is not a realistic model and will exceed normal MIPS expectations quickly.
• Skip local validation. TN3270 panel layouts are fragile; a field coordinate off by one row causes silent data corruption rather than an obvious error.

Where to go next

• CICS/IMS transaction testing — transaction response time metrics, think time, and transaction mix.
• JMeter plugins for mainframe — the RTE plugin install reference and plugin ecosystem overview.
• Daily mainframe scenarios — how to apply TN3270 tests to real workload patterns like morning peak and month-end batch.
• Mainframe do and don’t — coordination, MIPS cost, and authorization rules.