Macro commands

Connect

The Connect() method connects a user to a host session through HostFront Server.

Function Prototype

BOOL Connect(BSTR sUserName, BSTR sPassword)

This method attempts to allocate a new host session under the account defined by the given privileges.

•

If parameter sUserName is null, the ActiveX macro will use the last valid sign on user ID (the last successful sing on / connect that is still active (the browser is still open))

•

To disconnect the allocated session, you should call Disconnect(). You must call Connect() before using any other method. This method returns one of the following:

1.

TRUE if the operation is successful

2.

FALSE if the operation is not successful

Example

HFDISPLAY.Connect "GUEST", "Password"

In this example, the Connect() method attempts to allocate a new host session to the "Guest" account.

Note

Use this command only if you are authenticated using UserID/Password authentication. If you are using the other authentication methods (Windows domain, RSA), do not use it.

Disconnect

The Disconnect() method closes the current host session.

Function Prototype

BOOL Disconnect()

The Disconnect() method disconnects the session from the host before the script ends. You connect sessions using the Connect() method. This method returns one of the following:

1.

TRUE if the operation is successful

2.

FALSE if the operation is not successful

Example

HFDISPLAY.PushKey [PF3]

HFDISPLAY.Disconnect

In this example, the macro disconnects the active session after exiting (usually by PF3) the application.

GetBuildNoHF

This method returns the build number of the ActiveX control or the server depending on the parameter passed: a 0 returns the ActiveX control build number, a 1 return the server build number.

Function Prototype

STR GetBuildNoHF(boolean bServer)

Example

Version = HFDISPLAY.GetBuildNoHF(1)

Returns 20031003 for example

GetCursorColumnPos

The GetCursorColumnPos() method returns the column on which the cursor is currently positioned on the host screen.

Function Prototype

intGetCursorColumnPos();

Example

nCol = HFDISPLAY.GetCursorColumnPos();

GetCursorRowPos

The GetCursorRowPos() method returns the row on which the cursor is currently positioned on the host screen.

Function Prototype

int GetCursorRowPos();

Example

nRow = HFDISPLAY.GetCursorRowPos();

GetField

The GetField() method returns the data in the given field location on the host screen.

Function Prototype

BSTR GetField(int nRow, int nCol1, [int nCol2])

This method returns a string of the characters located at the field specified by nRow and nCol1 position. The information returns as a 32-bit character pointer (BSTR).

By specifying nCol2 as greater than zero, the GetField() method returns the information until it reaches the second column or the end of the field, whichever is shorter. If you do not want to specify an nCol2 position and get the whole field back, put (-1) in the place of nCol2.

Examples

SystName = HFDISPLAY.GetField(2, 70,-1)

In this example, the GetField() method returns the field starting at row 2 and column 70 till the end of the filed and stores it in the SystName variable.

UserName = HFDISPLAY.GetField(6, 20, 26)

In this example, the GetField() method returns the string at row 6 between columns 20 and 26 and stores it in the UserName variable.

GetFieldLength

The GetFieldLength() method returns the maximum length (in characters) of the field at given location on the current host screen.

Function Prototype

int GetFieldLength(int nRow, int nCol);

Example

nMaxLen = HFDISPLAY.GetFieldLength(2, 70);

GetHostScreenHeight

This method returns the screen height of the current screen.

Function Prototype

short GetHostScreenHeight()

Example

ScreenWidth = HFDISPLAY.GetHostScreenHeight()

GetHostScreenWidth

This method returns the screen width of the current screen.

Function Prototype

short GetHostScreenWidth()

Example

ScreenWidth = HFDISPLAY.GetHostScreenWidth() ()

GetRowData

The GetRowData() method returns the data from an entire row on the host screen.

Function Prototype

BSTR GetRowData(int nRow)

This method returns the information from a row identified by nRow. The information is returned as a 32-bit character pointer (BSTR).

Example

Row1 = HFDISPLAY.GetRowData(1)

In this example, the GetRowData() method returns all the characters on row 1 and stores them in the Row1 variable.

GetServerInfo

The GetServerInfo() method is used to retrieve active/configured session information from the server.

Function Prototype

long GetServerInfo (int nInfoType)

Example

nRet = HFDISPLAY.GetServerInfo (0)

nInfoType Returned Value

0: Server load as a percentage ( is calculated by multiplying the number of current sessions by 100 and dividing the product by the maximum number of concurrent sessions)

1: User load as a percentage ( is calculated by multiplying the number of users connected by 100 and dividing the product by the total number of users defined)

2: Maximum number of concurrent sessions

3: Number of sessions currently used

