ati§

Delete user-defined variable(s).

Drops one or more user-defined variable(s) or host sessions from memory. DROP will cause the value of a variable to be reset to its name in capital letters. DROP can be used safely on non-GLOBAL variables. Note that statement labels and WHEN labels cannot be dropped. Please see 'DROPPING A GLOBAL VARIABLE' for the consequences of dropping a GLOBAL variable.

(ATI) DROP varname1 [ … ] | SESSION

(python) drop(varname1[,varname2…])

RETURN CODES Not affected

Escape special characters in text.

Return a text string that is an escaped version of the input text string. The input text is treated as if it has no mneumonics and the returned text can be used as input to send without having any of it interpreted as a mneumonic.

Return a text string from the host screen.

Usage/Syntax:

extract({length | EOL}[, location][, wc='*'])

location:
    (r, c) | {FIRST|LAST}, string[, (xr, xc)][, wc='*']

length A numeric value specifying the length of the string to be extracted from the host screen.

EOL Causes the extraction to reach as far as the end of the host screen line where it began.

(r, c) An absolute begin-extraction location on the host screen. It can be used instead of the FIRST or LAST sequence if the user knows the coordinates of the screen where extraction is to begin. The row value range is between 1 and the height of the host screen (MAXROW). The column value range is between 1 and the width of the host screen (MAXCOL). Negative values for r and c can be used and are interpreted as relative to the height and width of the screen, respectively. For example specifying -1 for r is interpretaed as the last (bottom) row of the screen. Default is (1, 1).

FIRST Indicates that the begin-extraction location on the host screen is after the location of the first occurrence of string on the current host screen.

LAST Indicates that the begin-extraction location on the host screen is after the location of the last occurrence of string on the current host screen.

string The string to be searched for on the host screen.

(xr, xc) A relative row-column offset from the located string. The xr and xc fields are integers that represent the offset to the location of the extraction. In calculating this address, if the vertical edge of the host screen is encountered, a wrap-around to the next row wil occur and the offset counting then continues at this new location.

The value for xr can range from -MAXROW to MAXROW. The
value for xc can range from -MAXCOL to MAXCOL. For
example, (1, -10) would set the extraction location to
one row below and ten columns to the left of the first
character in string.

If (xr, xc) is not provided, the begin-extraction
location defaults to one character to the right of
string. The relative location could be defined as (0,
n) if string has a length of n.

wc='' Indicates that '' is the wildcard character in string. If more than one character is specified in the wildcard string, only the first character is used. If a null is specified, no wildcard is set. The '*' is a place holder that is not compared to the corresponding character in the string being tested on the host screen.

Usage Notes:

- The string is searched for on the host screen by
  increasing columns and rows (from top to bottom of
  screen, with each row being searched left to right).

- Absolute (r, c) is mutually exclusive with the
  FIRST/LAST and string option sequence.

- If the extraction occurs, HITROW and HITCOL is set
  to the location where the extraction began.

Return Codes (internal variable RC):

 0  The extraction was completed successfully.

 3  The extraction length was less than one; null
    string returned.

 6  The FIRST and LAST character string was not
    found; null string returned.

 7  Error in the FIRST or LAST sequence relative
    address specification null string returned.

 8  The begin-address specification exceeds screen
    bounds; null string returned.

 9  The extraction extended beyond screen bounds;
    result truncated.

12  Session lost or undefined; null string returned.

Return the asyncio event and loop as a tuple.

Return session Tnz instance.

Or None if there is none.

Like dict.keys

Writes the input string to the current log destination.

Create a new instance for a ATI-like program.

The new instance will share GLOBAL (including internal) variables.

Use ATI rules to convert the input string to an integer.

Shorthand for num(value(varname))

Rename the current session.

Changes the name of the current session to the session name specified. The specified session name cannot match the name of a currently established session.

This function performs the function of the RENAME option on the GOTO EXEC and overtyping the session name in the ATI session manager.

Print the input string.

