ATTAC implements REXX scripting standard. Using the Regina REXX interpreter (http://www.lightlink.com/hessling/Regina/index.html ), ATTAC support all standard REXX constructs.

New ATTAC Subroutines and Functions

ATTAC_ClearBuffer ([<pos>])

Clears the data buffer for the ZOC script.  If <pos> is passed, the buffer is only cleared up to that point.  All data after that position is still retained.

NOTE:  This buffer is not the same buffer that the Zoc* functions use.  Functions affecting this buffer does not affect the buffer used by the Zoc functions.

Example:

/* clear all data up to the 10th character */
CALL ATTAC_ClearBuffer(10)
/* now clear the whole buffer */
CALL ATTAC_ClearBuffer()

ATTAC_Get_Sector_Info (<sector> [, <warp_num> ])

Return information about a sector you have visited.

If <warp_num> is not passed, the return value is the number of warps out of this sector.

If <warp_num> is passed, return the sector that for the <warp_num> th warp.

Example:

/* Get infromation about sector 1 */
warp_count = ATTAC_Get_Sector_Info(1)
DO warp = 1 to warp_count
    sector = ATTAC_Get_Sector_Info(1, warp)
END

ATTAC_Get_ZTM_Sector_Info (<sector> [, <warp_num> ])

Return information about a sector from ZTM data.

If <warp_num> is not passed, the return value is the number of warps out of this sector.

If <warp_num> is passed, return the sector that for the <warp_num> th warp.

Example:

/* Get infromation about sector 1 */
warp_count = ATTAC_Get_ZTM_Sector_Info(1)
DO warp = 1 to warp_count
    sector = ATTAC_Get_ZTM_Sector_Info(1, warp)
END

ATTAC_GetBestPairPort(<type>)

Return a string of the best pair ports seperated by a space. If either port is on the bust list, it is NOT chosen and then next best pair is chosen.

<type> = "1", return the best equipment-organics pair
<type> = "2", return the best equipment-fuel pair
<type> = "3", return the best fuel-organic pair

Example:

/* getting the best equipment-organic pair and putting into variables sector1, sector2 */
tmp1 = ATTAC_GetBestPairPort(1)
parse var tmp1 sector1 sector2

/* getting the best equipment-fuel pair and putting into variables sector1, sector2 */
tmp1 = ATTAC_GetBestPairPort(2)
parse var tmp1 sector1 sector2

/* getting the best organic-fuel pair and putting into variables sector1, sector2 */
tmp1 = ATTAC_GetBestPairPort(3)
parse var tmp1 sector1 sector2

ATTAC_GetBestEvilPairPort(<type>)

Return a string of the best EVIL pair ports seperated by a space. If either port is on the bust list, it is NOT chosen and then next best pair is chosen.

<type> = "1", return the best XXB-XXB pair; REQUIRED. Type must be 1.

Example:

/* getting the best XXB-XXB pair and putting into variables sector1, sector2 */
tmp1 = ATTAC_GetBestEvilPairPort(1)
parse var tmp1 sector1 sector2

ATTAC_Get_Port_Info (<sector>, <option>)

Return information about the port in <sector>.  If ATTAC doesn't know about a port in that sector, it returns "Unknown". If there is not Port, it returns "NoPort"

The type of information returned is defined by <option>.

<option> = "TYPE", return the type of port 0-9
<option> = "FUEL AMOUNT", return the amount of fuel
<option> = "FUEL PERCENT", return the percent of fuel
<option> = "ORG AMOUNT", return the amount of organics
<option> = "ORG PERCENT", return the percent of organics
<option> = "EQUIP AMOUNT", return the amount of equipment
<option> = "EQUIP PERCENT", return the percent of equipment

Example:

/* Get information about the port in sector 1 */
info = ATTAC_Get_Port_Info(sector, "TYPE")
if info = "Unknown" then signal No_Port
if info = "NoPort" then signal No_Port
call ZocWriteln("Port in " || sector || " is a " || info)
info = ATTAC_Get_Port_Info(sector, "FUEL AMOUNT")
call ZocWriteln("Fuel amount = " || info)
info = ATTAC_Get_Port_Info(sector, "FUEL PERCENT")
call ZocWriteln("Fuel Percent = " || info)
info = ATTAC_Get_Port_Info(sector, "ORG AMOUNT")
call ZocWriteln("Org amount = " || info)
info = ATTAC_Get_Port_Info(sector, "ORG PERCENT")
call ZocWriteln("Org Percent = " || info)
info = ATTAC_Get_Port_Info(sector, "EQUIP AMOUNT")
call ZocWriteln("Equip amount = " || info)
info = ATTAC_Get_Port_Info(sector, "EQUIP PERCENT")
call ZocWriteln("Equip Percent = " || info)
signal Quit_Script

No_Port:
call ZocWriteln("No port in sector " || sector)

Quit_Script:
EXIT

ATTAC_GetTotalSectors ()

Returns the number of sectors in the game, as defined by the user during the creation of the game.

Example:

totalSectors = ATTAC_GetTotalSectors()

ATTAC_GetStardockSector ()

Returns the sector the stardock is in, as found when playing. If the stardock sector is unknown, a -1 is returned.

Example:

totalSectors = ATTAC_GetStardockSector()

ATTAC_GetBuffer ()

Returns the script buffer.

NOTE:  This buffer is not the same buffer that the Zoc* functions use.  Functions affecting this buffer does not affect the buffer used by the Zoc functions.

Example:

buffer = ATTAC_GetBuffer()

ATTAC_IsSectorBusted(<sector>)

Tells you if the you were busted in that  <sector> .

Return Values are:

-1 = If you enter an invalid sector or unknown
 0 = Not Busted In <sector>
 1 = Were Busted In <sector>

Example:

ATTAC_IsSectorAvoided(<sector>)

Tells you if the you have avoided that  <sector> .

Return Values are:

-1 = If you enter an invalid sector or unknown
 0 = Not Avoided <sector>
 1 = Avoided <sector>

Example:

ATTAC_HasSectorFig(<Sector>)

Tells you if a  <sector> has a fighter and if the fighter is yours, an ally or an enemy fighter.

Return Values are:

-1 = There are no fighters in the sector or you entered and invalid sector.
 0 = The is a fighter in the sector and it belongs to you or your corporation.
 1 = There is an enemy fighter in the sector.
 2 = There is an allied fighter in the sector.

Example:

tmp1 = ATTAC_HasSectorFig()
if tmp1 = 1 then do
  call ATTAC_Message ("Enemy Fighter in Sector")
end

ATTAC_Message (<message>,[<color>],[<intro>])

Adds a message to the ATTAC Message Center.

<message> = This is the actual message that gets added.
<color> = (Optional) Is the color of the Message.
            Choices are: BLACK, RED, GREEN, YELLOW, BLUE, CYAN, WHITE
<intro> = (Optional) This is the little blurb that appears in [...] before the message.

Example:

CALL ATTAC_Message("This is a test")

CALL ATTAC_Message("This is a test","YELLOW")

CALL ATTAC_Message("This is a test","GREEN","My Message")

ATTAC_SectorFigAmount(<sector>)

Tells you how many fighters are in a  <sector>

Return Values are:

-1 = There are no fighters in the sector or you entered and invalid sector.
 OR
The number of fighters in the sector

Example:

tmp1 = ATTAC_SectorFigAmount("294")
if tmp1 = -1 then do
  call ATTAC_Message ("No Fighters in Sector")
end
else do
  call ATTAC_Message ("There are " || tmp1 || " fighers in sector 294")
end

ATTAC_SectorFigOwner(<sector>)

Tells you the name of the owner of the fighters in the  <sector> .

Return Values are:

"Unknown" = ATTAC doesnt know who the owner of the fighters are.
"No Figs" = There are no fighters in the sector.
"CORP N" = Where N is the corporation number.
NAME = Where NAME is the name of the owner of the fighters
"-1" = If you enter an invalid sector.

Example:

tmp1 = ATTAC_SectorFigOwner("294")
if tmp1 = "No Figs" then do
  call ATTAC_Message ("No Fighters in Sector")
end
else do
  call ATTAC_Message ("There fighter owner is " || tmp1)
end

ATTAC_SectorFigType(<sector>)

Tells you the type of fighters in the  <sector> .

Return Values are:

-1 = If you enter an invalid sector or unknown
 0 = Rogue Mercenary
 1 = Toll
 2 = Offensive
 3 = Defensive

Example:

ATTAC_StartBuffer ()

Start placing incoming data into the script buffer.

NOTE:  This buffer is not the same buffer that the Zoc* functions use.  Functions affecting this buffer does not affect the buffer used by the Zoc functions.

Example:

CALL ATTAC_StartBuffer()

ATTAC_StopBuffer ()

Stop placing incoming data into the script buffer.

NOTE:  This buffer is not the same buffer that the Zoc* functions use.  Functions affecting this buffer does not affect the buffer used by the Zoc functions.

Example:

CALL ATTAC_StartBuffer()

ATTAC_UpdateCounter ([<inc_val>])

Update the script counter by <inc_val> or by 1 if <inc_val> is not passed.

Example:

/* Count from 2 - 20 in the script counter */
DO 10
    CALL ATTAC_UpdateCounter(2)
    CALL ZocDelay(1)
END

Supported ZOC Subroutines and Functions

ZocAsk (<title> [, <default>])

Get the user a question in a dialog box. If <default> is provided, the input box will be preset to that value.

Example:

Sector = ZocAsk ("Which sector would you like to warp to?", "1")

ZocAskP (<title> [, <default>])

Same as ZocAsk except the input box is displayed using the password symbol (*)

Example:

Password = ZocAskP ("Enter your password: ")

ZocBeep (<n>)

Beep <n> times.

Example:

CALL ZocBeep (3)

ZocClearBuffer ()

Clears ATTAC parsing buffer

Example:

CALL ZocClearBuffer ()

ZocCls ()

Clear the game window.

Example:

CALL ZocCls ()

dosfname ( <filename>)

Returns the filename with an absolute path using the ATTAC directory that attac.exe is located in.

Example:

CALL ATTAC_Message(dosfname ("script.ini"))

This returns "C:\Program Files\ATTAC\script.ini" assuming that attac.exe is located in "C :\Program Files\ATTAC"

dosisdir (<directory>)

Returns a 0 or a 1 depending on if the <directory> exists or not

 0 = The directory does not exist
 1 = The directory does exist

Example:

CALL ATTAC_Message(dosisdir ("c:\test"))

This returns 0 if the directory does not exist and 1 if it does

ZocDelay ( [<sec>] )

Pause the script for <sec> seconds. If <sec> is not provided, pause for 0.2 seconds.

Example:

CALL ZocDelay (5)

ZocGetLine ()

Wait for the next non empty line of text from the game. The received text can be accessed from ZocLastLine. ZocGetLine waits for line until the timeout is reach, at which time it returns with "640"

NOTE: Due to different processing, ATTAC does not miss any incoming data. Thus ZocSynctime is not implemented.

Example:

Timeout = ZocWait ("[Pause]")
IF Timeout = 640 THEN DO
    SIGNAL PANIC
END

ZocGetFileName ()

Opens a Common Dialog box and prompts the user to select a filename. You can either select a file or click CANCEL.. If user clicks CANCEL, the string ##CANCEL## is returned.

Example:

tmp1 = ZocGetFileName()
if tmp1 = "##CANCEL##" then do
  CALL ATTAC_Message("No file selected")
end
else do
  CALL ATTAC_Message("Filename is: " || tmp1)
end

ZocLastLine ()

Returns the line of text when the last ZocGetLine / ZocWait / ZocWaitMux returned.

Example:

Timeout = ZocWait ("]:[")
IF Timeout = 640 THEN DO
    SIGNAL PANIC
END
CALL ZocWait ("]")
CurrentSector = ZocLastLine()
/* Parse trailing "]:[" off of CurrentSector */

ZocLogname (<filename>)

Change the name of the log file to <filename>.  Only takes effect after you call ZocLogging(1).

Example:

/* Create a logfile with the name attac_zoc.log */
CALL ZocLogname("attac_zoc.log")
CALL ZocLogging(1)
CALL ZocSend("D")
CALL ZocWait("]:[")
CALL ZocLogging(0)

ZocLogging (<on_off>)

Turns the logging on (<on_off> = 1) or off (<on_off> = 0).  You can set the name of the log file with ZocLogname.

Example:

/* Create a logfile with the name attac_zoc.log */
CALL ZocLogname("attac_zoc.log")
CALL ZocLogging(1)
CALL ZocSend("D")
CALL ZocWait("]:[")
CALL ZocLogging(0)

ZocLockKeyboard (<lock>)

Lock (<lock> = 1) / Unlock (<lock> = 0) the keyboard to prevent the user to send keys while your script is running.

The keyboard is automatically unlocked at the termination of the script.

Example:

/* Prevent the user from typing for 5 seconds */
CALL ZocLockKeyboard (1)
CALL ZocDelay (5)
CALL ZocLockKeyboard (0)

Lower (<string>)

Changes the <string> to lowercase

Example:

ZocKeyboard(<command>)

This function allows a REXX script to lock/unlock the keyboard. 
It supports the subcommands LOCK, UNLOCK

Example:
Call ZocKeyboard("LOCK")

ZocMsgBox (<text> [, <mode>])

Display a message box containing <text>. The three different types of message boxes are:

<mode> = 0 Simple dialog box with an OK button
<mode> = 1 Error dialog box with an OK button
<mode> = 2 Yes/No dialog box.

If <mode> is not provided, a simple dialog box with an OK button is used. The return values are "##OK##", "##YES##", "##NO##".

Example:

result = ZocMsgBox ("Out of money", 2)
IF result = "##YES##" THEN DO
    /* Stuff */
END

ZocNotify (<text>)

Display a temporary window containing <text>. This window is displayed for 3 seconds.

Example:

Sector = Sector + 1
CALL ZocNotify ("Warping to sector " || Sector)

ZocOs ()

Returns the OS name and version. Currently returns only "WINNT 4.00".

Example:

Os = ZocOs ()

ZocRequest (<title>,<opt1> [, <opt2 > [, <opt3> … [, <optn>]]])

Display a list of options for the user to pick from. The number of options is not limited. The return value is the text of the option chosen.

Example:

Answer = ZocRequest ("Which planet would you like to land on?", "Planet 1", "Planet 2", "Planet 3", "Planet 4")
IF Answer = "Planet 1" THEN DO
    /* land on planet 1 */
END

IF Answer = "Planet 2" THEN DO
    /* land on planet 2 */
END

/* Etc.. */

ZocRequestList (<title>,<opt1> [, < opt2 > [, <opt3> … [, <optn>]]])

Display a requester window with a list of options and return the index of the selected option (or -1 for Cancel).  If only one option is passed to the function, it is considered as a list of choices separated by vertical bars.

Example:

Answer = ZocRequest ("Which planet would you like to land on?", "Planet 1", "Planet 2", "Planet 3", "Planet 4")
IF Answer = 1 THEN DO
    /* land on planet 1 */
END

IF Answer = 2 THEN DO
    /* land on planet 2 */
END

/* Etc.. */

ZocRespond (<prompt> [, <response>])

If <response> is provided and doeZocClearBuffer s not equals "", then send <response> whenever <prompt > is encountered, but ONLY while ZocGetLine, ZocWait, and ZocWaitMux are processing. If <response> is not provided or equals "", then this response is canceled.

NOTE: This command uses more CPU time than normal. Therefore, it is recommended that you cancel a response as soon as you don't need it anymore.

Example:

/* continue past all "[Pause]" until "Command" is reached */
CALL ZocRespond ("[Pause]", "^M")
CALL ZocWait ("Command")
CALL ZocRespond ("[Pause]")

ZocScreen (<x>, <y>, <length>) 
ZocGetScreen   (<x>, <y>, <length>) - (same as ZocScreen)

Returns <length> characters on game screen starting at coordinates <x>,<y>. <x> and <y> start at 0,0 in the upper left hand corner.

Example:

Data = ZocScreen(0, 0, 10)

ZocSend (<text>)

Send <text> to the game. The text in <text> is first expanded inserting the proper control characters in place of the control codes. See below for a list of the command codes and their meanings.

Example:

/* Send the username and a return key */

CALL ZocSend (username || "^M")

ZocSendRaw (<text>)

Same as ZocSend except it doesn't expand <text>.

Example:

/* Send the username and the string "^M" */
CALL ZocSendRaw (username || "^M")

ZocSetOption (<text>)

This Command is accepted but not interpreted.

ZocTimeout (<sec>)

Set the timeout used by ZocGetLine, ZocWait and ZocWaitMux to <sec > seconds.

Example:

/* Wait for 5 seconds for the text before returning */
CALL ZocTimeout (5)
Timeout = ZocWait (text)
IF Timeout = 640 THEN DO
    SIGNAL PANIC
END

ZocWait (<text>)

Wait for <text> in the input stream before returning. If ZocWait times out, it will return 640.

Example:

Timeout = ZocWait (text)
IF Timeout = 640 THEN DO
    SIGNAL PANIC
END

ZocWaitMux (<text1> [, <text2> [, < text3 > … [, <textn>]]]

Same as ZocWait except wait for multiple inputs. As soon as one of them is found, it returns the index of the <text?> found. (1 for < text1>, 2 for <text2>, etc.) If ZocWaitMux times out, it will return 640.

Example:

Result = ZocWaitMux ("offer", "not interested")
SELECT
    WHEN Result = 0 THEN SIGNAL Offer
    WHEN Result = 1 THEN SIGNAL Bail
    WHEN Result = 640 THEN SIGNAL PANIC
END

ZocWrite (<text>)

Write <text> to the screen at the current cursor position. < text> is expanded using control codes. This is similar to the REXX command SAY, but it does not place an enter at the end of the line.

Example:

CALL ZocWrite ("Starting the script! ^M")

ZocWriteln (<text>)

Similar to ZocWrite, except it places an enter at the end of the line. 

Example:

CALL ZocWriteln ("Starting the script!")

ZocExec <command>, [<viewmode>]

Execute a program directly (ie. without passing it through the shell handler, thus avoiding the black shell window).  This does only work for .com and .exe files (not for .cmd and internal commands like DEL, REN etc.).

optional viewmode parameter controls how the application window is shown:
<viewmode> = 0  -  normal
<viewmode> = 1  -  hidden
<viewmode> = 2  -  minimized
<viewmode> = 3  -  maximized

ZocExec also returns the exit code of the application.

Example:

CALL ZocExec ("notepad.exe")
 
ZocGetInfo(<item>)

This function returns information about the current ZOC session. Items:

CONNECTEDTO
The host or phone number to which we are connected.

CURSOR-X
The x-position of the cursor (starting with zero).

CURSOR-Y
The y-position of the cursor (starting with zero).

DOWNLOADDIR
The default drive and directory for downloads.

EXEDIR
The drive and directory in which ZOC has been installed.

ONLINE
Information if ZOC is currently connected to a host: ##YES##,  ##NO##, ##UNKNOWN##

OSYS
Returns a string which indicates the operating system and OS version under which ZOC is running.  The string returned is in the form "<osys> <version>" where <osys> is OS2 or WINNT or WIN95. <version> is a three digit number eg. 400 for Windows NT 4.0 or 230 for OS/2 Warp (Warp sees itself as OS/2 V2.30).  Windows 95 returns WIN95 400

UPLOADDIR
The default drive and directory for uploads.

VERSION
The current ATTAC version, eg 4.1.5

WORKDIR
ATTAC's working directory (containing host directory, options, etc).

Example:
call ATTAC_Message (ZocGetInfo("ONLINE"))

This function returns information about the current options. Items:

VTStripSeq
Returns: VTStripSeq="yes"

CaptDefaultName
Returns: CaptDefaultName="attac_log_default_name.log"

ScriptPath
Returns: ScriptPath="SCRIPT"

CapturePath
Returns: CapturePath="DATA"

DownloadAltPath
Returns: DownloadAltPath="DATA"

ScriptPath
Returns: ScriptPath="SCRIPT"

WindowTitle
Returns: WindowTitle="%%ZOCORHOST%% %%OPTIONS%%"

If None of the above options are chosen, the return value is "Invalid ZocGetOption"

Example:
call ATTAC_Message (ZocGetOption("ScriptPath"))

ZocReceiveBuf(<buffer size>)

This function makes ZOC collect parts of a session in a memory buffer and returns the previous buffer's contents (if any) as a string.
Initially the buffer has a size of zero, which means that no data is collected.  To start data collection you need to call the function with the size of a receive buffer.   After that the incoming data is collected until the buffer is full or until the function is called again (which will retrieve the buffer contents, empty the buffer and set a new size).
A typical call sequence to use ZocReceiveBuf() to retrieve text from a database might look like this:

Example:
/* make a receive buffer of 256 bytes */
CALL ZocTimeout 60
CALL ZocReceiveBuf 256
CALL ZocSend "d"
CALL ZocWait "Command"

/* get the description and make a */
/* larger buffer to continue with */
abst= ZocReceiveBuf(4096)
Call ZocMsgBox (abst)

CALL ZocSend "i"
CALL ZocWait "Command"

/* get the contents and discontinue buffering */
cont= ZocReceiveBuf(0)
Call ZocMsgBox (cont)

Note: In the example above, both variables (abst and cont) will start with the word "read" and end with the character "Command" with whatever was received in between.

Note: See also ZocWaitForSeq.

ZocString(<subcommand>, <inputstring>, <p1>, [<p2>])

This is a function to manipulate a string and return a modified copy. The subcommand and the parameters <p1> and <p2> control the modification. 

Subcommands:
PART
Return the <p1>th part <inputstring> which is delimited by <p2> (or space if <p2> is omitted), e.G. ZocString("PART", "Anne|Charly|Joe", 2, "|") will return "Charly".

PARTCOUNT
Return the number of <p2>-delimited parts in <inputstring>, e.G. ZocString("PARTCOUNT", "Anne|Charly|Joe", "|")  will return 3.

REPLACE
Return a copy of <inputstring> where all ocurrences of <p1> are replaced by <p2>, e.G. betterstr= ZocString("REPLACE", str, "HyperTerminal", "ATTAC")

REMOVE
Return a copy of <inputstring> where all ocurrences of <p1> are removed, e.G. betterstr= ZocString("REMOVE", str, "HyperTerminal")

REMOVECHARS
Return a copy of <inputstring> from which all characters of <p1> were removed, e.G. str= ZocString("REMOVECHARS", str, "0123456789"||X2C(09)) removes all digits and tab characters from STR.

ZocWaitForSeq 1|0

Normally ZocWait commands do not see emulation control codes in the data stream.  If you need to wait for an emulation control you can use this command.  This flag also turns on/off filtering of emulation controls for ZocReceiveBuf().

Example: 

/* rexx example */
Call ZocWaitForSeq 1
Call ZocSend "d"
Call ZocWait ("Command")
Call ZocMsgBox(ZocLastLine())

ZocSyncTime

This Command is NOT implemented. It is just interpreted for compatability with with other scripts. ATTAC has no need for this command has it syncronizes it's threads.

Unsupported ZOC Subroutines and Functions

The following ZOC subroutines and functions are not been implemented either due to no relevance or new different ways of implementing the underling algorithms.

Differences between ZOC and ATTAC

ATTAC and ZOC have different internal structure that cause slight changes in the way scripts are executed. The main differences are as follows:

ATTAC does not miss any data due to different threads

This has been the cause of many problems. Lost data is never a good thing, and ATTAC avoids this problem by using a more advanced internal algorithm.

ATTAC is more serialized with respect to ZocRespond and ZocGetLine/ZocWait/ZocWaitMux due to better synchronization handling

The following code fragment use to work but no longer does due to the better handling of data.

CALL ZocRespond ("[Pause]", "^M")
CALL ZocWait ("[Pause")
CALL ZocRespond ("[Pause]")

This fragment would wait for "[Pause]", send and enter, and continue. However, since the text sent to ZocWait is missing the trailing "]", it breaks out of ZocWait before ZocRespond sees the final "]", and therefore the enter is never sent, since ZocRespond only works while ZocGetLine, ZocWait or ZocWaitMux are waiting for data.

ATTAC does not place limits on the number of parameters passed to ZocRequest or limits on the number of ZocRespond requests .

This does not effect the execution of scripts, but does allow more flexibility.

ATTAC is stricter in calling ZOC commands.

ATTAC does not support the calling method such as the following:

ZocDelay 2

Instead, use the following method

CALL ZocDelay(2)

OR

ZocDelay(2)

Control Codes