4: Total number of users defined in the server profile

5: Number of users currently connected

GetStatusLine

This method returns the text displayed in the status bar of the active screen.

Function Prototype

BSTR GetStatusLine()

Example

StausLineText = HFDISPLAY.GetStatusLine()

GetUserName

This method returns the user name used to sign on to the server. The method returns the last user name used as stored in the profile file even if you are not currently signed on.

Function Prototype

STR GetUserName();

Example

UserName = HFDISPLAY.GetUserName()

GetUserPassword

This method returns the password used to sign on to the server. If you are not currently signed on, the method returns an empty string.

Function Prototype

STR GetUserPassword();

Example

UserName = HFDISPLAY.GetUserPassword ()

GetVersionHF

This method returns the version number of the ActiveX control or the server.

Function Prototype

short GetVersionHF(boolean bServer)

If the parameter passed is a 0, the method returns the ActiveX control version number and if it was a 1, it returns the server version number.

Example

Version = HFDISPLAY.GetVersionHF(0)

Returns 695 for example (for a 6.9.5 release of the ActiveX Display control)

IsAlphaField

The IsAlphaField() method checks if the field at given location on the current host screen is accepting only letters and some separator characters.

Function Prototype

BOOL IsAlphaField(int nRow, int nCol);

Example

bRtn = HFDISPLAY.IsAlphaField(6, 53);

IsConnected

The IsConnected() method checks if the session is currently connected to a the host.

Function Prototype

BOOL IsConnected()

Example

if HFDISPLAY.isconnected()= FALSE then HFDISPLAY.Connect "Guest", "password"

IsEditableField

The IsEditableField() method checks if the field at given location on the current host screen is editable or not.

Function Prototype

BOOL IsEditableField(int nRow, int nCol);

Example

bRtn = HFDISPLAY.IsEditableField(6, 53);

IsKbdLocked

The IsKbdLocked() method checks to see if the keyboard is locked (input inhibited). The host will lock the keyboard when it is processing data or when there is an error such as when numeric data is entered into a text-only field.

Function Prototype

BOOL IsKbdLocked()

This method returns one of the following:

1.

TRUE if the keyboard is locked

2.

FALSE if the keyboard is not locked

Example

bRtn = HFDISPLAY.IsKbdLocked()

IsNonDisplayField

The IsNonDisplayField() method checks if the field at given location on the current host screen is protected (i.e. used to input a host password).

Function Prototype

BOOL IsNonDisplayField(int nRow, int nCol);

Example

bRtn = HFDISPLAY.IsNonDisplayField(7, 53);

IsNumericField

The IsNumericField() method checks if the field at given location on the current host screen is a numeric field. Data in a numeric fields can include digits and some separator characters such as /,+,- and space. For details on valid data on numeric fields please check the appropriate IBM documentation.

Function Prototype

BOOL IsNumericField(int nRow, int nCol);

Example

bRtn = HFDISPLAY.IsNumericField(6, 53);

IsReverseField

The IsReverseField() method reverses the background and foreground colors of a host screen field. For example, if the background is white and the foreground is black, then the background becomes black and the foreground becomes white.

Function Prototype

BOOL IsReverseField (int nRow, int nCol) ;

Example

bRtn = HFDISPLAY.IsReverseField (7, 53);

PrintDisplayScreen

The PrintDisplayScreen() method performs a print screen function to the specified printer. It is equivalent to the Print Screen button on the toolbar. It has two parameters, one to define whether or not to print the header and footer information, and the second to define the target printer.

Function Prototype

BOOL PrintDisplayScreen (int HeaderFooter, Str PrinterPath) ;

Parameters

HeaderFooter:	0: Print the header and footer 1: Do not print the header and footer
PrinterPath:	The string defining the printer path. It must be enclosed between double quotes. If left empty (" "), the printing is directed to the default printer.

Example

HFDISPLAY.PrintDisplayScreen 0, "\\printer\HP6"

PushKey

The PushKey() method simulates a key input.

Function Prototype

BOOL PushKey (int nKey)

The PushKey() method is used to simulate a single key input to the host. A key is referred to by name. This method returns one of the following:

1.

TRUE if the operation is successful

2.

FALSE if the operation is not successful

The available keys are listed below (for both 5250 and 3270 together):

