Snap() action

From The x3270 Wiki

The Snap() action is a wrapper around other scripting actions that causes them to operate on a fixed buffer (the snap buffer) rather than using the live screen. The reason for this is to get a consistent picture of what is on the screen at a particular point in time.

For example, a script using the plain Ascii1() action could read one region of the screen. Between that and another call to Ascii1() to read another region, the host could completely redraw the screen with different data, causing the script to get inconsistent results.

By using Snap(), the script can capture the screen image once, then interrogate parts of that image multiple times, without needing to worry that the image might change while it is reading it. Then it can use Snap(wait,output) to wait for the host to update the screen.

Parameters

Unique parameters

save
Saves a snapshot of the screen buffer in the snap buffer.
status
Returns the s3270 prompt line from the last call to Snap(save).
rows
Returns the number of rows in the snap buffer.
cols
Returns the number of columns in the snap buffer.
wait,[timeout,]output
Waits for the host to write more data to the screen, since the last call to Snap(save).

Wrappers around screen-reading actions

Ascii[,arg...]
Runs the Ascii() action with the specified arguments, operating on the snap buffer.
Ascii1[,arg...]
Runs the Ascii1() action with the specified arguments, operating on the snap buffer.
Ebcdic[,arg...]
Runs the Ebcdic() action with the specified arguments, operating on the snap buffer.
Ebcdic1[,arg...]
Runs the Ebcdic1() action with the specified arguments, operating on the snap buffer.
ReadBuffer[,arg...]
Runs the ReadBuffer() action with the specified arguments, operating on the snap buffer.

Example

This is pseudo-code for the classic Snap() loop.

// At the top of the loop, wait for the host to change the screen.
// Snap(wait,output) will fail if the host disconnects.
while Snap(wait,output) {
  // Save a snapshot in the Snap buffer.
  Snap(save)
  ... interrogate the buffer using Snap(ascii1) ...
}