APPENDIX → ZOC-REXX Commands/Functions

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:

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:

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

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:

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

Beep n times.
 
Example:

Performs a clipboard function for one of the following subcommands:

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

Performs a function for one of the following subcommands:

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:

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:

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

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:

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

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:

Performs a dialog related function:

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

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:

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:

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:

This group of commands offers filename operations.

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:

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

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

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:

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:

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

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

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:

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

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:

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:

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

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:

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:

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

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

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

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:

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:

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:

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:

Plays a .WAV file.
 
Example:

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:

This group of commands allows access to the Windows registry.

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

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:

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:

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

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 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:

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:

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

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.

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

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:

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:

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:

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:

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:

Set new name for logging.
 
Example:

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

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

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:

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:

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:

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

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:

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:

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:

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

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.

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:

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

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:

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

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:

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"

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

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

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:

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:

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:

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:

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:

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:

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:

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:

Renamed to ZocConnectHostdirEntry.

Renamed to ZocAskPassword.

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

Replaced by ZocCommand("CLEARSCROLLBACK").

Replaced by ZocGetInfo("ONLINE").

Renamed to ZocClearScreen.

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

Renamed to ZocConnect.

Replaced by ZocTerminate.

Renamed to ZocShellExec.

Renamed to ZocAskFilename, ZocAskFilesnames.

Renamed to ZocAskFolderName.

Renamed to ZocWaitLine.

Renamed to ZocGetHostEntry.

Renamed to ZocGetSessionOption.

Renamed to ZocGlobalStore.

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

Renamed to ZocLoadSessionProfile.

Renamed to ZocLoadKeyboardProfile.

Renamed to ZocSetLogging.

Renamed to ZocSetLogfileName.

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

Renamed to ZocSaveSessionProfile.

Renamed to ZocGetScreen.

Replaced by ZocCommand("SENDBREAK").

Please use ZocGetSessionOption and ZocSend instead.

Renamed to ZocSetDeviceOpts.

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

Renamed to ZocSetHostEntry.

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

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

Renamed to ZocSetSessionOption.