Tivoli Service Desk 6.0 Developer's Toolkit Interface Designer Guide
At the current cursor position, clears the field, then types in the given string, truncating to length if given.
conn : EMUCONNECTION str : STRING EXPRESSION length: INTEGER EXPRESSION
Parameter | Description |
conn | Connection must be initialized with EMUConnect. |
str | String to be placed in the current field. |
length | Optional. Maximum length of the field Input string may be truncated to fit. |
INTEGER
The string is typed in at the current cursor position. The final position of the cursor is located after the last character of the string, just as if a user had typed the string at a keyboard. This function performs the task equivalent to calling EMUPressKey with $EMUClear, then calling EMUTypeIn.
VARIABLES rc :INTEGER; conn :EMUCONNECTION; str :STRING; ACTIONS rc := EMUConnect(conn, 'A'); -- conn is associated with session A now IF (rc < 1) THEN -- error handling ELSE str := 'HELLO WORLD!'; rc := EMUClrTypeIn(conn,str); IF (rc < 1) THEN -- error handling END; EMUDisConnect(conn); -- frees resources for conn. END; END;
Initializes an EHLLAPI connection, making active the terminal session specified by sessName.
conn : EMUCONNECTION sessName: STRING EXPRESSION
Parameter | Description |
conn | This handle is initialized with various terminal attributes. Do not pass the handle to EMUConnect more than once in an application, unless you want the previous initialization of the handle to be overwritten. |
sessName | The Communications Manager terminal session short name (typically 'A,' 'B,' 'C,' for 3270 terminal sessions). This terminal session must start in Communications Manager before the call to EMUConnect. |
INTEGER
This command must be executed before the connection handle pass to another EHLLAPI command.
VARIABLES rc :INTEGER; conn :EMUCONNECTION; str :STRING; ACTIONS rc := EMUConnect(conn, 'A'); -- conn is associated with session A now IF (rc < 1) THEN -- error handling ELSE str := 'HELLO WORLD!'; rc := EMUClrTypeIn(conn,str); IF (rc < 1) THEN -- error handling END; EMUDisconnect(conn); -- frees resources for conn. END; END;
Deactivates the connected emulation session, freeing the resources allocated for the connection handle.
conn: EMUCONNECTION
Parameter | Description |
conn | The connection handle to be freed. |
INTEGER
The connection handle is $Unknown after this command executes. The function EMUConnect must be called to re-initialize the connection handle.
VARIABLES rc :INTEGER; conn :EMUCONNECTION; str :STRING; ACTIONS rc := EMUConnect(conn, 'A'); -- conn is associated with session A now IF (rc < 1) THEN -- error handling ELSE str := 'HELLO WORLD!'; rc := EMUClrTypeIn(conn,str); IF (rc < 1) THEN -- error handling END; EMUDisconnect(conn); -- frees resources for conn. END; END;
Reads a string from the terminal screen at the given position with the given length.
conn : EMUCONNECTION row : INTEGER EXPRESSION col : INTEGER EXPRESSION length: INTEGER EXPRESSION inStr : STRING PARAMETER
Parameter | Description |
conn | The connection handle that specifies which session the TSD Script Interpreter should use to get the string. |
row | The row of the terminal screen. Usually, this number is between one and 24. Row one is the top row of the screen. |
col | The column from which to get the characters. Valid columns are usually one through 80. Column one on a text screen is the leftmost column. |
length | The number of characters to copy from the screen. |
inStr | The string into which the data is copied. |
INTEGER
The position of the host cursor is irrelevant in this command. The cursor is not moved by this command. The TSD Script Interpreter can carry this command out even if the session is "busy," (the Input Inhibitor is shown in the OIA).
VARIABLES rc :INTEGER; str :STRING; conn :EMUCONNECTION; ACTIONS rc := EMUConnect(conn,'A'); IF (rc < 1) THEN -- error handling ELSE rc := EMUFillBuffer(conn,1,1,20,str); IF (rc < 1) THEN -- error handling ELSE WinMessageBox($DESKTOP,'FillBuff',$MBOK, 'Row 1, Col 1 '& 'first 20 chars is:'& str); END; EMUDisconnect(conn); END; END;
Reads a text file into the host screen starting at the current cursor position. At the end of each text file line, the specified key code is pressed.
conn : EMUCONNECTION filename: STRING EXPRESSION keycode : INTEGER EXPRESSION
Parameter | Description |
conn | Specifies a connected session which is the target of the input file. |
filename | The name of the text file to be read into the host screen. |
keycode | One of the valid key codes for EHLLAPI. |
This key is pressed after each file line is read into the screen.
INTEGER
VARIABLES rc :INTEGER;
ACTIONS rc := EMUConnect(conn, 'A'); IF (rc < 1) THEN -- error handling ELSE rc := EMUInFile(conn,'EXAMPLE.TXT', $EMUTab); IF (rc < 1) THEN -- error handling END; EMUDisconnect(conn); END; END;
Suppose EXAMPLE.TXT contains:
This is a description. Another line of description. Finally, the third line of description.
If the screen looks like this:
BLGRRR==================================== In===>______________________________________________ 12/12/93
First: __________________ Last: ______________________ Description: _________________________________________ ______________________________________________________ ______________________________________________________ ______________________________________________________ ______________________________________________________
========================================
Assume that the cursor is at the first position of the description.
After the example code executes, you would see:
BLGRRR==================================== In===>______________________________________________ 12/12/93
First: __________________ Last: _____________________ Description: This is a description. Another line of description. Finally, the third line of description. ______________________________________________________ ______________________________________________________
========================================
Downloads a screen of data, as specified by the given map.
conn : EMUCONNECTION mapName : STRING EXPRESSION downloadBuff: ANY
Parameter | Description |
conn | Specifies the session from which data should be downloaded. |
mapName | The name of the map file to be used in the download process. |
downloadBuff | A record structure that contains (at least) the fields named in the map file. The data is read from the position specified in the map and placed into the record field that has the same name as the field name given in the map file. |
INTEGER
Notes
EMUMapDownload replaces the use of many EMUFillBuffer commands as the maps provide a fast way to convert data types to TSD Script types. For instance, if you use EMUFillBuffer to get data from a screen, then all the data is a TSD Script string. You then must convert the data one field at a time.
For TIME, DATE, INTEGER, and REAL types, EMUMapDownload eliminates leading and trailing white space (blanks) from data fields before placing values into record fields. For STRING types, the data is copied as is from the host screen into the record field (similar to EMUFillBuffer).
TYPES SomeRec IS RECORD Name:STRING; Age :INTEGER; END;
VARIABLES rc :INTEGER; rec :SomeRec; conn:EMUCONNECTION; ACTIONS rc := EMUConnect(conn, 'A'); IF (rc < 1) THEN -- error handling ELSE rc := EMUMapDownload(conn,'EX1.MAP',rec); IF (rc < 1) THEN -- error handling ELSE -- do something with data in rec now. END; EMUDisconnect(conn); END; END;
Assume that EX1.MAP contains:
*FIELDS NAME 5 12 10 SYSFORMAT DEFAULT_FORMAT AGE 6 6 3 SYSFORMAT DEFAULT_FORMAT
Suppose that the host screen looks like:
========================================
FULL NAME: Jon Rigsby AGE: 18
========================================
Given the conditions in the example, after the EMUMapDownload executes, the rec variable would have the name Jon Rigsby and the age 18.
Uploads a screen-full of data, as specified by the given map file.
conn : EMUCONNECTION mapName : STRING EXPRESSION uploadBuff: ANY
Parameter | Description |
conn | Specifies the session to which data should be uploaded. |
mapName | Specifies the name of a map file which determines the placement and conversion of data during an upload. |
uploadBuff | The variable that contains data to be uploaded to the screen. The type of this var may be either a simple TSD Script type (TIME, DATE, INTEGER, STRING) or a user defined record type. |
INTEGER
If a value is $Unknown during upload, the field is skipped.
TYPES SomeRec IS RECORD first:STRING; last :STRING; age :INTEGER; bday :DATE; END;
VARIABLES rc :INTEGER; conn:EMUCONNECTION; rec :SomeRec; ACTIONS rc := EMUConnect(conn, 'A'); IF (rc < 1) THEN -- error handling ELSE rec.first := 'John'; rec.last := 'Doe'; rec.age := 30; rec.bday := {8/6/1963}:DATE; rc := EMUMapUpload(conn, 'EX1.MAP', rec); IF (rc < 1) THEN -- error handling END; EMUDisconnect(conn); END; END;
Assume EX1.MAP contains:
*FIELDS FIRST 3 14 10 SYSFORMAT DEFAULT_FORMAT LAST 4 12 20 SYSFORMAT DEFAULT_FORMAT AGE 5 6 3 SYSFORMAT DEFAULT_FORMAT BDAY 6 13 10 SYSFORMAT DEFAULT_FORMAT
Suppose the host screen looks like:
========================================
FIRST NAME: __________ LAST NAME: ____________________ AGE: ___ BIRTH DATE: __________
========================================
After EMUMapUpload executes successfully, the host screen looks like this:
========================================
FIRST NAME: John LAST NAME: Doe AGE: 30 BIRTH DATE: 08/06/1963
========================================
Moves the host cursor to the given row and column.
conn: EMUCONNECTION row : INTEGER EXPRESSION col : INTEGER EXPRESSION
Parameter | Description |
conn | Identifies the terminal session in which the cursor is to be moved. |
row | The row of the host screen to which the cursor should be moved. The top row of the screen is row one. |
col | The column to which the cursor should be moved. Column one is the leftmost column on the host screen. |
INTEGER
The cursor cannot be moved when the host displays Input Inhibited. A row or column that is out of range returns an error code.
VARIABLES rc :INTEGER; conn:EMUCONNECTION; ACTIONS rc := EMUConnect(conn, 'A'); IF (rc < 1) THEN -- error handling ELSE rc := EMUMoveCursorTo(conn, 10, 10); IF (rc < 1) THEN -- error handling ELSE EMUClrTypeIn(conn, 'THIS STARTS AT POSITION 10,10'); END; EMUDisconnect(conn); END; END;
Dumps a rectangular portion of the host screen (defined by the coordinates given) to the named file.
conn : EMUCONNECTION filename: STRING EXPRESSION topRow : INTEGER EXPRESSION leftCol : INTEGER EXPRESSION botRow : INTEGER EXPRESSION rightCol: INTEGER EXPRESSION
Parameter | Description |
conn | Specifies the terminal session from which to capture the text portion. |
filename | The name of the file to which the text should be dumped. If the file already exists, the new data replaces the previous. If the file does not exist, it is created. |
topRow | The host row that is the top row of the rectangular portion of text. |
leftCol | The terminal column number that is the last column on the left of the text written to the file. |
botRow | The row of the host screen that is the bottom row of the rectangular portion of text. |
rightCol | The host column that serves as the rightmost column of the rectangular portion of text. |
INTEGER
If file does not exist when this command executes, then the file is created. If it does exist, the new data is appended to the end of it.
VARIABLES rc :INTEGER; conn:EMUCONNECTION; msg :STRING; ACTIONS rc := EMUConnect(conn, 'A'); IF (rc < 1) THEN -- error handling ELSE rc := EMUFillBuffer(conn, 3, 1, 5, msg); IF (rc < 1) THEN -- error handling ELSE IF (msg = 'ERROR') THEN -- capture the screen to a file EMUOutFile(conn, 'ERRFILE.TXT',1,1,24,80); END; END; EMUDisconnect(conn); END; END;
Presses the control key specified by a key code. Key codes can be one of the TSD Script system defined integers ($EMUClearKey, $EMUEnter).
conn : EMUCONNECTION keycode: INTEGER EXPRESSION
Parameter | Description |
conn | Identifies the terminal session where key presses should be sent. |
keycode | The key to be pressed. |
INTEGER
Keys cannot be pressed when the host displays Input Inhibited.
VARIABLES rc :INTEGER; conn:EMUCONNECTION;
ACTIONS rc := EMUConnect(conn, 'A'); IF (rc < 1) THEN -- error handling ELSE rc := EMUPressKey(conn, $EMUPF3); IF (rc < 1) THEN -- error handling ELSE EMUClrTypeIn(conn, 'JON_R'); EMUPressKey(conn, $EMUTab); EMUClrTypeIn(conn, 'mypasswd'); rc := EMUPressKey(conn, $EMUEnter); IF (rc < 1 ) THEN -- error handling, login failed. END; END; END; END;
Gets the current host cursor position.
conn : EMUCONNECTION row : INTEGER PARAMETER col : INTEGER PARAMETER
Parameter | Description |
conn | Specifies the terminal session from which to get the cursor position. |
row | The row in which the cursor is positioned at the time of execution of this command. |
col | The column in which the host cursor is positioned. |
INTEGER
VARIABLES rc :INTEGER; conn:EMUCONNECTION; r,c :INTEGER; ACTIONS ... EMUPressKey(conn,$EMUEndKey); EMUQueryCursor(conn,r,c); IF (c > 59) THEN EMUPressKey(conn, $EMUTab); END; EMUTypeIn(conn,'Is this on new field?');
END;
Returns the size of the screen in text rows and columns.
conn: EMUCONNECTION row : INTEGER PARAMETER col : INTEGER PARAMETER
Parameter | Description |
conn | Specifies the terminal session for which to get the size. |
row | This parameter gets the height of the host screen. |
col | Contains the number of columns in the host screen. |
INTEGER
VARIABLES rc :INTEGER; conn:EMUCONNECTION; r,c :INTEGER; ACTIONS ... -- at this point in the code, you decide -- that you need to capture the entire host screen to a file. EMUQuerySession(conn, r, c); EMUOutFile(conn,'ERRFILE.TXT',1,1,r,c); END;
Scans the terminal session for the specified string. If found, it returns the starting position of the string in row, column format.
conn: EMUCONNECTION row : INTEGER PARAMETER col : INTEGER PARAMETER
Parameter | Description |
conn | The terminal session to be scanned |
row | If the string is found, then this parameter contains the row where the string begins |
col | The column in which the found string begins |
INTEGER
Passing a blank or $Unknown string to EMUScanForString is not a valid function. The scan is also case-sensitive.
VARIABLES rc:INTEGER; conn:EMUCONNECTION; r,c:INTEGER;
ACTIONS ... rc := EMUScanForString(conn,'JON RIGSBY',r,c); IF (rc < 1) THEN IF (rc = -24) THEN WinMessageBox($DESKTOP,'Not Found',$MBOK, 'Did not find '& 'JON RIGSBY'); ELSE -- some other error has occurred END; ELSE WinMessageBox($DESKTOP,'Found',$MBOK,'Found '& 'JON RIGSBY at row '& r &' column '& c); END;
END;
Sets the timeout for any Wait commands that follow this call.
conn : EMUCONNECTION timelimit: INTEGER EXPRESSION
Parameter | Description |
conn | Terminal session for which to set the timeout limit. |
timelimit | Maximum time (in milliseconds) that any of the EMUWait commands waits before it is cancelled. |
INTEGER
The default time limit is 500 milliseconds. The time limit you set with EMUSetWatchTimeLimit is used for all EMUWait commands that follow (for that connection). It is valid to set a time limit of 0. In this case the EMUWait functions return immediately with return codes indicating whether the condition was satisfied.
VARIABLES rc:INTEGER; conn:EMUCONNECTOIN; ACTIONS .. rc := EMUSetWatchTimeLimit(conn,1000); -- 1 second IF (rc < 1) THEN -- error handling ELSE rc := EMUWaitForNoX(conn); END; END;
Types the given string at the current cursor position.
conn : EMUCONNECTION str : STRING EXPRESSION length: INTEGER EXPRESSION
Parameter | Description |
conn | The terminal session in which the string should be typed. |
str | The string to be typed at the current cursor position. |
length | (Optional) Specifies a maximum length for the input string. The string is truncated if it is longer than the allowable length. |
INTEGER
If the input string is blank, the return code is 5008. No characters are typed into the host screen.
VARIABLES rc :INTEGER; conn:EMUCONNECTION;
ACTIONS ... EMUMoveCursorTo(conn, 10,10); EMUTypeIn(conn,'JON RIGSBY',20); EMUPressKey(conn,$EMUTab); EMUTypeIn(conn,'18'); EMUPressKey(conn,$EMUTab); EMUTypeIn(conn,'1901 Niagara Drive',30); rc := EMUPressKey(conn,$EMUEnter); IF (rc < 1) THEN -- error handling END; END;
Pauses the application until the host cursor appears at the designated position, or until the watch time limit expires.
conn: EMUCONNECTION row : INTEGER EXPRESSION col : INTEGER EXPRESSION
Parameter | Description |
conn | Specifies the terminal session on which to wait. |
row | The row position in which the cursor is expected to appear. |
col | The column position in which the cursor is expected to appear. |
INTEGER
VARIABLES rc :INTEGER; conn:EMUCONNECTION; ACTIONS ... EMUPressKey(conn, $EMUPF3); rc := EMUWaitForCursorAt(conn, 1, 5); IF (rc < 1) THEN IF ((rc = 1010) or (rc = 1011)) THEN -- wait gave up ELSE -- error END; ELSE -- continue with normal processing END; END;
Pauses execution until the host cursor is not at the specified position, or until the watch time limit has expired.
conn: EMUCONNECTION row : INTEGER EXPRESSION col : INTEGER EXPRESSION
Parameter | Description |
conn | The terminal connection on which to wait. |
row | The row from which the cursor should disappear. |
col | The column from which the cursor should disappear. |
INTEGER
VARIABLES rc :INTEGER; conn:EMUCONNECTION; ACTIONS ... EMUPressKey(conn, $EMUPF3); rc := EMUWaitForCursorNotAt(conn, 10,10); IF (rc < 1) THEN IF (rc = 1010) THEN -- wait gave up ELSE -- other error END; ELSE -- continue with normal processing END; END;
Pauses execution until the host Input Inhibited indicator disappears from the OIA. If settle time is given, the TSD Script Interpreter ensures that the indicator disappears for the total settle time before returning.
conn : EMUCONNECTION settleTime: INTEGER EXPRESSION
Parameter | Description |
conn | The terminal connection for which to wait. |
settleTime | Optional. The time the TSD Script Interpreter waits after the X disappears, to make sure the X indicator has "settled." |
INTEGER
VARIABLES rc :INTEGER; conn:EMUCONNECTION; ACTIONS ... -- fill in the data on the screen EMUMoveCursorTo(conn, 10, 10); EMUClrTypeIn(conn, 'JON RIGSBY'); EMUPressKey(conn, $EMUTab); EMUClrTypeIn(conn, '1901 Niagara Drive'); EMUPressKey(conn, $EMUTab); EMUClrTypeIn(conn, 'Ontario, Canada'); -- press enter to accept the data EMUPressKey(conn, $EMUEnter); rc := EMUWaitForNoX(conn); IF (rc < 1) THEN IF ((rc = 1011) OR (rc = 1012)) THEN -- wait gave up ELSE -- some other error END; ELSE -- continue normal processing END; END;
Pauses execution until the given search string appears with its first character in the given row and column, or until the watch time limit expires.
conn: EMUCONNECTION str : STRING EXPRESSION row : INTEGER EXPRESSION col : INTEGER EXPRESSION
Parameter | Description |
conn | Terminal connection on which to wait. |
str | The string for which to wait. |
row | The host row in which the string appears. |
col | The column in which the string appears. |
INTEGER
If the search string is blank or $Unknown, an error return code is returned immediately.
VARIABLES rc :INTEGER; conn:EMUCONNECTION; ACTIONS ... EMUPressKey(conn, $EMUPF3); rc := EMUWaitForStringAt(conn,'ENTER YOUR LOGIN NAME:', 3, 5);
IF (rc < 1) THEN IF (rc = 1010) THEN -- wait gave up ELSE -- other general error END; ELSE -- continue normal processing END;
END;
Pauses execution until the given string disappears from the designated host position, or until the watch time limit expires.
conn: EMUCONNECTION str : STRING EXPRESSION row : INTEGER EXPRESSION col : INTEGER EXPRESSION
Parameter | Description |
conn | The terminal connection on which to wait. |
str | The string that disappears from the host screen. |
row | The row from which the string disappears. |
col | The column from which the first character of the string disappears. |
INTEGER
If the search string is blank or $Unknown, an error return code appears.
VARIABLES rc :INTEGER; conn:EMUCONNECTION; ACTIONS ... EMUMoveCursorTo(conn, 10, 10); EMUClrTypeIn(conn,'JONATHAN K. RIGSBY'); EMUPressKey(conn, $EMUEnter); rc := EMUWaitForStringNotAt(conn, 'JONATHAN K. RIGSBY', 10, 10); IF (rc < 1) THEN IF (rc = 1010) THEN -- wait gave up ELSE -- other general error END; ELSE -- continue normal processing END; END;
Tivoli Service Desk 6.0 Developer's Toolkit Legacy APIs Guide