Attention	Dup	Latin	PF4	PF19
Auto_Reverse	End	LightPen_Selection	PF5	PF20
Backspace	Enter	NewLine	PF6	PF21
BackTab	Erase_EOF	NumPad_Comma	PF7	PF22
Base	Erase_Input	NumPad_Dot	PF8	PF23
Calc_Rev_Mode	Field_Base	NumPad_Slash	PF9	PF24
Clear	Field_Exit	NumPad_Star	PF10	Print
Cursor_Down	Field_Mark	PA1	PF11	Reload
Cursor_Left	Field_Minus	PA2	PF12	Reset
Cursor_Right	Field_Plus	PA3	PF13	Reverse_Push
Cursor_Selection	FieldX	Page_Down	PF14	Screen_Direction
Cursor_Up	Help	Page_Up	PF15	System_Request
Delete_Char	Hex_Mode	PF1	PF16	Tab
Delete_Left	Home	PF2	PF17	Test_Request
Delete_Right	Insert	PF3	PF18	Toggle_RDE_RTE

Example

HFDISPLAY.PutField 6, 53, UserName

HFDISPLAY.PutField 7, 53, Password

HFDISPLAY.PushKey [ENTER]

In this example, the PushKey() method sends the [Enter] key to the host after the user provides a user name and password. An alternative to PushKey [ENTER] is as follows:

HFDISPLAY.PushKey 32778

The numeric code for the [Enter] key is 0x800A in hexadecimal or 32778 in decimal.

PushKeyStream

The PushKeyStream method simulates keystrokes on the keyboard with letters, numbers and function keys used on one screen all listed one after the other.

Function Prototype

HFDISPLAY.PushKeyStream "string<special key>"

Special keys should always be enclosed between <>. Normal text is typed as is. The whole stream will be enclosed between two double quotes.

This is the list of supported special keys that can be used by name:

Attention	Dup	Latin	PF4	PF19
Auto_Reverse	End	LightPen_Selection	PF5	PF20
Backspace	Enter	NewLine	PF6	PF21
BackTab	Erase_EOF	NumPad_Comma	PF7	PF22
Base	Erase_Input	NumPad_Dot	PF8	PF23
Calc_Rev_Mode	Field_Base	NumPad_Slash	PF9	PF24
Clear	Field_Exit	NumPad_Star	PF10	Print
Cursor_Down	Field_Mark	PA1	PF11	Reload
Cursor_Left	Field_Minus	PA2	PF12	Reset
Cursor_Right	Field_Plus	PA3	PF13	Reverse_Push
Cursor_Selection	FieldX	Page_Down	PF14	Screen_Direction
Cursor_Up	Help	Page_Up	PF15	System_Request
Delete_Char	Hex_Mode	PF1	PF16	Tab
Delete_Left	Home	PF2	PF17	Test_Request
Delete_Right	Insert	PF3	PF18	Toggle_RDE_RTE

Example

HFDISPLAY.PushKeyStream GUEST<TAB>FARABI<ENTER>

This macro assumes the cursor is at the correct position where the username should be entered and that the password field is one TAB move away. In this example we used values directly. In order to use variables, you need to separate the variables from the other keys using simple concatenation as in the following example:

HFDISPLAY.PushKeyStream Username+<TAB>+Password+<ENTER>

PutField

The PutField() method fills fields with data on the host screen.

Function Prototype

BOOL PutField(int nRow, int nCol1, VARIANT vtData)

This method places a constant, or the value of the variable, in the field starting at the specified row and column. This method returns one of the following:

1.

TRUE if the operation is successful

2.

FALSE if the operation is not successful

When using PutField() methods on a host screen, the PushKey(ENTER) method validates your entries and moves on to the next screen.

You can use (-1) for the row and column to have the data entered at the current field.

Example

HFDISPLAY.PutField 6, 53,UserName

HFDISPLAY.PutField 7, 53, Password

HFDISPLAY.PushKey [ENTER]

In this example, the PutField() method enters the values UserName and Password in the user name and password fields of a host sign on screen. Using the -1 parameter, the example becomes as shown below. This however assumes the cursor is currently at the correct field location where the username should be entered and the password field is the next one (after one Tab move).

HFDISPLAY.PutField -1, -1, UserName

HFDISPLAY.PushKey [TAB]

HFDISPLAY.PutField -1,-1, Password

HFDISPLAY.PushKey [ENTER]

ReceiveIndFile

The ReceiveIndFile() method performs an IND$FILE command to transfer a file from the mainframe. For further details, refer to your IND$FILE documentation. This command works only with HostFront for the Mainframe.

Function Prototype

INT ReceiveIndFile (Str MainframeFile, Str PCFile, Str FTOptions, Int Flags)

Parameters

