Home Page
        Orders     Downloads     Support     Contact     Deutsch
ZOC Terminal is a professional SSH Client and Terminal Emulator for Windows and macOS.
ZOC Online Help Topic:

APPENDIX → ZOC-REXX Commands/Functions

 

Overview

The section below lists the ZOC extensions to the REXX scripting language in alphabetical order (alternately there is also a list of ZOC-REXX Commands by Category. These commands extend the native REXX programming language. REXX in itself is a full featured programming language, offering the usual constructs like variables, decisions, loops, etc.

To help discern between native REXX and the ZOC-Extensions, the examples below display the native elements of the REXX language in all-uppercase, e.g. CALL, IF, THEN, SAY. You will find an overview of such commands and functions in REXX Language Elements.

The ZOC-commands extend the REXX language and offer terminal emulation specific functions. Their names start with with Zoc and below these commands are written in CamelCase, e.g. ZocConnect, ZocSend, etc. User defined names (variables) are expressed all lowercase, e.g. thename= ZocAsk("What is your name");

 

 

Invoking ZOC-REXX Extensions

Generally there are two types of ZOC-commands: Those which return a value or result (e.g. ZocAsk, these are also called functions) and those which just perform a task but don't provide a return value (e.g. ZocDelay).

  • ZOC-commands that do not return a value are invoked using the procedure call syntax:
  • CALL <cmd-name> <arguments>, e.g. CALL ZocDelay 2.5.
  • Functions that return values are invoked using the function call syntax:
  • <result-var>= <cmd-name>(<arguments>), e.g. answer= ZocAsk("Your name?")

However, if you are not interested in the result value, it is possible to simply discard it by calling functions (commands which return values) using the procedure style invocation. In other words, the statements CALL ZocDownload "ZMODEM", "SOMEFOLDER" and error= ZocDownload("ZMODEM", "SOMEFOLDER") are both correct. In fact, the ZOC-REXX implementation even allows this variant: CALL ZocDownload("ZMODEM", "SOMEFOLDER")

 

 

ZOC REXX Extensions

In the list below, the use of brackets in commands titles indicates that you typically need to use the function style (see above), because the return value of the commands is usually significant.

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

Show a text input window and read text from user. If the second argument (preset) is provided, the entry field will be preset with this value.
 
Example:

answer= ZocAsk("What is the best terminal?", "ZOC")
IF answer="ZOC" THEN …

 
See also: ZocDialog, ZocAskPassword, ZocAskFilename, ZocAskFoldername, ZocRequest, ZocRequestList

ZocAskPassword([<title>])
 

Same as the ZocAsk command, except that it is intended to enter passwords, i.e. the entry field shows typed characters as dots and you cannot preset the field with a default value.
 
Example:

pw= ZocAskPassword("What's your password?")
IF pw=="secret" THEN …

ZocAskFilename(<title> [, <preselected file>])
 

Display a file selection window and return the filename. If the file dialog is cancelled, the string ##CANCEL## is returned.
 
Example:

file= ZocAskFilename("Select file to upload", "*.ZIP")
IF file\="##CANCEL##" THEN DO
    CALL ZocUpload "ZMODEM", file
END

 
See also: ZocAsk, ZocDialog, ZocFilename, ZocAskFilenames, ZocAskFoldername, ZocListFiles

ZocAskFilenames(<title> [, <preselected file> [, <delimiter>]])
 

Display a window that allows selection of multiple files and return the filenames separated by a space character. If the file dialog is cancelled, the string ##CANCEL## is returned.

The items can then be extracted from the list by using the ZocString("WORD", idx) function. If you expect filenames to contain space characters, you need to supply a different delimiter and use the ZocString("PART", idx, "|") function instead.
 
Example:

files= ZocAskFilenames("Select file to process", "*.ZIP", "|")
    
howmany= ZocString("PARTCOUNT", files, "|")
DO i=1 TO howmany
    name= ZocString("PART", files, i, "|")
    SAY i||". NAME= "||name
END

 
See also: ZocFilename, ZocAskFilename, ZocAskFoldername, ZocListFiles, ZocMessageBox, ZocRequest, ZocRequestList

ZocAskFoldername(<title> [, <preselected folder>])
 

Display a folder selection dialog and return the name of the selected folder. If the dialog is cancelled, the string ##CANCEL## is returned.
 
Example:

folder= ZocAskFoldername("Select Folder")
IF folder\="##CANCEL##" THEN DO
    SAY folder
END

 
See also: ZocFilename, ZocAskFilename, ZocAskFilenames

ZocBeep [<n>]
 

Beep n times.
 
Example:

CALL ZocBeep 2

ZocClipboard <subcommand> [, <writestring>]
 

Performs a clipboard function for one of the following subcommands:

READ
 

Returns the current content of the clipboard

WRITE
 

Writes the string from the 2nd parameter to the clipboard


 
Example:
clip= ZocClipboard("READ")
newclip= clip||ZocCtrlString("^M^J Zoc was here!")
CALL ZocClipboard "WRITE", newclip)

ZocClearScreen
 

Clears the screen and resets the emulation to its initial state.
 
Example:

CALL ZocClearScreen

ZocCommand <subcommand>
 

Performs a function for one of the following subcommands:

CLS
 

Clear screen.

CLEARSCROLLBACK
 

Clear scrollback buffer.

CANCELCONNECT
 

Cancel a connect request that is currently in progress.

LOADGLOBALCOLORS
 

Reload the global color table from file (default file name or 2nd Parameter).

SAVEPROGRAMSETTINGS
 

Permanently stores changes, which were made via the ZocSetProgramOption command.

SAVESESSIONPROFILE
 

Stores changes made via the ZocSetSessionOption to the current session profile file (see also ZocSaveSessionProfile)

SETMARKEDAREA
 

Marks an area on screen. After the subcommand provide the word BLOCK or STREAM, followed by coordinates x1,y1 and x2,y2.

SENDBREAK
 

Sends a modem break signal (Serial/Modem connections only).


 
Example:
CALL ZocCommand "SAVESESSIONPROFILE"

 
Example:
CALL ZocCommand "SETMARKEDAREA", "BLOCK", 0,0, 1,79

 
See also: ZocMenuEvent

ZocConnect [<address>]
 

Connect to a host via telnet, modem, ssh etc. or read the address to connect to from the user if the parameter is omitted.

The connection method will be the one that is active in the current session profile. Alternately a connection method can be selected in the script via ZocSetDevice.

If the address is an SSH host, you can pass the username and password to the host in the form CALL ZocConnect "user:pass@ssh.somedomain.com" and you can also provide the name of a key file after the password separated with a colon, CALL ZocConnect "user:pass:keyfile@ssh.somedomain.com".

 
Example:

CALL ZocSetDevice "Secure Shell"
CALL ZocConnect "harry:alohomora@192.168.1.1:10022"

 
Example:
CALL ZocSetDevice "Telnet"
CALL ZocConnect "server.hogwarts.edu"
    
Call ZocTimeout 20
x= ZocWait("Login:")
IF x=640 THEN SIGNAL waitfailed /* login prompt not received */
CALL ZocSend "harry^M"
x= ZocWait("Password:")
IF x=640 THEN SIGNAL waitfailed /* password prompt not received */
CALL ZocSend "secret^M"
    
/* At this point we are logged in */
    
waitfailed:
EXIT

 
See also: ZocConnectHostdirEntry, ZocSetDevice, ZocDisconnect, ZocGetInfo("ONLINE")

ZocConnectHostdirEntry <name>
 

Makes a connection based on the details of an entry in the ZOC host directory (the host directory entry should not have a Login REXX file assigned to it).
 
Example:

CALL ZocConnectHostdirEntry "Webhost 03"

 
See also: ZocConnect, ZocDisconnect, ZocGetInfo("ONLINE")

ZocCtrlString(<text>)
 

This function converts a string containing control codes into a string where the control codes are converted into their respective values.
 
Example:

crlf= ZocCtrlString("^M^J") /* results in two byte string hex"0D0A" */

 
See also: ZocCtrlString

