GetScreen

This method retrieves data from the presentation space of the connection associated with the ECLPS object. The data is returned as a linear array of byte values, one byte per presentation space character position. The array is not null terminated except when data is retrieved from the TextPlane, in which case a single null termination byte is appended.

The application must supply a buffer for the returned data, and the length of the buffer. If the requested data does not fit into the buffer it is truncated. For TextPlane data, the buffer must include at least one extra byte for the terminating null. The method returns the number of bytes copied to the application buffer (not including the terminating null for TextPlane copies).

The application must specify the number of bytes of data to retrieve from the presentation space. If the starting position plus this length exceeds the size of the presentation space an error is thrown. Data is returned starting at the given starting position or row 1, column 1 if no starting position is specified. Returned data is copied from the presentation space in a linear fashion from left to right, top to bottom spanning multiple rows up to the length specified. If the application wants to get screen data for a rectangular area of the screen, the GetScreenRect method should be used.

The application can specify any plane for which to retrieve data. If no plane is specified, the TextPlane is retrieved. See ECL Planes — Format and Content for details on the different ECL planes.