Updated and reviewed, October 2010
xcall MIAMEX, MX_CLIPBOARD, opcode, text {,status {,srow, scol, erow, ecol}}
MX_CLIPBOARD allows you to retrieve or set the text contents of the clipboard.
Parameters
opcode (Num) [in]
|
Value |
Description |
|
0 |
Retrieve clipboard text contents |
|
1 |
Set clipboard text either from screen coordinates (if non-zero) or from text parameter |
|
2 |
Same as 0 but applies to ATE client |
|
3 |
Same as 1 but applies to ATE client |
|
5 |
Mark area specified by coordinates |
Note that in non-ATE A-Shell/UNIX environments, opcode 0 and 1 will simulate clipboard operations by reading/writing to a file MEM0:<job>.CLP[1,1] if the file exists. If it does not exist, status will be set to -1 (same as if the Windows clipboard could not be opened).
text (String) [in/out]
will receive the clipboard text contents for opcode 0 and 2. For opcode 1 and 3, if you want to specify a string containing the text to copy to the clipboard, then put it in the text parameter and do not specify the srow, scol, erow, and ecol parameters (or set them to 0). Otherwise, if you want to copy a rectangular area of the current screen to the clipboard, then specify the coordinates in the last four parameters, in which case text will be ignored. The maximum effective size for text is about 3K.
status (F,6) [out] optional
|
Value |
Description |
|
0 |
Success |
|
-1 |
Unable to open clipboard; locked? |
|
-2 |
Clipboard can be opened but not read, or there is no text available in the clipboard |
|
-3 |
Unable to lock memory |
|
-4 |
Invalid coordinates |
srow,scol,erow,ecol (Num) [in]
Optional coordinates used with opcodes 1, 3 to specify the screen area to be copied to the clipboard. (Set them all to 0 in order to load the clipboard from the text parameter instead of the screen.) For opcode 5, they specify the screen area to be marked. Ignored for all other opcodes.
Notes
• In non-Windows, non-ATE environments (e.g. A-Shell/UNIX with a non-GUI client), opcodes 0 and 1 will simulation clipboard operations by reading/writing to a file MEM0:<job>.CLP[1,1] if the file exists. If it does not exist, status will be set to -1 (same as if the Windows clipboard could not be opened.)
• Other than the non-GUI A-Shell/UNIX case just mentioned, you can safely used opcodes 2 and 3 in place of 0 and 1 (i.e. add +2) without regard to whether the configuration involves ATE or some other Windows architecture (standalone, peer-to-peer, Terminal Server, etc.)
History
2010 November, A-Shell 5.1.1194: Limits removed on buffers controlling clipboard size. Buffers now auto-expand, making size of clipboard objects unlimited.
2009 September, A-Shell 5.1.1159: Routine modified to support returning data into dynamic variables, such that they expand as needed. Previously, the output data was being truncated to the current size of the variable, or 0 for uninitialized.
2009 February, A-Shell 5.1.1139: Prior to this release, the amount of text that could be copied to the clipboard was limited to about 3K. While this remains the case when copying from screen coordinates, or when running under ATE (opcodes 2 and 3), for opcodes 1 and 3 in local Windows mode (copying a string supplied by the application), the amount is now only limited by available Windows resources.