ZocDdeClient([<channel>,] <subcommand> [, <parameters>]
 

This function can be used to interact with other software via DDE (dynamic data exchange). For example MS-Excel supports DDE and the DDE client can be used to retrieve data from Excel worksheets.

Possible <subcommands> are:

INIT
 

Initializes a DDE connection. INIT is followed by two parameters: DDE server-name and topic. INIT will return either ##ERROR## or a channel number for use with subsequent commands.

EXECUTE
 

Performs a server-function. EXECUTE is followed by one parameter: execution-command (e.g. an Excel command).

REQUEST
 

Requests data from the server. REQUEST is followed by one parameter: data-address (e.g. an Excel cell or range).

CLOSE
 

Closes an existing dde-channel.


 
Example:
chan= ZocDdeClient("INIT", "EXCEL", "Table1")
SAY "INIT: channel= "||chan
    
IF chan\="##ERROR##" THEN DO
    data= ZocDdeClient(chan, "REQUEST", "R1C1")
    SAY "REQUEST-DATA: "||data
    
    CALL ZocDdeClient chan, "CLOSE"
END
EXIT
    

ZocDelay [<sec>]
 

Wait a given time in seconds or wait 0.2 seconds if the parameter is omitted.
 
Example:

CALL ZocDelay 4.8

ZocDeviceControl <string>
 

This rather arcane command performs an operation that is specific to the current connection type (e.g. to return the signal states of the COM during a Serial/Direct type connection).

Possible control commands for each communication method are described in ZOC Devices.
 
Example:

state= ZocDeviceControl("GETRS232SIGNALS")

 
See also: ZocSetDevice

ZocDialog <subcommand> [, <parameter>]
 

Performs a dialog related function:

LOAD
 

Shows a user defined dialog window. The 2nd parameter is a combination of the name of the dialog together with the name of the file containing the dialog template (the file name is either a fully qualified file name or the name of a file located in the same folder as the currently running script file).

SHOW
 

Shows a user defined dialog window. There can be an optional 2nd parameter as described above for the LOAD command. In this case, the SHOW command will include the LOAD operation.

GET
 

Returns the value of one of the dialog elements (e.g. the text which the user had typed into an entry field or the state of a checkbox or radiobutton).

SET
 

Set the value of one of the dialog elements, e.g. the text which the will initially be shown in an entry field or the description of an item. With a checkbox or radiobutton, the values "##ON##" or "##OFF##" will also change the initial state.

For details about how dialog templates are built, see ZocDialog Templates.
 
Example:
dlgrc= ZocDialog("SHOW", "MAIN@test.dlg")
IF dlgrc=="##OK##" THEN DO
  name= ZocDialog("GET", "ED1")
  SAY "Hallo "||name
  SAY ZocDialog("GET", "CB1")
  SAY ZocDialog("GET", "P1")
  SAY ZocDialog("GET", "P2")
END

 
Example:
dlgrc= ZocDialog("LOAD", "MAIN@test.dlg")
SAY "Dialog load result: "||dlgrc
CALL ZocDialog "SET", "ED1", "foobar"
CALL ZocDialog "SET", "CB1", "##ON##"
CALL ZocDialog "SET", "DD1", "Red"
CALL ZocDialog "SET", "DD2", "Apple|Orange|Grape"
CALL ZocDialog "SET", "DD2", "Orange"
dlgrc= ZocDialog("SHOW")
IF dlgrc=="##OK##" THEN DO
    /* process result */
END

 
See also: ZocAsk, ZocAskPassword, ZocMessageBox, ZocRequest, ZocRequestList
ZocDisconnect
 

Disconnects the current connection. Same as ZocCommand "DISCONNECT".
 
Example:

CALL ZocDisconnect

 
See also: ZocConnect, ZocConnectHostdirEntry
ZocDownload(<protocol>[:<options>], <file or dir>)
 

Download one or more files using a file transfer protocol.

The first parameter is the name of a file transfer protocol (as listed in ZOC's Options→Session Profile→File Transfer dialog).

The exact nature of the second parameter varies depending on the transfer type (see note below).

For a discussion of the protocol options, please see the ZocUpload command further down in this list.

Depending on success or failure, the function returns the string ##OK## or ##ERROR##
 
Example:

CALL ZocSetSessionOption "TransferAutoStart=no"
ret= ZocDownload("ZMODEM", "C:\ZOC\INFILES")
IF ret=="##ERROR##" THEN DO
    CALL ZocBeep 5
    SAY "Download failed."
END

 
Note: The second parameter varies depending on the file transfer type:
XMODEM: Local destination filename.
YMODEM: Local destination folder.
ZMODEM: Local destination folder.
SCP: Remote source file, e.g. /var/log/somefile.txt
 
Note: If you have Auto Transfer enabled in the Options→Session Profile→File Transfer options, and if the remote host starts the transfer before ZOC-REXX processes the ZocDownload command, then two download windows will come up. So you need to make sure you are issuing ZocDownload() before the host starts or make sure that Auto Transfer option is disabled.
 
Note: If the file has a name that is set for download to the alternate path (in Options→Session Profile→File Handling), the directory parameter is ignored.

 
See also: ZocUpload
ZocDoString(<commandstring>)
 

Pass an action code to ZOC for processing.

You can obtain such strings by temporarily mapping something to a key via Options→Keyboard Mapping Profiles and then copying the result from the key's mapping assistant.
 
Example:

CALL ZocDoString "^EXEC=notepad.exe"

 
See also: ZocMenuEvent, ZocShell, ZocSendEmulationKey

ZocEventSemaphore(<subcommand>[, <signal-id>])
 

This function can be used to synchronize and exchange signals between multiple REXX scripts (it has no use within a single script). To facilitate this, the function offers a signaling mechanism with 16 signal slots for which other scripts can wait.

Possible <subcommands> are:

RESET
 

Sets the state of this semaphore to not-fired and clears the signal counter.

FIRE
 

Sets state to signaled, increases the counter and releases all waiting scripts.

TEST
 

Returns the number of received signals (i.e. FIRE commands) since the last reset.

WAIT
 

Wait for a signal. If the semaphore was already fired, the command will return immediately, resetting the signal (see above) returning the number of signals which happened since the last reset (max 255).
If the semaphore has not yet been signaled (fired), the function will block and wait for a signal or it will return after a timeout (set via ZocZimeout) returning a code of 640 (the behavior of this function is very similar to ZocWait).

<signal-id>
 

An optional number [1..15] to access/use a different semaphore (default is 0).


 
Example:
Call ZocEventSemaphore "RESET"
/* do some work */

/* wait until another script fires the signal */
ret= ZocEventSemaphore("WAIT")
IF ret\=640 THEN DO
   /* signal was received */
END

 
See also: ZocTimeout, ZocWait, ZocGlobalStore

ZocFilename(<command>[, <options>])
 

This group of commands offers filename operations.

COMBINE <path>[, <path2>], <file>
 

Combines filename parts to a full filename. If <file> is already a fully qualified name, <path> and optional <path2> are ignored.

EXISTS <filename>
 

Returns ##YES## or ##NO##, depending on if the file exists.

GETFILE <filename>
 

Returns the filename part of a full file descriptor.

GETPATH <filename>
 

Returns the directory part of a full file descriptor.

GETSIZE <filename>
 

Returns the size of a file.

GETVOLUMELABEL <driveletter>
 

Returns the drive label for a drive, e.g. "C:" (Windows only).

ISFOLDER <pathname>
 

Returns ##YES## or ##NO##, depending on if the given path refers to an existing folder.

RESOLVE <string>
 

Resolves one of ZOC's special file/path placeholders like %ZOCFILES% or %USERHOME% (the other filename functions do this automatically).

WRITEACCESS <filename>
 

Returns ##YES## or ##NO##, depending on if a file can be written.


 
Example:
workdir= ZocGetInfo("WORKDIR")
datadir= ZocFilename("RESOLVE", "%ZOCFILES%");
    
fullfile= ZocAskFilename("Choose File", workdir)
file= ZocFilename("GETFILE", fullfile)
path= ZocFilename("GETPATH", fullfile)
    
file2= file||".tmp"
target= ZocFilename("COMBINE", path, file2)
IF ZocFilename("EXISTS", target)=="##YES##" THEN DO
    CALL ZocMessageBox "Can't overwrite file "||file2
    EXIT
END

ZocFileCopy(<source filename>, <destination>)
 

Copy a file to a new destination which can either be a file name or folder name.

Wildcards like * or ? are not supported in the source file (see ZocListFiles).
 
Example:

CALL ZocFileCopy "Z:\SALES.DAT", "Z:\SALES.BAK"
    
ok= ZocFileCopy("C:\DATA\USERFILE.TMP", "C:\BACKUP")
IF ok\="##OK##" THEN EXIT

 
See also: ZocFilename, ZocFileDelete, ZocFileRename, ZocListFiles, ZocShell

ZocFileDelete(<filename>)
 

Deletes a file. The filename may not contain wildcards (* or ?, see ZocListFiles).

The function returns ##OK## or ##ERROR##
 
Example:

ok= ZocFileDelete("C:\DATA\USERFILE.TMP")
IF ok\="##OK##" THEN EXIT
    
filename= ZocFilename("COMBINE", "%ZOCFILES%", "rexx.log")
CALL ZocFileDelete filename

 
See also: ZocFilename, ZocFileCopy, ZocFileRename, ZocListFiles, ZocShell

ZocFileRename(<oldname>, <newname>)
 

Renames a file. The renamed file will always remain in the same folder as the original file. Filenames may not contain wildcards (* or ?, see ZocListFiles).

The function returns ##OK## or ##ERROR##
 
Example:

ret= ZocFileRename("C:\DATA\USERFILE.TMP", "C:\DATA\USERFILE.TXT")

 
See also: ZocFilename, ZocFileCopy, ZocFileDelete, ZocListFiles, ZocShell

ZocGetHostEntry(<name>,<key>)
 

Retrieves the key-value pair for a ZOC host directory entry (see ZocSetHostEntry or ZocSetSessionOption commands for more information about such key-value pairs).
 
Example:

pair= ZocGetHostEntry("ZOC Support BBS", "connectto")
PARSE VALUE pair WITH key'="'val'"'
CALL ZocConnect val

ZocGetInfo(<what>)
 

Depending on the parameter, this function can return various bits of information about the current environment and ZOC session.

COMPUTERNAME
 

The name of the computer on which ZOC is running.

CONNECTEDTO
 

The host name, ip, or phone number to which ZOC is connected.

CURRENTDEVICE
 

The name of the currently active communication method, e.g. Telnet.

CURRENTEMULATION
 

The name of the currently active emulation, e.g. Xterm.

CURRENTLOGFILENAME
 

Current file name for logging (without path).

CURRENTSCRIPTNAME
 

Filename and path of the main script which is currently executed (this will not return sub-scripts which are executed via CALL from inside another script).

CURRENTSESSIONPROFILENAME
 

The filename and full path of the current session profile.

CURSOR-X
 

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

CURSOR-Y
 

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

DESKTOPSIZE
 

The net size of the Windows/macOS desktop in pixels (excluding taskbar, dock, etc.)

DOWNLOADDIR
 

The default drive and directory for downloads.

EXEDIR
 

The drive and directory in which ZOC has been installed.

LASTDOWNLOADEDFILE
 

The name and path of the last downloaded file.

MARKEDAREA
 

The start/end position and mode of the marked area in the form x1,y1,x2,y2,mode (positions are zero based) or the string ##NONE##.

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, e.g. Windows 10.

OWNIP
 

Returns the computer's IPV4 address in the local LAN or WLAN.

PROCESSID
 

ZOC's system process id.

SCREENHEIGHT
 

Height (number of lines) of the terminal.

SCREENWIDTH
 

Width (number of characters) of the terminal.

TRANSFER
 

Information if a file transfer is currently active: ##YES##, ##NO##

TN3270FIELDATTR x y
 

The TN3270 field attributes and colors of a given screen location (x,y are zero based numbers) in the form attr foreground background flags...

UPLOADDIR
 

The default drive and directory for uploads.

USERID
 

The ID of the currently logged in user.

VERSION
 

The current ZOC version, e.g. 7.24

VERSIONEX
 

The current ZOC version including beta version (if any), e.g. 7.24b

WINPOS
 

A string indicating the position and size of the program window on the screen.

WORKDIR
 

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


 
Example:
ver= ZocGetInfo("VERSIONEX")
SAY "ZOC "||ver
    
CALL ZocTimeout 30
timeout= ZocWait("Password")
IF timeout=640 | ZocGetInfo("ONLINE")<>"##YES##" THEN DO
    SIGNAL PANIC /* disconnected! */
END

ZocGetProgramOption(<key>)
 

Retrieves the key-value pair for a ZOC program option (see ZocGetSessionOption and ZocSetProgramOption for more info about key-value pairs).
 
Example:

pair= ZocGetProgramOption("DisconEndProg")
PARSE VALUE pair WITH key"="value
IF value=="yes" THEN DO
    SAY "ZOC will terminate after this session."
END

 
See also: ZocGetSessionOption, ZocSetSessionOption, ZocSetProgramOption

ZocGetScreen(<x>,<y>,<len>) or ZocGetScreen("<alias>")
 

The ZocGetScreen() function can be used to return characters that are currently displayed in ZOC's terminal window. It returns <len> characters beginning from position <x>,<y> (zero based). If it reaches the right margin, it continues on the next line without adding a CR or LF.

There are also a few short versions for common combinations of x,y and len:
ALL: The whole screen (i.e. from position 0/0 with length SCREENWIDTH*SCREENHEIGHT)
LEFTOFCURSOR: The text left of the cursor (position= 0/CURSOR-Y, length= CURSOR-X)
CURRENTLINE: The whole line where the cursor is (position= 0/CURSOR-Y, length= SCREENWIDTH)


 
Example:

curline= ZocGetScreen("LEFTOFCURSOR")
SAY "^M"
SAY "The text before the cursor was: "||curline

 
Example:
width= ZocGetInfo("SCREENWIDTH")
posy= ZocGetInfo("CURSOR-Y")
screenpart= ZocGetScreen(0,0, posy*width)
IF POS("#", screenpart)=0 THEN DO
    SAY "There is no hash-character on screen above the cursor."
END

 
Example:
cx= ZocGetInfo("SCREENWIDTH")
cy= ZocGetInfo("SCREENHEIGHT")
    
-- loop through all lines on screen
DO y= 0 TO cy-1
    line= ZocGetScreen(0,y, cx)
    -- check each line for some text
    IF POS("**SUCCESS**", line)>=1 THEN DO
        Call ZocMessageBox "Found **SUCCESS* on screen in line "||y
    END
END

 
See also: ZocGetInfo("CURSOR-X"), ZocGetInfo("CURSOR-Y"), ZocGetInfo("SCREENWIDTH"), ZocGetInfo("SCREENHEIGHT")

ZocGetSessionOption(<key>)
 

Retrieves the key-value pair for a ZOC option from the session profile (see the ZocSetSessionOption command for more details).
 
Example:

pair= ZocGetSessionOption("Beep")
PARSE VALUE pair WITH key"="value
IF value=="no" THEN DO
    SAY "The beep option is turned off."
END

 
Example:
pair= ZocGetSessionOption("EnqString")
PARSE VALUE pair WITH key'="'value'"'
SAY "The configured answer to enq is: "||value

 
See also: ZocSetSessionOption, ZocGetProgramOption, ZocSetProgramOption

ZocGlobalStore(<operation>, [<options>])
 

This group of functions allows permanent storage of values in a file based data pool. This can be used to remember values across various script runs (the operations are atomic and they are protected against concurrent access).

Possible operations are:

SELECT <name>
 

Select a different global store. With the exception of the name VOLATILE, the name will be used to create a file name in the form <name>Global.ini in the user data folder or it can point to a different location, e.g. C:\data\mypool (which will then also become mypoolGlobal.ini).

The name VOLATILE refers to a special pool that is only held in memory and which is shared across all sessions. It will lose its values when the last session is closed.

INIT
 

Clear all values within the data pool.

GET <name>
 

Returns the value with the given name or an error (see below).

SET <name>, <value>
 

Stores a value in the storage pool under a given name. Returns ##OK## or error (see below).

PUT <name>, <value>
 

Same as SET.

Concurrent access to the store is protected using file locks. This will even work with access from multiple computers if the global store is located on a network drive.

Return codes for the GET, SET and PUT commands include the values ##OK##, ##LOCKERROR## if the lock can not be obtained and ##FILEERROR## if the file can not be accessed.


 
Example:

CALL ZocGlobalStore "SELECT", "MyValStore"
x= ZocGlobalStore("GET", "LASTX")

CALL ZocGlobalStore "SET", "LASTX", x
    
ret= ZocGlobalStore("SET", "VAL", "OK")
IF ret\="##OK##" THEN SAY "Could not set value"

ZocKeyboard(<command> [, <timeout>])
 

This function allows a REXX script to read keystrokes from the terminal window. It supports the subcommands LOCK, UNLOCK and GETNEXTKEY.

LOCK
 

Lock the keyboard and prevent user input.

UNLOCK
 

Unlock the keyboard from a previous LOCK state.

GETNEXTKEY
 

Wait for the next keystroke and return it. You can also specify a timeout in seconds and if successful, GETNEXTKEY will return a string in the form char|scancode|shift|ctrl|alt.

char: two byte hex number representing the ascii code of the key.
scancode: The physical scan code from the keyboard (the scan code can be used to identify functional keys such home, del, f1, f2, etc.).
shift, ctrl and alt are either 0 or 1 indicating if they were held down when the primary key was pressed.

The example below shows how the subcommands are used and how the possible result can be split into its parts and displayed in a user friendly form.

 
Example:
CALL ZocKeyboard "UNLOCK"
ret= ZocKeyboard("GETNEXTKEY", 30)
PARSE VALUE ret WITH hexkey"|"scan"|"shift"|"ctrl"|"alt
key= X2C(hexkey)
SAY "You pressed hex/key: "hexkey"/"key
SAY "Scan code: "scan
SAY "Shift/Ctrl/Alt states: "shift"/"ctrl"/"alt

ZocLastLine()
 

This is a function and returns the last line of text that was received from the point the last ZocWait/ZocWaitMux/ZocWaitLine command was issued to the point when it successfully returned

 
Example:

CALL ZocSend "ATZ^M"
timeout= ZocWaitMux("OK", "ERROR")
IF timeout\=640 & THEN DO
    IF ZocLastLine()\="OK" THEN SIGNAL error
    CALL ZocConnect "555 3456"
END

 
Note: In many cases, using ZocReceiveBuf instead will be the more flexible choice. ZocGetScreen("LEFTOFLINE") often also provides a similar result.
 
Note: Also see the examples in the description for ZocWaitLine

ZocListFiles(<path\mask> [, <separator>])
 

The ZocListFiles function will retrieve a list of filenames for a directory.

The first parameter is a directory name and wildcard mask (e.g. "c:\data\*.*").

The function will return a string which contains the number of files and the file names separated by space characters, e.g. "3 download.zip sales.txt foobar.fil"

This allows easy access to the parts of the string via REXX's WORD function (see example below). If you expect filenames to contain space characters you can provide a different list separator as the second parameter. E.g. a separator of "|" will return the string "3 download.zip|sales.txt|foobar.pdf". In this case you can use ZocString("PART", purelist, i, "|") to extract the file names.

Note: The number of filenames returned is limited to 128 and the maximum length of the total string returned is 4096.

 
Example:

files= ZocListFiles("C:\TEMP\*")
    
howmany= WORD(files, 1)
SAY "Number of Files:" howmany
    
purelist= SUBSTR(files, LENGTH(howmany)+2)
DO i=1 TO howmany
    SAY "File " i "=" WORD(purelist, i)
END

 
See also: ZocFilename, ZocGetFilename, ZocGetFilenames, ZocGetFolderName, ZocString

ZocLoadKeyboardProfile [<zkyfile>]
 

Loads and activates a keyboard profile (*.zky file).
 
Example:

CALL ZocLoadKeyboardProfile "Alternate.zky"

ZocLoadSessionProfile <optsfile>
 

Loads and activates a session profile file (*.zoc).
 
Example:

CALL ZocLoadSessionProfile "Zoc4Linux.zoc"

ZocLoadTranslationProfile [<ztrfile>]
 

Loads and activates a character translation profile (*.ztr).
 
Example:

CALL ZocLoadTranslationProfile "7bitgerman.ztr"

ZocMath(<function>, <arg>[, <arg2>])
 

ZocMath calculates the math function based on the argument(s). Valid functions are sin, cos, tan, asin, acos, sqrt, todeg, torad, bitand, bitor, bitxor.
 
Example:

angle = 270
anglerad = ZocMath("torad", angle)
sinresult = ZocMath("sin", anglerad)
lowbits = ZocMath("bitand", 175, 15)
hibits = ZocMath("bitand", X2D(A5), X2D(F0))

ZocMenuEvent <menu text> [, <file>]
 

Perform a function from the ZOC menu. The <menu text> is a text that matches an entry in the ZOC menu. The <file> parameter is an optional file name which some menu events accept rather than prompting the user for a file.
 
Example:

CALL ZocMenuEvent "Paste (no line breaks)"
CALL ZocMenuEvent "Edit REXX Script", "test.zrx"

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

Display a message box with the given text (a ^M in the text creates a line break).

Normally an informational message window with an OK button (mode 0) is shown. Mode 1 shows an error message with an OK button. Mode 2 shows a message with a YES and NO button.

The return value is either ##OK## or ##YES## or ##NO##.
 
Example:

CALL ZocMessageBox "Connect Failed!", 1
ret= ZocMessageBox("The operation failed^M^MTry again?", 2)
IF ret=="##YES##" THEN DO
   …
END

 
See also: ZocAsk, ZocAskPassword, ZocRequest, ZocRequestList
ZocNotify <text> [, <duration>]
 

Display a small floating message at the center of the window. If duration is given, controls the time in milliseconds which the window will stay on screen.
 
Example:

CALL ZocNotify "Hello World!", 1500

ZocPlaySound <file>
 

Plays a .WAV file.
 
Example:

CALL ZocPlaySound "ka-ching.wav"

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 a parameter indicating the size of the next receive buffer. After that, incoming data is added to the buffer until either the buffer is full or until the function is called again. Calling ZocReceiveBuf again will retrieve the buffer's content, reset the content and set a new size for the buffer.

A sequence of calls to ZocReceiveBuf in order to retrieve text from a database will look like this:
 
Example:

/* make a receive buffer of 256 bytes */
CALL ZocTimeout 60
    
CALL ZocReceiveBuf 256
CALL ZocSend "read abstract^M"
CALL ZocWait "Command>"
    
/* get the result from the read command and */
/* make a larger buffer to hold the result of */
/* a subsequent command. */
abst= ZocReceiveBuf(4096)
CALL ZocSend "read contents^M"
CALL ZocWait "Command>"
    
/* get the content and discontinue buffering */
cont= ZocReceiveBuf(0)
    
/* At this point, both variables (abst and cont) will start
with the word "read" and end with the character ">", containing
whatever data was received between the command and next prompt. */

 
Example:
/* read the remote environment variables and extract the TERM= value */
    
Call ZocReceiveBuf 2048
Call ZocSend "set^M"
    
/* you will need to wait for the your own prompt here */
Call ZocWait "PROMPT: ~username$"
data= ZocReceiveBuf(0)
    
/* google for "REXX PARSE COMMAND" to get more details
  on the PARSE command which is used to extract the data */
PARSE VALUE data WITH ."TERM="term .
    
SAY "The remote term setting is " term

 
Note: If executed via DDE, the ZocReceiveBuf command must be sent as a DdeRequest (rather than DdeExecute)
 
Note: See also ZocWaitForSeq and ZocString("LINE" …)

ZocRegistry(<subcommand>[, <options>])
 

This group of commands allows access to the Windows registry.

OPEN <basekey>, <name>
 

Return a <hkey> handle for access to a part of the registry. Basekey can be HKEY_CURRENT_USER or HKEY_LOCAL_MACHINE.

OPEN returns a hkey value which can be used to read/write this part of the registry.

WRITE <hkey>, <value>, <data>
 

Writes <data> to the part of the registry which is associated with <hkey>. If <data> is provided in the form "DWORD:n" the decimal value n will be stored as REG_DWORD. If <data> is provided in the form "BINARX:xxxxxx…", then xxxxxx… is converted from a hex string to bytes and will be stored as REG_BINARY. Otherwise <data> will be stored as REG_SZ (string).

READ <hkey>, <value>
 

Read a value from the registry part <hkey>. If the registry value is in REG_DWORD format, the command will return "DWORD:n". If the value is in REG_BINARY format, the command will return "BINARY:xxxxxx…", where xx… represents a hex-string (the hex-string can be converted to bytes via the REXX X2C function). Values of type REG_SZ will be returned without prefix, i.e. the command will simply return the string from the registry.

ENUM <hkey>, <n>
 

Returns the <n>th value name from <hkey> or ##ERROR## if no such value exists.

TEST <hkey>, <value>
 

This function tests, if the given value exists and returns either ##ERROR##, or a string in the form ##OK## TYPE nt LENGTH nl, where nt and nl are a decimal values indicating the type of the entry and the length of the data.

CLOSE <hkey>
 

Ends access to <hkey>.


 
Example:
hk= ZocRegistry("OPEN", "HKEY_CURRENT_USER", "Software\Emtec\ZOC8")
IF hk=="##ERROR##" THEN EXIT
CALL ZocRegistry "WRITE", hk, "Test01", "Hello World"
CALL ZocRegistry "WRITE", hk, "Test02", "DWORD:1"
CALL ZocRegistry "WRITE", hk, "Test03", "BINARY:5A4F43"
SAY ZocRegistry("TEST", hk, "%ZOC%")
homepath= ZocRegistry("READ", hk, "%ZOC%")
SAY "ZOC installed in "||homepath
i= 0
DO FOREVER
    x= ZocRegistry("ENUM", hk, i)
    IF x=="##ERROR##" THEN LEAVE
    i= i+1
    SAY "Value named "||x
END
    
CALL ZocRegistry "CLOSE", hk
EXIT

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

Displays a dialog window with options and returns a string containing the selected option.
 
Example:

answer= ZocRequest("What do you want?", "Milk", "Honey")
IF answer=="Milk" THEN DO
    …
END

 
See also: ZocAsk, ZocAskPassword, ZocMessageBox, ZocRequestList
ZocRequestList(<title>, <opt1> [, …]])
 

Displays a dialog window with a list of options and returns 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= ZocRequestList("Please select!", "Beer", "Wine", "Whiskey", "Gin")
IF answer=3 THEN DO
    …
END
    
answer= ZocRequestList("Please select!", "Beer|Wine|Whiskey|Gin")
IF answer=3 THEN DO
    …
END

 
See also: ZocAsk, ZocAskPassword, ZocMessageBox, ZocRequest
ZocRespond <text1> [, <text2>]
 

Send text2 whenever text2 is received while REXX is processing a ZocDelay or ZocWait command.

A maximum of 64 Respond commands can be active simultaneously. <text1> must not contain carriage returns or line feeds.

If text2 is omitted or empty the response command for <text1> is cleared. If text1 is empty ("") all responses are cleared.
 
Example:

/* Wait for 'Command' and auto-skip all possibly prompts in between */
CALL ZocRespond "Enter", "^M"
CALL ZocRespond "More", "^M"
timeout= ZocWait("Command")
/* Clear responders */
CALL ZocRespond "Enter"
CALL ZocRespond "More"

The above example waits until the text Command is received. While waiting, all Enter and More prompts are answered automatically by sending Enter. After the Wait is satisfied, the respond commands are cancelled.

ZocSaveSessionProfile [<optsfile>]
 

Save the current session profile to file. If the <optsfile> parameter is omitted, ZOC will ask the user for a filename.
 
Example:

CALL ZocSetSessionOption "JumpScroll=3"
CALL ZocSaveSessionProfile "Fastscroll.zoc"

 
See also: ZocCommand("SAVESESSIONPROFILE")
ZocSend <text>
 

Sends the given text to the remote host.

Internally the text sending is processed as a series keystrokes rather than sending it directly through the low level communication channel. The send speed is based on the text sending option int Options→Session Profile→Text Sending. If you need a faster, more direct version of this command, please use ZocSendRaw

Also, if the text contains control codes (e.g. ^M for Enter), are replaced with their respective values. For nearly all emulations these control codes are based on the control codes. Exceptions are the TN3270 and TN5250 emulations, where ^M is interpreted as Newline/FieldExit, ^I as Tab and ^Z as Transmit/Enter.


 
Example:

/* send JOE USER<enter>*/
CALL ZocSend "JOE USER^M"

 
Example:
/* Unix login Sequence */
CALL ZocWait "login:"
CALL ZocSend "harry^M"
CALL ZocWait "password:"
CALL ZocSend "alohomora^M"

 
Example:
/* 3270/5250 example */
CALL ZocSetCursorPos 12,5
CALL ZocSend "Freddie"
CALL ZocSendEmulationKey "NewLine"
CALL ZocSend "Elm Street"
CALL ZocSendEmulationKey "Enter"
    
/* 3270/5250 same as above */
CALL ZocSend "Freddie^MElm Street^Z"

 
See also: ZocSendRaw, ZocSendEmulationKey.

ZocSendEmulationKey <keyname>
 

Send the code that represents a special key in the current terminal emulation, e.g. send F17 from a VT220 emulation or Attn under TN3270.

The key names are described in the Key Names Appendix.
 
Example:

CALL ZocSendEmulationKey "f17" /* Send F17 based on current emulation */

ZocSendRaw <datastring>
 

This command sends the data from datastring in untranslated form. The command does not translate control sequences like ^M. If you need to send such codes, you will have to use the REXX string functions like X2C(<hexcode>) or ZocCtrlString to create a corresponding character values (e.g. X2C(0D) for Enter).

ZocSendRaw may be useful if you want to send binary data to a host. For example, if you want to send 42 01 00 05 41 43 (hex) through the communication channel, you can do this as in the 2nd part of the example below.
 
Example:

CALL ZocSendRaw "Login"||X2C(0d) /* Login<enter> */
    
/* Four times the same result: */
CALL ZocSendRaw X2C(420100054143)
CALL ZocSendRaw "B"||X2C(01)||X2C(00)||X2C(05)||"AC"
CALL ZocSendRaw ZocCtrlString("B^A^@^EAC")
CALL ZocSend "B^A^@^EAC"

 
See also: ZocSend, ZocSendEmulationKey, ZocCtrlString
ZocSessionTab(<subcommand>, <parameters>)
 

This function allows a REXX script to access or manipulate session tabs. The subcommand defines the action, the parameters depend on the subcommand.

CLOSEATEXIT
 

Close the current session tab when the script exits.
 
Example:  CALL ZocSessionTab "CLOSEATEXIT"

CLOSETAB
 

Close the session tab with the given index (zero for the leftmost tab or -1 for the current tab).
 
Example:  CALL ZocSessionTab "CLOSETAB", 2

GETCOUNT
 

Returns the number of session tabs.
 
Example:  howmany= ZocSessionTab("GETCOUNT")

GETCURRENTINDEX
 

Returns the index of the tab in which this script is running.
 
Example:  myidx= ZocSessionTab("GETCURRENTINDEX")

GETINDEXBYNAME, <name>
 

Returns the index of the first tab that has a given title or -1 if none was found.
 
Example:  srvidx= ZocSessionTab("GETINDEXBYNAME", "My Server")

GETNAME, <index>
 

Return the name of the tab with a given index (zero for the leftmost tab) from the 1st parameter. An index of -1 refers to the session in which the script is running.
 
Example:  name= ZocSessionTab("GETNAME", -1)

ISCONNECTED, <index>
 

Returns ##YES## or ##NO## depending on if the tab with the given index has an active connection.
 
Example:  yesno= ZocSessionTab("ISCONNECTED", 2)

NEWSESSION, <title>, <activate>, <sessionprofile>[, <connectto>, <script>]
 

Create a new session and return the new session's index.

Parameters:
<title>: A string naming the tab.
<activate>: 0 or 1 depending on if the new tab should be in the background or active.
<sessionprofile>: name of a session profile (e.g. MyProfile.zoc) or ##NULL## for default.
<connectto>: A string as described with the /CONNECT command line parameter or a string prefixed with CALL: followed by the name of an entry in the host directory or ##NULL## for none.
<script>: The name of a script file to run in the new tab.

 
Example:

idx1= ZocSessionTab("NEWSESSION", "Test1", 1, "##NULL##", "CALL:My Server")
    
idx2= ZocSessionTab("NEWSESSION", "Test2", 0, "SSHProfile.zoc", "SSH!Harry:alohomora@ssh.hogwarts.edu")
    
idx3= ZocSessionTab("NEWSESSION", "Test3", 1, "##NULL##", "##NULL##", "test.zrx")
CALL ZocSessionTab "SETCOLOR", idx3, 5
    
idx4= ZocSessionTab("NEWSESSION", "Test4", 1, "Standard.zoc", "TELNET!smtp.hogwarts.edu:25", "test.zrx")

MENUEVENT, <index>, <menu>
 

Performs a command from the ZOC menu in a different session. The <index> parameter indicates the session (see the description of the <index> parameter for GETNAME), the <menu> parameter is the same as for ZocMenuEvent.
 
Example:  CALL ZocSessionTab "MENUEVENT", idx, "Disconnect"

RUNSCRIPT, <index>, <title>
 

Starts a script in a different session. The <index> parameter indicates the session (see description of the <index> parameter for GETNAME). Please note that this will not work for sessions which already have a script running (including the session/script which issues the ZocSessionTab("RUNSCRIPT", …) command.
 
Example:  CALL ZocSessionTab "RUNSCRIPT", newidx, "configure.zrx"

SEND, <index>, <text>
 

Sends text to the session with the given index (similar to using the ZocSend command).
The <index> parameter indicates the session (for details see description of the <index> parameter for GETNAME).  
Example:  CALL ZocSessionTab "SEND", 2, "exit^M"

SETCOLOR, <index>, <color>
 

Sets the color of the tab with a given index. The <index> parameter indicates the session (for details see the description of the <index> parameter for GETNAME). The color is a number between 0 and 7.
 
Example:  CALL ZocSessionTab "SETCOLOR", -1, 4

SETBLINKING, <index>, <blinkflag>
 

Activates or deactivates the blinking for the tab with a given index. The <index> parameter indicates the session (for details see the description of the <index> parameter for GETNAME). The <blinkflag> is either 1 or 0.
 
Example:  CALL ZocSessionTab "SETBLINKING", -1, 1

SETNAME, <index>, <title>
 

Sets the name of the tab with a given index. The <index> parameter indicates the session (for details see the description of the <index> parameter for GETNAME).
 
Example:  CALL ZocSessionTab "SETNAME", -1, "This Session"

SWITCHTO, <index>
 

Activate the tab with a given index. The <index> parameter indicates the session (for details see the description of the <index> parameter for GETNAME).
 
Example:  CALL ZocSessionTab "SWITCHTO", 2


 
Example:
/* ZocSessionTab sample: send a text to all tabs */
    
text= ZocAsk("Command to send to all other tabs:")
IF text\="##CANCEL##" THEN DO
  n= ZocSessionTabs("GETCOUNT")
  c= ZocSessionTabs("GETCURRENTINDEX")
  SAY n
  DO i=0 TO n-1
    IF i==c THEN ITERATE
    name= ZocSessionTabs("GETNAME", i)
    CALL ZocSessionTabs "SEND", i, text||"^M"
    SAY "Sent "||text||" to "||name
  END
END

ZocSetAuditLogname <filename>
 

Set the file name for the audit log (a logfile that can not be turned off by the user, also see the setting in the ADMIN.INI file in the program folder) or turn off audit logging with "" (empty string) as a filename.

ZocSetAutoAccept 1|0
 

For those connection types that support it (e.g. Telnet), make the communication method accept incoming connections.
 
Example:

CALL ZocSetDevice "Telnet"
CALL ZocSetAutoAccept 1 /* accept calls */

ZocSetCursorPos <row>, <column>
 

This command moves the cursor to the given position on a TN3270 screen (in other emulations the command is ignored). The positions are 1-based, i.e. the top/left position on screen is 1/1.
 
Example:

CALL ZocSetCursorPos 1,15
Call ZocSendEmulationKey "Enter"

ZocSetDevice <name> [, <commparm-string>]
 

Change the connection type (communication device). The name must be one of the names from the list in Options→Session Profile→Connection Type.

The optional commparm-string contains options, which can further tweak the operation of that connection (e.g. setting Telnet-specific options, see ZocSetDeviceOpts for information about how to obtain a commparm-string). If the comm parameters are omitted, ZOC uses the options which are set for the connection type in the currently active session profile.
 
Example:

CALL ZocSetDevice "Telnet"
CALL ZocConnect "bbs.channel1.com"

 
Example:
CALL ZocSetDevice "SERIAL/MODEM", "[1]COM3:57600-8N1|9|350"

ZocSetDeviceOpts <parameter-string>
 

This is a rather arcane command, which sets the options for a communication method (device) directly from REXX. However, since the options strings for the device are not standardized, in order to find a specific parameter string, you will need to set the options manually in the session profile dialog and then query the current connection type's parameter string by pressing Shift+Ctrl+F10 in ZOC's main window.

Let us assume you want to start a modem session on COM3 with 57600 bps, RTS/CTS and Valid-CD active and a break time of 350ms.

1. Go to Options→Session Profile→Connection Type, select Serial/Modem and the set these options.
2. Close the session profile window using 'Save'
3. Press Shift+Ctrl+F10
4. The status output from that connection type will show the current device-parameter [1]COM3:57600-8N1|9|350 which you can use as a parameter to the ZocSetDeviceOpts command.

 
Example:

/* Set serial options to:
   COM3, 57600-8N1, RTS/CTS, Valid-CD, 350ms */
CALL ZocSetDeviceOpts "[1]COM3:57600-8N1|9|350"

 
Example:
/* Select telnet and set options for
   "Start session with local echo" */
CALL ZocSetDevice "TELNET"
CALL ZocSetDeviceOpts "[3]12"

ZocSetEmulation <emulationname>[, <emuparm-string>]
 

The ZocSetEmulation command allows a script to activate a different terminal emulation. The parameter can be one of the names shown in the Emulation section of the session profile dialog, e.g. VT220, TN3270, etc.
The optional emuparm parameter contains optional settings that configure emulation dependent options (otherwise the settings from the current session profile are used).
 
Example:

CALL ZocSetEmulation "Xterm"

ZocSetHostEntry "name", "<key>=<value>"
 

Sets a value for a host directory entry from a key-value pair. To find actual names for these key-value pairs, please check the file HostDirectory.zhd (stored in the ZOC data folder) using an editor. The file contains all the key-value pairs that make up your host directory.
If instead of a key-value pair, you pass the string "##NEW##", a new host directory entry with that name will be created (if it does not yet exist). You can then configure it with subsequent calls that provide key-value pairs.
See the ZocSetSessionOption command for more background about key-value pair handling in general.

 
Example:

CALL ZocSetHostEntry "MyBBS", "emulation=1"
    
pair= ZocGetHostEntry("ZOC Support BBS", "calls")
PARSE VALUE pair WITH key"="value
value= value+1
CALL ZocSetHostEntry "ZOC Support BBS", "calls="||value
    
/* mind the mixture of quotes in the commands below */
value= "555-1234"
CALL ZocSetHostEntry "ZOC Support BBS", 'connectto="555-1234"'
CALL ZocSetHostEntry "ZOC Support BBS", 'connectto="'||value||'"'

 
Example:
name= "My Router"
Call ZocSetHostEntry name, "##NEW##"
Call ZocSetHostEntry name, 'connectto="192.168.1.1"'
Call ZocSetHostEntry name, 'username="root"'
Call ZocSetHostEntry name, "deviceid=9"
Call ZocSetHostEntry name, "emulationid=3"

 
See also: ZocSetSessionOption, ZocGetHostEntry

ZocSetLogfileName <filename>
 

Set new name for logging.
 
Example:

CALL ZocSetLogfileName "Today.LOG"

ZocSetLogging 0|1 [,1]
 

Suspend/resume logging. If a second parameter with value 1 is given, ZocSetLogging will suppress the notification window.
 
Example:

CALL ZocSetLogging 1

ZocSetMode <key>, <value>
 

This commands allows you to set operation modes for some of the script commands. The following modes are supported:

SAY
 

A value of RAW sets the SAY command to not convert control codes like ^M into their respective character values. A value of COOKED switches back to standard behavior.
 
Example:

CALL ZocSetMode "SAY", "RAW"

RESPOND
 

A value of RAW sets the respond command to not convert control codes like ^M into their respective values for both sides of the command.
 
Example:

CALL ZocSetMode "RESPOND", "RAW"

ZocSetProgramOption "<key>=<value>"
 

This command modifies a ZOC option from the Options→Program Settings dialog. (similarly ZocSetSessionOption modifies the Options→Session Profile). The function basically works the same as ZocSetSessionOption but the underlying file which contains the key-value pairs is Standard.zfg. You can load the file into an editor and you will see that the key names are mostly self explanatory. If you have problems finding a specific key or value, you can start the REXX script recorder, change the options, stop the recording and look at the resulting script.
 
Example:

CALL ZocSetProgramOption "SafAskClrCapt=yes"
CALL ZocSetProgramOption 'ScriptPath="ZocREXX"' /* mind the quotes */
CALL ZocSetProgramOption 'ScriptPath="'||pathvar||'"' /* mind the quotes */

 
See also: ZocCommand("SAVEPROGRAMSETTINGS"), ZocGetSessionOption, ZocSetSessionOption, ZocGetProgramOption

ZocSetSessionOption "<key>=<value>"
 

Sets a ZOC option from the Options→Session Profiles window, based on a key-value pair. To find out more about the key-value pairs, please have a look at the contents of the Standard.zoc file (or any other *.zoc session profile). The file contains all the key-value pairs, which make up a session profile.

If you are not sure what the value of a certain key means, just set the option you want to change in the options window, then click Save and check the options file for the new key-value pair. Or you can also start the REXX script recorder, then make the changes to the session profile and then stop recording and look at the resulting script.
 
Example:

CALL ZocSetSessionOption "JumpScroll=3"
CALL ZocSetSessionOption "ShowChat=no"
CALL ZocSetSessionOption 'MdmIni="ATZ^M"' /* mind the quotes */
CALL ZocSetSessionOption 'TransAutoRemove="'||valvar||'"' /* mind the quotes */

 
Note: ZocSetSessionOption/ZocGetSessionOption will only work for options from the Options→Session Profile dialog. To change Options→Program Settings, use ZocSetProgramOption.
 
See also: ZocCommand("SAVESESSIONPROFILE"), ZocSaveSessionProfile, ZocGetSessionOption, ZocGetProgramOption, ZocSetProgramOption

ZocSetTimer <hh:mm:ss>
 

Set connection timer to given time. If called with an empty parameter, the function will return the current duration of the session timer in seconds. Calling the function with a parameter string "STOP" will hold the timer and "RESUME" will continue with a held timer.
 
Example:

CALL ZocSetTimer "00:00:20"

ZocSetUnattended 0|1
 

Enable or disable ZOC's unattended mode (same as command line parameter /U).
 
Example:

CALL ZocSetUnattended 1

ZocShell <command>, [<viewmode>]
 

Execute a command or program in a shell window via cmd.exe /c <command> (Windows) or /bin/bash -c "<command>" (macOS). This is similar to using to REXX's native ADDRESS CMD "<command>" and essentially allows the execution of anything that you can execute in the shell/terminal window of the operating system.

Windows only: The optional viewmode parameter controls how the black shell window is shown:
0= normal, 1= hidden, 2= minimized, 3= maximized.

In many cases ZocShell is identical to using the native REXX shell interface via ADDRESS CMD "<command>"
 
Example:

CALL ZocShell "DEL FILE.TMP"
CALL ZocShell "touch /tmp/file.lck", 1

 
See also: ZocShellExec, ZocShellOpen, ZocFileDelete, ZocFileRename

ZocShellExec <command>[, <viewmode>]
 

Execute a program directly (i.e. without passing it through the shell's command interpreter, thus avoiding the overhead of running the shell). Under Windows this only works for .com and .exe files (i.e. it will not work for .CMD scripts and internal shell commands like DEL, REN etc.).

The optional viewmode parameter controls how the application window is shown:
0= normal, 1= hidden, 2= minimized, 3= maximized.

ZocShellExec also returns the exit code of the application to the REXX script.
 
Example:

CALL ZocShellExec 'notepad.exe "somefile.txt"'

 
See also: ZocShell, ZocShellOpen

ZocShellOpen <filename>
 

This function is somewhat equivalent of a double click on a file, because it passes a filename to the operating system with a request to open it. The operating system will then start the program which is associated with the type of that file (e.g. a PDF viewer for PDF files or Notepad for TXT files).

Alternately, an URL can be passed as a parameter instead of a filename.
 
Example:

CALL ZocShellOpen 'C:\DOWNLOADS\Report.pdf'

 
Example:
CALL ZocShellOpen 'https://www.emtec.com/'

 
See also: ZocShell, ZocShellExec

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.

LINE
 

Return the <p1>th element of <inputstring> which is delimited by a line feed (hex 0A) and stripped of leading or trailing carriage return characters (hex 0D) (simply speaking, this refers to the <p1>th line). This is useful to parse multiline results from a ZocReceiveBuf call, e.g. name= ZocString("LINE", data, 4) will return the 4th line from the data variable.

LINECOUNT
 

Returns the number of elements in <inputstring> which are accessible as LINE.

LOAD
 

Returns the content of the file with name <inputstring> (the file is loaded in text mode, line endings are converted to LF (hex 0A)). The LINE subcommand of ZocString can be used to extract lines from the result string.

SAVE
 

Saves the content of string <p1> in a file with name given in <inputstring> (the file is saved in text mode, LF line endings are converted to CR/LF under Windows).

MIME-ENCODE
 

Converts <inputstring> to base-64/MIME.

MIME-DECODE
 

Converts <inputstring> form base-64/MIME.

UTF8-ENCODE
 

Converts <inputstring> from an 8-bit string to UTF8.

UTF8-DECODE
 

Converts <inputstring> form an UTF8-string to 8-bit.

AES256-ENCRYPT
 

Encrypts the string <p1> via AES256 using the encryption-key from <inputstring>. The result is MIME-encoded.

AES256-DECRYPT
 

Decrypts the MIME-encoded string from <p1> using the encryption-key <inputstring>.

PART
 

Return the <p1>th part of <inputstring> which is delimited by <p2>, e.g. name= ZocString("PART", "Anne|Charly|Joe", 2, "|") will return "Charly".

PARTCOUNT
 

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

REPLACE
 

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

REMOVE
 

Return a copy of <inputstring> where all occurrences 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.

TAB
 

Return the <p1>th element of <inputstring> which is delimited by a tab-character, e.g. name= ZocString("TAB", tabbed_data, 2)

TABCOUNT
 

Return the number of elements of <inputstring> accessible as TAB.

WORD
 

Return the <p1>th element of <inputstring> which is delimited by a space, e.g. name= ZocString("WORD", "The quick brown fox", 3) will return "brown". Same as REXX's native WORD() function.

WORDCOUNT
 

Return the number of elements of <inputstring> accessible as WORD.


 
Example:
CALL ZocReceiveBuf 1024
CALL ZocSend "ps^M"
CALL ZocWait "$"
data= ZocReceiveBuf(0)
    
/* display result list line by
   line but ignoring the first*/
howmany= ZocString("LINECOUNT", data)
DO i=2 TO howmany
    SAY ZocString("LINE", data, i)
END

 
Example:
key= "Secret.740.$%&"
n= ZocString("AES256-ENCRYPT", key, "Hello World!")
SAY "Encoded: "||n
n2= ZocString("AES256-DECRYPT", key, n)
SAY "Decoded: "||n2

 
See also: ZocCtrlString

ZocSuppressOutput 0|1
 

Enables or disables suppressing of screen output. This command allows you to send/receive characters without any screen activity. Logging to the capture buffer and to file is also suppressed.

Output suppression is automatically reset to normal when the script ends or upon disconnecting from a host.

ZocSynctime <time>
 

This command lets you define the sync-time period (the default time is 250ms).

Background: Because REXX programs are running parallel to ZOC, the main window may receive and process more incoming data while REXX is performing its own work. This means that in some situations it is possible that text, which you expect to be received and which are going to wait for, has actually already scrolled by.

A typical example for this is a loop that attempts to process all incoming lines of text.

 
Example:

DO FOREVER
    timeout= ZocWaitLine()
    IF timeout\=640 THEN DO
     data= ZocLastLine()
     /* process data in some way */
    END
END

In this example ZOC could receive more text while the REXX program still processes the data from ZocLastLine and before it is ready to loop and issue the next ZocWaitLine.

To address this problem, ZOC's processing of incoming traffic is suspended for a short time period (the sync-time) whenever a Wait-command has been satisfied, thus giving the REXX program time to process the result and to get ready to wait for more data.

After a Wait-command (ZocWait, ZocWaitMux, etc.), ZOC will resume processing of incoming data either if the sync-time has elapsed or if the REXX program issues another Wait-command or if another command is processed, which needs to interact with the main window (ZocWrite, ZocSend, etc. but also SAY, TRACE, because those output to the main window).
 
Important: Instead of increasing the sync-time, in loops like the above, you should consider to merely collect and store the data for later processing (the ZocWaitLine command has an example of how to do this properly). An even better alternative is the use ZocReceiveBuf to catch all the data in one packet.

 
See also: ZocWait, ZocWaitIdle, ZocWaitLine, ZocWaitMux, ZocReceiveBuf, ZocLastLine

ZocTerminate [<return-code>]
 

Causes ZOC to end the program and close after the REXX program has ended. Usually an EXIT command will follow ZocTerminate.

If you supply the return-code parameter, the ZOC process will return this value to the operating system or to the calling program.
 
Example:

CALL ZocTerminate
EXIT

ZocTimeout <sec>
 

Set maximum time to wait for a ZocWait/ZocWaitMux/ZocWaitLine/ZocEventSemaphore command.
 
Example:

/* Make subsequent ZocWait commands expire after 30 seconds */
CALL ZocTimeout 30
    
/* Wait until the host sends 'ready' of until the timeout expires */
timeouttimeout= ZocWait("ready")
IF timeout=640 THEN SAY "ready-prompt not received within 30 seconds"

 
See also: ZocWait, ZocWaitIdle, ZocWaitLine, ZocWaitMux, ZocEventSemaphore, ZocSyncTime

ZocUpload <protocol>[:<options>], <path/filename>
 

Start to upload a file using the given file transfer protocol.

If the filename contains no path, it is taken from the standard upload folder, otherwise, if the path is relative, it is accessed relative to ZOC's program folder or relative to the upload folder.

For file transfer protocols which support multiple files (Ymodem, Zmodem), the file parameter may contain wildcards. Multiple filenames may be provided as one string in which the file names are separated by vertical bars *.pdf|somefile.txt

The protocol name is ASCII, BINARY or the name of the file transfer protocol from the Options→Session Profile→File Transfer dialog, e.g. Zmodem or Kermit.

Depending on the success of the transfer, ZocUpload will return ##OK## or ##ERROR##.

 
Example:

CALL ZocUpload "ZMODEM", "id_dsa.pub"
uploads id_dsa.pub from the local upload folder to the remote host using the Zmodem protocol.
 
Example:
success= ZocUpload("XMODEM", "updates.zip")
uploads the file updates.zip from the upload folder via Xmodem protocol and obtains a success indicator (##OK## or ##ERROR##).
 
Example:
CALL ZocUpload "BINARY", "CNC-CONTROL.DAT"
sends the contents of the file directly without any translation or protocol.
 
Example:
CALL ZocUpload "ASCII", "commands.txt"
uploads commands.txt using the text sending options which are currently configured in the session profile.
 
Example:
CALL ZocUpload "ASCII:CRONLY+10", "\FAR\AWAY\LIST.TXT"
uploads LIST.TXT via text/ascii transfer using CR-only as the end of line marker and a character delay of 10ms.
 
Example:
CALL ZocUpload "ASCII:1+3", "HERE\SOME.DATA"
uploads the file SOME.DATA via ascii transfer with CR/LF translation and a character delay of 3ms.


Transfer Options
For all protocols (except IND$FILE, ASCII and BINARY, see below), you can set the optional options by copying a string from a session profile which configures that protocol. To do this, set your desired protocol options in ZOC's Options→Session Profile→File Transfer dialog and query the current parameter string by pressing Shift+Ctrl+F10 in ZOC's main window.

Example: If you want to perform a file transfer via Xmodem using the CRC option and 1KB data blocks, you
1. Go to ZOC's Options→Session Profile→Transfer dialog, select Xmodem and configure these options.
2. Close the session profile window (click 'Save')
3. In ZOC's main window press Shift+Ctrl+F10
4. The status output will show the current transfer options "[0]kc" which you can use as a parameter to the ZocUpload command.
5. The REXX command will be CALL ZocUpload "XMODEM:[0]kc", "datafile.zip" (please note that the options are case sensitive).

Transfer Options ASCII
For the file transfer in ASCII mode (equivalent of Transfer→Send Text File), the options parameter has the format "mode+chardelay+linedelay", where mode specifies the end of line translation as a number or text (ASIS= 0, CRLF= 1, CRONLY= 2, LFONLY= 3) and delays are the per character and per line send delays, e.g. valid parameters would be 2+5+100 or CRONLY+5+100 (which means CR only with 5 milliseconds per character and 100 ms extra delay at the end of each line).

Transfer Options BINARY
For a file transfer in BINARY-mode (equivalent of Transfer→Send Text File), the options parameter can be a number. This number sets the character delay in milliseconds (otherwise the text sending delay from the session profile will be used).

Transfer Options IND$FILE
The IND$FILE file transfer type is an exception to the above. The options part for IND$FILE actually contains the corresponding host command to perform the transfer (you can look up this command at the bottom of the dialog which is shown when performing a manual file transfer via IND$FILE), e.g.:
CALL ZocUpload "IND$FILE:TSO IND$FILE PUT 'userid.projects.asm(report)' ASCII CRLF", "report.asm"

ZocWait(<text>)
 

Waits until the given text is received. If ZocWait times out (see ZocTimeout), it returns a value of 640.
 
Example:

CALL ZocTimeout 20
timeout= ZocWait("Password")
IF timeout=640 THEN SAY "Password prompt not received within 20 seconds"
ELSE CALL ZocSend "alohomora^m"

 
Example:
CALL ZocTimeout 10
    
timeout= ZocWait("enter command>")
IF timeout=640 THEN SIGNAL the_end
CALL ZocSend "ENABLE FIREWALL^M"
    
timeout= ZocWait("enter command>")
IF timeout=640 THEN SIGNAL the_end
CALL ZocSend "ENABLE IPFILTER^M"
    
timeout= ZocWait("enter command>")
IF timeout=640 THEN SIGNAL the_end
    
SAY "Firewall and Ip-Filter activated!"
    
the_end:
Call ZocDisconnct

 
Note: ZOC automatically filters ANSI/VTxxx/etc. control sequences from the data stream to avoid interference with the ZocWait command (see ZocWaitForSeq).
 
Note: If you are using ZocWait from a DDE controller, the command must be sent as via DDE-Request rather than via DDE-Execute.
 
Note: With the TN3270 and TN5250 emulations, the command can be used to wait for "^Z", which will be used as a signal that indicates that the emulation is ready to accept input again.

Also, because these emulations are transmitting whole screens at a time, you should only issue one ZocWait per screen. In other words, if a ZocWait("LOGON:") returns, you can assume that the whole logon-screen has arrived and is ready for input.

 
See also: ZocWaitIdle, ZocWaitLine, ZocWaitMux, ZocTimeout, ZocReceiveBuf, ZocLastLine, ZocSyncTime, ZocWaitForSeq

ZocWaitForSeq 1|0|"on"|"off"
 

Normally Wait-commands ignore emulation control sequences in the data stream. If you need to wait for an emulation control, you can use this command to enable their visibility to the Wait commands.

This command also turns on/off filtering of emulation controls for ZocReceiveBuf.
 
Example:

esc= ZocCtrlString("^[")
    
/* wait for VT220 color reset */
CALL ZocWaitForSeq "On"
Call ZocWait esc||"[0m"

 
See also: ZocWait, ZocWaiMux, ZocReceiveBuf

ZocWaitIdle(<time>)
 

Wait until there was no data received from the remote host for the given amount of time (in seconds).

If the host keeps sending data, the command will time out after the time set by ZocTimeout (a value of 640 will be returned to indicate the timeout).
 
Example:

CALL ZocTimeout 60
timeout= ZocWaitIdle(2.5)
IF timeout=640 THEN SAY "Host kept sending a steady stream of data for 60 seconds"
ELSE SAY "OK, finally the host did stop the chatter (2.5 seconds of silence detected)"

 
See also: ZocWait, ZocWaitLine, ZocWaitMux, ZocWaitNumChars, ZocTimeout, ZocSyncTime, ZocReceiveBuf, ZocLastLine

ZocWaitLine()
 

Wait for the next non empty line of text from the remote host (if you want to wait for the next line, no matter if empty or not, use EXMLPL(ZocWait "^M")).

The received text will then be available using the ZocLastLine function or it can be accessed with some extra coding via ZocReceiveBuf.

If ZocWaitLine times out, it returns a value of 640.
 
Note: Since REXX is running in its own thread, it is possible that ZocWaitLine will miss lines if new text is received by ZOC while the REXX program is still processing the previously received data. Thus, especially when using ZocWaitLine in a loop, you should just collect the data until it is complete and then process it in a 2nd pass (see the sample below and the description of the ZocSyncTime command).
 
Example:

rc= ZocWaitLine()
IF rc\=640 THEN DO
    reply= ZocLastLine()
    IF reply=="CONNECT" THEN …

 
Example:
/* issue a command that outputs a bunch of lines of data */
CALL ZocSend 'dig emtec.com && echo "<<END>>"^M'
    
/* first collect all the data and store it in an array */
n= 0
DO FOREVER
    timeout= ZocWaitLine()
    
    /* exit loop if no more data */
    IF timeout=640 THEN LEAVE
    
    line= ZocLastLine()
    
    /* exit loop on a line meeting some condition */
    IF line=="<<END>>" THEN LEAVE
    
    /* store line in array */
    n= n+1
    data.n= line
    data.0= n
END
    
/* when done, process each line of collected data in a 2nd pass */
DO i= 1 TO data.0
    line= data.i
    
    /* line can now leisurly be processed
     without fear of missing data */
END

 
See also: ZocWait, ZocWaitIdle, ZocWaitMux, ZocWaitNumChars, ZocTimeout, ZocSyncTime

ZocWaitMux(<text0> [, <text1> …])
 

Wait for one of multiple texts in the input data stream. The command will return if one of the given texts is found in the incoming data stream or after the default timeout has expired. The return code provides information about which text was found (0, 1, 2, …) or if the command timed out (return code 640).
 
Note: The sum of the lengths of all texts must not exceed 4096 characters.
 
Example:

CALL ZocTimeout 45
ret= ZocWaitMux("You have mail", "Main Menu")
SELECT
    WHEN ret=0 THEN CALL handle_maildownload
    WHEN ret=1 THEN LEAVE
    OTHERWISE SIGNAL handle_error
END

 
See also: ZocWait, ZocWaitIdle, ZocWaitLine, ZocWaitNumChars, ZocTimeout, ZocSyncTime

ZocWaitNumChars(<n>)
 

Waits for a specific number of characters be received. These could be any characters including newline or control characters. To find out which characters were received, set up a receive buffer (see ZocReceiveBuf) before issuing the ZocWaitNumChars command and read its content after the ZocWaitNumChars command returns.

If less than the given number of characters is received within the wait timeout (see ZocTimeout), the function will return the value 640.
 
Example:

CALL ZocTimeout 45
CALL ZocReceiveBuf 100
ret= ZocWaitNumChars(5)
IF ret\=640 THEN DO
   data= ZocReceiveBuf(0)
END

 
See also: ZocReceiveBuf, ZocWait, ZocWaitIdle, ZocWaitLine, ZocTimeout, ZocSyncTime

ZocWindowState(MINIMIZE|MAXIMIZE|RESTORE|ACTIVATE|MOVE:x,y|QUERY)
 

Set the State of ZOC's main window to the state given or moves the window to the given pixel coordinate (e.g. MOVE:20,100).

In used in function call syntax, the command will return new state of the window.

A parameter string of QUERY will just return the current window state as MINIMIZED, MAXIMIZED or RESTORED (please note the extra letter D at the end of those words).
 
Example:

now= ZocWindowState("QUERY")
IF now\="MINIMIZED" THEN DO
    CALL ZocWindowState "MINIMIZE"
END

ZocWrite <text>
 

Write text to screen. This command is similar to REXX's native SAY command, but it does not place the cursor in the next line after printing the text and it understands control codes like ^M (Enter) or ^[ (ESC).
 
Example:

/* use a VT220 escape sequence to highlight a word */
CALL ZocWrite "Hello ^[[1m World^[[0m"

ZocWriteln <text>
 

Write text to screen and skip to the next line. This command is similar to the REXX SAY command, but it resolves control codes (e.g. ^[ for ESC).
 
Example:

CALL ZocWriteln "Hello ^M^J World"
SAY "Hello"||X2C(0D)||X2C(0A)||"World"
 

 

 

Obsolete Functions

       
ZocAutoConnect
 

Renamed to ZocConnectHostdirEntry.

ZocAskP
 

Renamed to ZocAskPassword.

ZocBaud
 

Replaced by ZocSetDeviceOpts, e.g CALL ZocSetDeviceOpts "[1]38400-8N1".

ZocCaptClr
 

Replaced by ZocCommand("CLEARSCROLLBACK").

ZocCarrier()
 

Replaced by ZocGetInfo("ONLINE").

ZocCls)
 

Renamed to ZocClearScreen.

ZocCursor
 

Replaced by ZocGetInfo("CURSOR-X") and ZocGetInfo("CURSOR-Y").

ZocDial()
 

Renamed to ZocConnect.

ZocEndZoc()
 

Replaced by ZocTerminate.

ZocExec
 

Renamed to ZocShellExec.

ZocGetFilename(s)
 

Renamed to ZocAskFilename, ZocAskFilesnames.

ZocGetFolderName
 

Renamed to ZocAskFolderName.

ZocGetLine
 

Renamed to ZocWaitLine.

ZocGetPhonebk
 

Renamed to ZocGetHostEntry.

ZocGetOption
 

Renamed to ZocGetSessionOption.

ZocGlobal
 

Renamed to ZocGlobalStore.

ZocLockKeyboard
 

Replaced by ZocKeyboard("LOCK") and ZocKeyboard("UNLOCK").

ZocLoadOpts
 

Renamed to ZocLoadSessionProfile.

ZocLoadKeyfile
 

Renamed to ZocLoadKeyboardProfile.

ZocLogging
 

Renamed to ZocSetLogging.

ZocLogname
 

Renamed to ZocSetLogfileName.

ZocRestimer
 

Replaced by ZocSetTimer("00:00:00").

ZocSaveOpts
 

Renamed to ZocSaveSessionProfile.

ZocScreen
 

Renamed to ZocGetScreen.

ZocSendBreak
 

Replaced by ZocCommand("SENDBREAK").

ZocSendKey <number>
 

Please use ZocGetSessionOption and ZocSend instead.

ZocSetDevParm
 

Renamed to ZocSetDeviceOpts.

ZocSetDlPath
 

Please use CALL ZocSetProgramOption "DownloadPath=<path>" instead.

ZocSetPhonebk
 

Renamed to ZocSetHostEntry.

ZocSetEmu
 

Please use CALL ZocSetSessionOption "ActiveEmulation=<emu-id>" or ZocSetEmulation.

ZocSetHost 0|1
 

Please use CALL ZocSetSessionOption "Host=yes|no" instead.

ZocSetOption
 

Renamed to ZocSetSessionOption.

 

 
← Back to APPENDIX

 

Downloads
Orders
Contact
Support
Terms of Use
Privacy Policy
pixel