Write input string to standard output (likely the terminal). If tracing is active (the internal variable TRACE is set to either CODE or ALL), say will also direct output to the log destination.

Check current screen for a string.

Return True if the specified character string exists on the current host screen. Otherwise return False.

Usage/Syntax:

scrhas(string)               (string is always required)

scrhas(string,wc='*')        (wc is optional to all)
scrhas(CASI,string)          (CASI is optional to all)

scrhas(string,(r,c))

scrhas(string,FIRST,string2)
scrhas(string,LAST,string2)

scrhas(string,(r,c),length)
scrhas(string,(r,c),(r2,c2))

CASI Signifies that the screen search is to be done case independently. Thus, 'Logon' is equivalent to 'LOGON' or 'logon'.

string The string that is searched for on the host screen.

FIRST Indicates that the begin-search location on the host screen is after the location of the last character of the first occurrence of string2 on the current host screen.

LAST Indicates that the begin-search location on the host screen is after the location of the last character of the last occurrence of string2 on the current host screen.

string2 A string that, along with the FIRST or LAST keyword, specifies the location on the host screen where the search for the string will begin.

(r, c) An absolute begin-search location on the host screen. Row ® must be an integer between 1 and the host screen height (MAXROW). Column © is an integer between 1 and the host screen width (MAXCOL).

length An optional parameter specifying the length of the area to be searched for the indicated string. If omitted, the area searched will range from the specified start position to the end of the screen.

(r2, c2) Specifies an absolute end-search location diagonally opposite to (r, c). Row (r2) and column (c2) must be integers from 1 to MAXROW and from 1 to MAXCOL, respectively. The (r, c) and (r2, c2) define a rectangular window on the screen where the specified string is searched for.

wc='' Indicates that '' is the wildcard character in string. The '*' is a place holder that is not compared to the corresponding character in the string being tested on the host screen. The wildcard can be any character that the user chooses. Whenever a character is to be interpreted as a wildcard, wc must be specified.

Usage Notes:

 - The internal variables HITROW, HITCOL, and HITSTR
   are set by this function if the search is
   successful.

 - If a begin location is not specified, the search
   will begin at the upper left corner (1:1) of the
   host screen and will cover the entire screen.

 - If string2 is not found on the current host screen,
   this function returns False.

 - Search direction is by increasing columns and rows.
   (Top to bottom, each row being searched left to
   right.)

Return Codes (internal variable RC):

  0  The string was found on the host screen.
     Function returns True.

  1  The string was not found on the host screen.
     Function returns False.

  6  The FIRST or LAST character string was not found.
     Function returns False.

  8  The begin-search or end-search location exceeds
     screen bounds.
     Function returns False.

 12  Session lost or undefined.
     Function returns False.

Send string to the active session.

Send a string of characters and/or special keys to the active session. The session recognizes them as if the user typed the data interactively at the keyboard and, depending on the data sent, it performs the necessary action.

Usage/Syntax:

send([(row, col),] string)

string The data to be sent to the host screen.

(row,col) The location of the cursor that should be set before the data is sent to the host screen. The default is the current cursor location.

Usage Notes:

1 - After completion of the send function, the internal
    variable SENDSTR will contain the value of string. A
    difference from ATI is that SENDSTR will NOT contain
    characters that were ignored.

2 - The send function transmits data to the active
    session starting at the current cursor position. The
    programmer can access the internal variables CURROW
    and CURCOL to check the current cursor location. A
    difference from ATI is that the position at which
    data is transmitted can be specified by (row,col).

3 - <TODO need more on mneumonics>

Special Keys

    [backtab]
    [curdown]
    [curleft]
    [curright]
    [curup]
    [delete]
    [eraseeof]
    [home]
    [insert]
    [newline]
    [tab]

