Save Screen (QsnSavScr) API

The Save Screen (QsnSavScr) API saves the current state of the display. If this is a direct operation, the API creates a command buffer that contains the operations used to restore the screen state and returns a handle for this buffer. When a direct save screen operation is issued, the saved screen data is returned in a command buffer. This command buffer contains the Restore Screen command along with the data to restore the screen. Additional commands can be added to the command buffer as described in Restrictions under the Restore Screen (QsnRstScr) API. The screen can be restored by sending this command buffer using the Put Command Buffer (QsnPutBuf) API.

When an indirect save screen operation is issued, the Save Screen command is stored in the command buffer and is considered an input operation. The command can be issued to the screen only through the Put Command Buffer and Perform Get (QsnPutGetBuf) API. The saved data will be returned in the input buffer parameter specified for the QsnPutGetBuf API. The screen can subsequently be restored by specifying this input buffer on the QsnRstScr API.

This command corresponds directly to the 5250 Save Screen (when the underlying control unit supports it) or Save Partial Screen command. See the 5250 data stream documentation for details.

Authorities and Locks

None

Restrictions

This command must be the last command in the command buffer, except when GUI support is available. In this case, other non-input commands may follow.

Omissible Parameter Group

Saved data command buffer handle

OUTPUT; BINARY(4)

The variable that will contain the command buffer handle for the restore screen operation if this is a direct operation.

For an indirect operation, the result of the save screen will be returned in the input buffer of a subsequent input operation, which can be used to restore the screen using the QsnRstScr operation.

Command buffer handle

INPUT; BINARY(4)

If this parameter is omitted or specified as 0, this is a direct operation and the screen is saved immediately. Otherwise, this is an indirect operation and the command is stored in the command buffer without an I/O operation taking place.

Low-level environment handle

INPUT; BINARY(4)

The low-level environment that the operation applies to. If this parameter is omitted or given with a value of zero, the default low-level environment is used.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter. If this parameter is omitted, diagnostic and escape messages are issued to the application.

Returned Value

Saved data

OUTPUT; BINARY(4)

For a successful operation, this API returns the value for the saved data parameter if this is a direct operation; otherwise, it returns zero. For an unsuccessful operation, it returns -1.

Error Messages