Mainframe File	The full name and path of the file on the mainframe
PCFile	The path and name of the target file on the PC or local network.
FTOptions	Is a string defining additional command option for IND$FILE file transfer. For example, you can use "ASCII CRLF" for TSO environment.
Flags	A total of fixed values defining additional options for the file transfer. There are five groups of values. You have to use one value from each group. The groups are listed below:
	Group 1: Environment Type	TSO = 0 CMS = 16 '0x0010 CICS = 32 '0x0020
	Group 2: Conversion Type	WINDOW_ANSI = 0 DOS_ASCII = 256 '0x0100 BINARY = 512 '0x0200
	Group 3: Over-write/Append	OVERWRITEFILE = 0 APPENDFILE = 4096 '0x1000
	Group 4: Prompt Completion	NOTSHOWMSGBOX = 0 SHOWMSGBOX = 16384 '0X4000
	Group 5: RTL Flipping (Arabic)	NOTFLIP_ARABICDATA = 0 FLIP_ARABICDATA = 8192 '0x2000

Example

HFDisplay.ReceiveIndFile "test(aaa)", "C:\public\ft\aaa.txt", "ASCII CRLF", 16384

SendIndFile

The SendIndFile() method performs an IND$FILE command to transfer a file to the mainframe. For further details, refer to your IND$FILE documentation. This command works only with HostFront for the Mainframe.

Function Prototype

INT SendIndFile (Str MainframeFile, Str PCFile, Str FTOptions, Int Flags)

Parameters

Mainframe File	The full name and path of the file on the mainframe
PCFile	The path and name of the target file on the PC or local network.
FTOptions	Is a string defining additional command option for IND$FILE file transfer. For example, you can use "ASCII CRLF" for TSO environment.
Flags	A total of fixed values defining additional options for the file transfer. There are five groups of values. You have to use one value from each group. The groups are listed below:
	Group 1: Environment Type	TSO = 0 CMS = 16 '0x0010 CICS = 32 '0x0020
	Group 2: Conversion Type	WINDOW_ANSI = 0 DOS_ASCII = 256 '0x0100 BINARY = 512 '0x0200
	Group 3: Over-write/Append	OVERWRITEFILE = 0 APPENDFILE = 4096 '0x1000
	Group 4: Prompt Completion	NOTSHOWMSGBOX = 0 SHOWMSGBOX = 16384 '0X4000
	Group 5: RTL Flipping (Arabic)	NOTFLIP_ARABICDATA = 0 FLIP_ARABICDATA = 8192 '0x2000

Example

HFDisplay.SendIndFile "test(aaa)", "C:\public\ft\aaa.txt", "ASCII CRLF", 16384

SetCursorPos

The SetCursorPos() method places the cursor on the host screen at a specified position.

Function Prototype

BOOL SetCursorPos(int nRow, int nCol)

This method places the cursor at the specific row and column. In some host applications, you may need to position the cursor at a specific location on the host screen before issuing a PushKey() method. This method returns one of the following:

1.

TRUE if the operation is successful

2.

FALSE if the operation is not successful

Example

HFDISPLAY.SetCursorPos 20 , 7

HFDISPLAY.PushKey [PF3]

In this example, the cursor is placed at row position 20 and column 7 before the [PF3] key is sent to the host application.

SignOn

This method is used to sign on to HostFront with the given user name and password.

Function Prototype

boolean SignOn(BSTR sUserName, BSTR sUserPassword)

Example

SignonSuccessful = HFDISPLAY.SignOn(Visitor,Password)

Note

Use this command only if you are authenticated server using UserID/Password authentication. If you are using the other authentication methods (Windows domain, RSA), do not use it.

WaitForCursor

This method causes the macro to be suspended until the cursor is at a specified location on the active screen. If you want to specify a column only use the value -1 for the row (and vice-versa).

Function Prototype

void WaitForCursor (int nRow, int nColumn) ;

Example

HFDISPLAY.WaitForCursor 4,35

WaitForFieldData

The WaitForFieldData method waits for specific data to come to a specific position on the host screen before returning.

Function Prototype

BOOL WaitForFieldData(LPCTSTR szText, int nRow, int nColumn1, int nColumn2, int nTimeout);

This method returns one of the following:

1.

TRUE if the data returns

2.

FALSE if the request times out or an error occurs

Example

HFDisplay.WaitForFieldData “ROCKPROC”, 10,20,27,20000

WaitForText

This method causes the macro to be suspended until the specified text is entered at the specified location. Value -1 can be used for both nRow and nColumn meaning that the text can be anywhere on the active screen.

Function Prototype

void WaitForText (string szText , int nRow, int nColumn)

Example

HFDISPLAY.WaitForText Montreal, -1,-1