IBMlogo
IBM eNetwork Communications Server for Windows NT
Host Publisher Feature, Version 6.01
[Next|Previous|Contents]

Host Publisher Hints and Tips

Macro Syntax

This section covers the detailed syntax of the macro language.
  • Macro Syntax
  • Macro Commands
  • Screen position
  • Screen planes
  • Sending keystrokes
  • Waiting
  • Macro syntax

    Consider the syntax of the macro language; that is, what does a valid macro look like.

    A macro is a sequence of line delimited commands. These commands have the following syntax rules:

    Macro commands

    Because the macro language is based on IBM's Host Access Class Library for Java, all commands look like Java calls, most with object references attached ("ps.SendKeys" instead of just "SendKeys"). The object references don't actually do anything in the macro language; just consider them to be part of the command. In other words, just use "ps.SendKeys" and don't try to use "SendKeys" or "somethingelse.SendKeys".

    Parameters shown in square brackets [] are optional.

    Screen position

    Some macro commands provide two ways of addressing positions in the host presentation space. The macro can address characters by row and column coordinates or by a single linear position value. Addressing is always 1-based (not zero-based) no matter which addressing scheme is used.

    The row and column addressing scheme is related directly to the physical screen presentation of the host data. Row 1 column 1 is in the upper left corner.

    The linear positional addressing method (with position 1 in the upper left corner, progressing from left to right, top to bottom) is useful for viewing the entire presentation space as a single array of data elements.

    For example, on an 80-column screen, linear position 81 is the same as row 2, column 1.

    Note that if the number of characters per row can change, macros that use the row and column technique might be more likely to keep working correctly.

    Screen Planes

    The presentation space consists of a number of planes, each of which contains one type of data. The planes are:

    The planes are all the same size and contain one character for each character position in the host presentation space.

    Sending keystrokes

    Non-text keys are represented by bracketed keywords called mnemonics. For example, to send an Enter keystroke, send "[Enter]". See the appendix Sendkeys Mnemonics Keywords for more information.

    To send a left or right square bracket, the character must be doubled. To send a left square bracket use "[[". To send a right square bracket use "]]".

    ps.SendKeys places keys on the Presentation Space (PS) as though the user had moved the cursor to a position and typed the text.

    Valid commands are:

    ps.SendKeys(String text);
    ps.SendKeys(String text, int position);
    ps.SendKeys(String text, int row, int col);
    

    prompt places text on the screen that is supplied by Host Publisher at run-time, using values from Web forms or session variables.

    prompt(int row, int col, int len, String name, String value, boolean clearField [, String echoChar]);

    Parameters:

    row
    Row in Presentation Space to place text
    col
    Column in Presentation Space to place text

    Set row and col to 0 to place text at the current cursor position.

    len
    Maximum length of text. Use this to guard against skip fields.
    name
    Text to enter, or name of variable.

    If the value given is of the form ":fieldname", Host Publisher attempts to use the value from a Web form parameter named fieldname.

    If the value given is of the form ":[variablename]", Host Publisher attempts to use the value from a session variable named variablename.

    value
    Not used by Host Publisher; just pass "" for this parameter.
    clearField
    Clears the field that the text is placed in if true.
    echoChar
    Echo character for password. Currently, only '*' is used. (Optional. This parameter can be omitted and the text entered is echoed normally.)

    Warning: prompt does not move the cursor. If you want to move the cursor past the text that prompt has placed on the screen, you can use ps.SendKeys("[right][right]") with enough [right] commands to move the cursor past the maximum length of the prompt text.

    Examples:

    prompt(23,8,9,":filename","",true);
    prompt(23,17,8,":filetype","",false);
    prompt(24,8,9,":password","",true,"*");
    ps.SendKeys("[right][right][right][right][right][right][right][right][right]");
    

    These lines in a macro place the values of the Web form parameters "filename" and "filetype" at row 23, column 8 and row 23, column 17, respectively. The first line clears the field first (9 characters starting at 23, 8); the second line does not clear its field first. The third line places a password at row 24, column 8, getting its value from the Web form parameter named password, but will echo "*" characters rather than showing the password on the screen. The fourth line moves the cursor past the password.

    Waiting

    There are three ways to wait:
    1. Wait for input to be enabled
    2. Wait for a specific screen to appear
    3. Wait for the connection to reach a particular state

    Waiting does not last forever. If the condition you are waiting for does not occur, after a period of time, the macro fails, and Host Publisher will report an error on the Web page that is produced.

    Some of the macro commands allow you to specify a timeout period in milliseconds. Others use the default timeout, which you can view in the comments at the end of the macro.

    The macro Time Out field that you can set in the Integrator for the Connect, Data Loop, or Disconnect macro is different; it controls the time allowed for the entire macro to complete.

    Waiting for input to be enabled

    oia.WaitForInput waits for the OIA to enter the "input not inhibited" state. This wait times out when the standard time-out property value is reached (seen in the comments at the end of the Host Publisher macro file).

    Valid commands are:

    oia.WaitForInput(); 
    
    Waiting for a screen
    To wait for a specific screen, build a description of that screen specifying one or more characteristics of the screen.

    screenDesc.Clear clears the screen description. This is the first command to issue when setting up to wait for a screen.

    Valid commands are:

    screenDesc.Clear(); 
    

    screenDesc.AddAttrib adds an attribute for the given row and column position and plane to the screen description.

    Valid commands are:

    screenDesc.AddAttrib(char attr, int row, int col, int plane); 
    

    See the appendix Field attributes for details about field attributes.

    screenDesc.AddCursorPos adds the cursor position at the given row and column position to the screen description.

    Valid commands are:

    screenDesc.AddCursorPos(int row, int col); 
    

    screenDesc.AddNumFields adds the total number of fields to the screen description.

    Valid commands are:

    screenDesc.AddNumFields(int num); 
    

    screenDesc.AddNumInputFields adds the total number of input fields to the screen description.

    Valid commands are:

    screenDesc.AddNumInputFields(int num); 
    

    screenDesc.AddOIAInhibitStatus adds a particular OIA input inhibited status to the screen description. If input is inhibited for more than one reason, it is considered inhibited due to the reason with the highest value in the table below.

    Valid commands are:

    screenDesc.AddOIAInhibitStatus(int type); 
    
    The possible inhibit types are:
    Inhibit Indicator Value OIA String
    INHIBIT_NOTINHIBITED 0  
    INHIBIT_SYSTEMWAIT 1 "X SYSTEM" or "X []"
    INHIBIT_COMMCHECK 2 "X COMMxxx"
    INHIBIT_PROGCHECK 3 "X PROGxxx"
    INHIBIT_MACHCHECK 4 "X MACHxxx"
    INHIBIT_OTHERINHIBIT 5  

    screenDesc.AddString adds the string to the screen description.

    Valid commands are:

    screenDesc.AddString(String text); 
    
    

    screenDesc.AddStringInRect adds the string to appear in the given rectangle to the screen description.

    Valid commands are:

    screenDesc.AddStringInRect(String text, int startRow, int startCol,
                               int endRow, int endCol); 
    screenDesc.AddStringInRect(String text, int startRow, int startCol,
                               int endRow, int endCol, boolean caseSensitive); 
    

    ps.WaitForScreen waits for the screen described by the screen description object to appear in the PS. This is the final command to issue when waiting for a screen.

    Valid commands are:

    ps.WaitForScreen(ECLScreenDesc screenDesc); 
    ps.WaitForScreen(ECLScreenDesc screenDesc, int timeOut); 
    
    screenDesc
    Just put "screenDesc" (without the quotation marks)
    timeOut
    Timeout in milliseconds (optional)

    Examples of waiting for a screen

    // wait for a screen described by its cursor position
    screenDesc.Clear(); 
    screenDesc.AddCursorPos(14,19); 
    ps.WaitForScreen(screenDesc,1000); 
    

    // Wait for a screen described by the number of fields and some text
    screenDesc.Clear(); 
    screenDesc.AddNumFields(128); 
    screenDesc.AddNumInputFields(1); 
    screenDesc.AddString("Directory Record"); 
    ps.WaitForScreen(screenDesc, 5000); 
    
    Waiting for a connection state
    To wait for the connection to reach a particular state, use the waitForConnection() command. Valid commands are:
    waitForConnection(int waitType);
    waitForConnection(int waitType, int timeout);
    

    The possible waitTypes are:

    ECLConnection.CONNECTION_INIT initial state
    ECLConnection.CONNECTION_PND_ACTIVE state immediately following a connect request
    ECLConnection.CONNECTION_ACTIVE connection established
    ECLConnection.CONNECTION_DEVICE_NAME_READY an LU name has been assigned during negotiation
    ECLConnection.CONNECTION_READY connection established and negotiation complete
    ECLConnection.CONNECTION_PND_INACTIVE state immediately following a disconnect request
    ECLConnection.CONNECTION_INACTIVE disconnected

    The timeout is in milliseconds.

    Example macro to wait for logoff to complete:

    ps.SendKeys("logoff[enter]");
    screenDesc.Clear();
    screenDesc.AddCursorPos(23,1);
    ps.WaitForScreen(screenDesc,10000);
    ps.SendKeys("[clear]");
    waitForConnection(ECLConnection.CONNECTION_INACTIVE);
    

    [Next|Previous|Contents]
    IBM eNetwork Communications Server for Windows NT
    Host Publisher Feature, Version 6.01