# Automation API and wnd-automate for Scripts | WND Software Docs

Source: https://wndsoftware.com/docs/automation-api

### Automation API and wnd-automate

Programs the person runs on the same computer can drive WND Terminal’s open sessions. They read the screen, type, press keys and wait for the host, much as EHLLAPI programs do with other emulators.

The WND Terminal desktop app listens on a named pipe on Windows and a local socket on a Mac or Linux. Programs that the same person runs on that computer send it requests, and the `wnd-automate` command sends one request each time it runs, so any script can use it. Programs written for another emulator’s EHLLAPI or COM objects use it through WND Terminal’s [EHLLAPI DLLs, COM objects and .NET library](https://wndsoftware.com/docs/ehllapi-com), without changes. IT can turn the API off with `AllowAutomation` = false.

On a small screen, swipe the table to read all columns.


| What | Detail |
| --- | --- |
| Where it runs | The desktop app on Windows, Mac and Linux. The browser version doesn’t have it. |
| Windows address | The named pipe `\\.\pipe\wnd-terminal-<user>`, open to that Windows user only |
| Mac and Linux address | The socket `/tmp/wnd-terminal-<uid>/automation.sock`, in a folder only that user can open |
| Who can connect | Programs run by the same person on the same computer. Never other users, and never other computers. |
| Sessions | Mainframe (3270), IBM i (5250), UNIX and Linux (VT), and Unisys, HP, Tandem and airline sessions |
| Turned off by | `AllowAutomation` = false |


### Sessions and their short names

Each open session gets a letter from A to Z, in the order it opened. The status line shows it while the API is on, such as Session A . A session keeps its letter while it stays open, like an EHLLAPI presentation space ID. Programs can also use the connection’s name, such as `Production`.

Rows and columns count from 1, as in EHLLAPI. Screen text comes back as Unicode, one character for each position.


### Script with wnd-automate

`wnd-automate` sends one request each time it runs. Any language that can start a program can use it, including PowerShell, a batch file or a shell script.

It’s installed with WND Terminal. On Windows it’s `wnd-automate.exe` in the app’s folder, such as `C:\Program Files\WND Terminal`. On a Mac it’s inside the app, at `/Applications/WND Terminal.app/Contents/MacOS/wnd-automate`.


```text
wnd-automate list
wnd-automate A wait-text "Logon ===>" 20
wnd-automate A keys "wnduser@E"
wnd-automate A wait-ready 10
wnd-automate --json A fields
```

On a small screen, swipe the table to read all columns.


| Command | What it does |
| --- | --- |
| `list` | Lists the open sessions with their short name, name, host type and size. |
| `open NAME [SECONDS]` | Opens a saved connection and waits for it to connect. |
| `SESSION status` | Shows the host type, size, cursor, keyboard and connection. |
| `SESSION text [ROW COL LENGTH]` | Prints the screen, or part of it. |
| `SESSION keys KEYS` | Types text and presses keys written as EHLLAPI SendKey codes. |
| `SESSION type TEXT` | Types the text exactly as it is. An `@` is just an `@`. |
| `SESSION put ROW COL TEXT` | Puts text into the input fields from that position. |
| `SESSION fields`, `SESSION field ROW COL` | Lists the fields on the screen, or describes one. |
| `SESSION cursor [ROW COL]` | Shows where the cursor is, or moves it. |
| `SESSION search TEXT` | Prints the row and column where the text starts. |
| `SESSION wait-ready [SECONDS]` | Waits until the host has answered and the keyboard is free. |
| `SESSION wait-text TEXT [SECONDS]`, `wait-gone` | Waits until the text appears, or until it has gone. |
| `SESSION close` | Closes the session and its tab. |
| `call OP [JSON]` | Sends any request and prints the answer as JSON. |

Add `--json` to get WND Terminal’s answer as JSON. The exit code tells a script what happened.

On a small screen, swipe the table to read all columns.


| Exit code | Meaning |
| --- | --- |
| 0 | Done. |
| 1 | WND Terminal refused or couldn’t do it. The reason is on standard error. |
| 2 | The command line is wrong. |
| 3 | WND Terminal isn’t running, or its automation API is off. |
| 4 | A wait ran out of time. |
| 5 | `search` found nothing. |


### A logon script

This shell script opens the saved connection called Production, logs on to TSO and saves the screen to a file.


```text
set -e
wnd-automate open Production 60
wnd-automate Production wait-text "Logon ===>" 30
wnd-automate Production keys "@0${TSO_USER}@E"
wnd-automate Production wait-ready 30
wnd-automate Production text > screen.txt
```

This PowerShell example clears the screen and lists its input fields.


```text
wnd-automate A keys "@C"
wnd-automate A wait-ready 10
$fields = (wnd-automate --json A fields | ConvertFrom-Json).fields | Where-Object { -not $_.protected }
$fields | Format-Table row, col, length, text
```


### Keys

Keys are written the way EHLLAPI’s SendKey writes them. `"wnduser@E"` types `wnduser` and presses Enter.

On a small screen, swipe the table to read all columns.


| Code | Key |
| --- | --- |
| `@E` | Enter |
| `@T`, `@B` | Tab, Back Tab |
| `@1` to `@9` | PF1 to PF9 |
| `@a` to `@o` | PF10 to PF24 |
| `@x`, `@y`, `@z` | PA1, PA2, PA3 |
| `@C` | Clear |
| `@R` | Reset |
| `@F` | Erase EOF |
| `@0` | Home |
| `@A@E` | Field Exit |
| `@@` | The `@` character itself |

WND Terminal checks the whole string before it types anything. A code it doesn’t know, or a key it doesn’t have, is refused with the key’s name. After Enter or another key that goes to the host, it waits for the answer before it types the rest. So `"@ETSO@E"` works as it would for a person at the keyboard.


### Writing your own client

Programs can also talk to the pipe or socket directly. Each message is one JSON object on one line. The first request must be `hello`, and every request carries an `id` that comes back in the answer.


```text
→ {"id":1,"op":"hello","version":1,"client":"logon"}
← {"id":1,"ok":true,"result":{"app":"WND Terminal","protocol":1,"can_open":true}}
→ {"id":2,"op":"wait_text","session":"A","text":"Logon ===>","timeout":20}
← {"id":2,"ok":true,"result":{"found":true,"row":3,"col":1,"pos":161}}
→ {"id":3,"op":"keys","session":"A","keys":"jsmith@E"}
← {"id":3,"ok":true,"result":{"sent":2,"keyboard_locked":true}}
```

Each EHLLAPI function has a request that does the same job.

On a small screen, swipe the table to read all columns.


| EHLLAPI function | Request |
| --- | --- |
| Connect Presentation Space, Query Session Status | `status` |
| Send Key | `keys` |
| Wait | `wait_ready` |
| Copy Presentation Space, Copy Presentation Space to String | `text` |
| Search Presentation Space | `search` |
| Query Cursor Location, Set Cursor | `cursor`, `set_cursor` |
| Query Sessions | `list` |
| Reserve, Release | `reserve`, `release` |
| Copy OIA | `status` |
| Query Field Attribute, Find Field Position, Find Field Length, Copy Field to String | `field` |
| Copy String to Presentation Space | `put` |
| Copy String to Field | `put_field` |
| Query Host Update, Pause | `updates`, `wait_update` |
| Keystroke intercept, Send File, Receive File | Not available |


### File transfer requests

`file_list`, `file_get`, `file_put`, `job_submit` and `job_output` use a saved site of the [file transfer client](https://wndsoftware.com/docs/file-transfer) (FTP, FTPS or SFTP), without a session. Each request connects, does one thing and closes. The site’s password goes with the request and is never kept or logged. The organization’s file transfer rules apply, and every transfer is in the audit log as done by a program.


### Programs written for other emulators

WND Terminal comes with EHLLAPI and WinHLLAPI DLLs (32-bit and 64-bit, under the names programs load), COM objects with the Extra!, PCOMM and Reflection object models, and the .NET library `WndTerminal.Automation`. They all use the requests on this page, so programs written for another emulator keep working without changes, under the same rules. IT turns them on with MSI properties. See [EHLLAPI, COM and .NET](https://wndsoftware.com/docs/ehllapi-com). The [Migration readiness report](https://wndsoftware.com/migration-readiness-report) lists scripts that drive an emulator, so you know which ones to test.


### What programs can’t do

- Read hidden fields.  Password fields always read as blanks. Programs can type into them.
- See masked values.  Card numbers and IT’s `MaskPatterns` are masked in everything a program reads, and a search can’t find them by their real digits.
- Read the screen when copying is off.  With `AllowCopy` = false, programs can’t read the screen’s text. They can still search and wait for text.
- Get round the policy.  Connections a program opens go through the license and IT’s connection rules like any other.
- Type over someone.  A program can reserve a session’s keyboard, and the person is told why their typing is refused. While Fill from Excel or Ask WND is typing in a session, programs can’t type there.
- See what the person types.  There’s no keystroke intercept. What a program types isn’t kept as recent typing or recorded into a macro.


### Turning it off, and the audit log

The API is on unless IT turns it off. Set `AllowAutomation` to false, or enable Turn off the automation API (EHLLAPI-style scripting)  in Group Policy. Nothing then listens, and About WND Terminal says your organization turned it off. A policy that can’t be read turns it off too. See [Policy settings](https://wndsoftware.com/docs/policy-settings).

The audit log records each program that connects (`automation.attach`) and disconnects (`automation.detach`), with its program name and process ID. Keys and reads aren’t recorded. See [Audit log to Splunk and Sentinel](https://wndsoftware.com/docs/audit-log-splunk-sentinel).

For routines a person runs from the keyboard, a [macro](https://wndsoftware.com/docs/macros) is usually simpler. Macros run inside WND Terminal, in the desktop app and in a browser.


### Questions


#### Does WND Terminal include an EHLLAPI DLL?

Yes. It ships EHLLAPI and WinHLLAPI DLLs in 32-bit and 64-bit, under the names PCOMM, Extra! and Reflection programs load, plus COM objects and a .NET library. IT copies and registers them at install with MSI properties.


#### Can a script read passwords from the screen?

No. Password fields always read as blanks, and card numbers and IT's patterns are masked in everything a program reads.


#### Can a program on another computer drive WND Terminal?

No. On Windows the pipe refuses connections from other computers and other users. On a Mac or Linux the socket sits in a folder only that user can open.


#### How do we turn the automation API off?

Set AllowAutomation to false in Group Policy, Intune, a Mac configuration profile or policy.json. Nothing listens after that, and About WND Terminal says so.

Look up an exact code in the [online error reference](https://wndsoftware.com/mainframe-errors/), including [CICS abends](https://wndsoftware.com/mainframe-errors/cics-abends), [Db2 SQLCODEs](https://wndsoftware.com/mainframe-errors/db2-sqlcodes) and [MQ reason codes](https://wndsoftware.com/mainframe-errors/mq-reason-codes).

Technical reviewer: [Albert Joseph](https://wndsoftware.com/authors/albert-joseph), WND Software.