Copy Presentation Space to String

Copy Presentation Space to String – Function 8

This function copies all or part of the Host session presentation space into a string buffer.

Prerequisite functions

Connect Presentation Space (function 1)

Function call

WinHLLAPI(COPYPSTOSTR,lpbyString,lpwLength,lpwReturnnCode)

Call parameters

Parameter	Description
Data String	String that will contain the specified portion of the Host session presentation space.
	Note If the EAB option is set under Set Session Parameters (9) to include extended attribute bytes in the copy, the string must be defined as at least twice the size of the presentation space that is copied.
Data Length	Number of characters.
PS Position	Position in the Host session presentation space where the copying is to begin. Must be greater than zero and less than or equal to the maximum size of the Host session presentation space.

Return parameters

Parameter	Description
Data String	String containing the specified portion of the Host session presentation space.

Return code

Code	Description
WHLLOK	The specified portion of the Host session presentation space successfully copied to Data String; the session is active and the keyboard is unlocked.
WHLLNOTCONNECTED	Your Windows HLLAPI application is currently not connected to a session.
WHLLPSBUSY	The specified portion of the Host session presentation space successfully copied to Data String; the session is waiting for a Host response.
WHLLINHIBITED	The specified portion of the Host session presentation space successfully copied to Data String; the keyboard is locked.
WHLLPOSITIONERROR	PS Position value specified is invalid.
WHLLSYSERROR	The function failed due to a system error.

Remarks

PS Position in the Host session presentation space is determined by starting in the upper left corner of the screen display (row 1, column 1). At the end of each screen display row, the next Host session presentation space position is column 1 of the following screen display row. This process continues until the end of the Host session presentation space (screen display) is reached.

Character translation from EBCDIC to ASCII is performed by the Copy Presentation Space to String function. The translation depends on the setting of the following session options:

Session option	Effect of this function
NOATTRB	Unknown values are translated into spaces.
ATTRB	Unknown values are copied untranslated.
NOEAB	Extended attribute bytes are not copied to the string.
EAB, XLATE	Extended attribute bytes are copied and translated into CGA colors
EAB, NOXLATE	Extended attribute bytes are returned.
DISPLAY	Data in non-display fields is copied to the target buffer.
NODISPLAY	Data in non-display fields is copied as null characters to the target buffer.