The RESET key ([reset])

    The RESET key has three different meanings--depending on
    its location in the input string:

    Terminate INSERT mode
        Occurs when the key appears in the middle of the
        input string; i.e., there is data before and
        after the RESET key.

    Ignore Keyboard Lock Condition
        Occurs when the key is the first data item in the
        string being sent. Normally if the keyboard is
        locked, ATI waits up to 1 minute for the keyboard
        to unlock before sending data. (Note that this
        value can be changed using the KEYUNLOCK internal
        variable. However, there are rare cases when it
        is necessary to transmit data while the keyboard
        is locked. For example, the user may want to send
        '####' to PVM (Pass-Through Virtual Machine) to
        drop a link, ignoring the condition of the
        screen. For example:

            send(reset+'####'+enter)

        Note: If the keyboard were not to unlock in the
        time allowed, the session would be dropped.

    Suppress Warning Messages
        Is not a very common use of the RESET key. By
        appending a RESET key just before the control
        key, warnings are not logged by the compiler if
        the send function was unsuccessful. For example,
        it is usually desirable not to see warning
        messages when a LOGOFF or DISCONNECT is sent to a
        session. For example:

            send('LOGOFF'+reset)

Control keys

    [clear]
    [enter]
    [pa1]-[pa3]
    [pf1]-[pf24] (also [pf01]-[pf24])

    Note that there is no equivalent to the ATI HOLDSEND.
    None is needed since ENTER is not implied.

Return Codes (return value and internal variable RC):

     0  The string was successfully sent to the host screen.

     4  Data placed in protected field ignored.

    12  Session lost or undefined.

    14  Session dropped due to excessive keyboard lock;
        null string returned.

Set an ATI-like variable.

Perform the ATI GLOBAL statement function

returns the contents of the ATI variable for the input name

Wait for either a specific time limit or for a specified wait condition to be satisfied.

Usage/Syntax:

wait([{ss | '[[hh:]mm:]ss'}])
wait([{ss | '[[hh:]mm:]ss'},] {bool | callable})

hh Represents the number of hours to wait.

mm Represents the number of minutes to wait.

ss Represents the number of seconds to wait.

: A delimiter that separates the hour, minute, and second.

bool An expression that evaluates to True or False.

callable An expression in the form of a callable (e.g. lambda) that returns a bool.

Usage Notes:

- The wait function will return upon a True expression
  (or when the wait time is exceeded).

- The wait function will continuously request updates of
  the current host session screen. A wait time of 0 will
  cause a host screen update to occur and ATI processing
  to continue immediately.

- If no time is specified, the wait time will be the
  value of the program variable MAXWAIT.

- The condition is checked once every second unless the
  value of the internal variable, WAITSLEEP, is changed.

Return Codes (return value and internal variable RC):

 0  The wait time expired before the expression was
    satisfied.

 1  The expression was satisfied before the wait time
    expired.

12  Sesesion lost or undefined.

ATI WHEN statement function.

Usage/Syntax:

@when({bool | callable | lambda: expression})
def whenlabel():
    statement(s)

when(whenlabel, [priority, ] ON)
when(whenlabel, OFF)

whenlabel The assigned name of the WHEN block.

priority A priority level that a WHEN block is given at runtime. This determines the order of execution relative to other active WHEN blocks. The priority level is an integer between 1 and 5. The default priority is 1 (highest) at the start of program execution. The priority will remain the last value assigned to it on a WHEN ON statement.

ON Used to begin the monitoring of whenlabel. All WHEN blocks are initialized to OFF. For any monitoring of WHEN blocks to occur, each WHEN must be explicitly turned ON.

OFF Used to suspend the monitoring of whenlabel. It is highly recommended to turn off any unnecessary WHEN conditions. Excessive WHEN condition monitoring slows processing.

An indicator that a WHEN, when active, will execute in all included or called programs as well as the program in which it is declared.

expression A WHEN condition in the form of an expression.

statement(s) A list of statements to be executed whenever expression is true.

Usage Notes

-  The expression used in a WHEN block may involve a host
   screen check and/or an ATI variable check. The WHEN
   conditions may be classified to determine the
   frequency of monitoring.

-  While a WHEN block is currently being executed, no
   other WHEN expressions are checked.

-  A WHEN condition can be suspended or executed inside
   of a WHEN execution block.