Shamrock Software GmbH

ShamCom

Terminal Program for Windows

> Deutsch Version 4.05, 06 Mar 12
Functions
Mouse
Keyboard
Connection menu
Edit menu
Actions menu
Configuration menu
Script files

ShamCom is a freeware program from Shamrock Software for all 32-bit Windows variants. Shamrock does not offer hotline support for freeware and does not guarantee its functions for a specific operation environment. Distribution of the software in the Internet or on media requires a written and explicit approval from Shamrock. Selling the software for money is prohibited.

Functions

ShamCom is a terminal program for 32-bit Windows, allowing a dialogue with on-line systems over:

ShamCom supports the secure file transfer protocols Xmodem, Ymodem, Zmodem and all widespread terminal emulations:

Please note that the cable between a modem and the serial port of the PC needs all 9 wires. ShamCom uses a hardware handshake (DTR, DSR, DSR, CTS) and uses DCD for detecting a connection. A simple 3-wire cable (RXD, TXD, GND) will not work. The status of all RS232 control lines is displayed as blue symbols at the bottom of the terminal window.

Mouse

The left mouse button has the same functions as in other Windows applications. It selects menu items or Toolbar functions. By moving the mouse with its left key pressed you mark (select) a portion of text in the terminal window. The selected text may then be used for:

These menu items are also available in the pop-up menu which appears when you press the right mouse button. By double-clicking a word with the left mouse button you may either send its initial character or the whole word, with or without a carriage return behind it, depending on the configuration of terminal options. This lets you easily control a mailbox or other online service using the mouse. Double clicking on an unused terminal area sends a return character.
The right mouse button displays a pop-up menu which lets you start macros or create and edit macros using the macro configuration editor. (Macros are just pre-defined conditional sequences of keystrokes.)

Keyboard

The following keys have a special meaning in ShamCom:

F1 Help (context-sensitive)
Shift+F1 Help, click on the element in question
Alt+F1-F10  Starts a macro (script)
Alt+B Phone book configuration window
Alt+D Dial out using the phone book
Alt+H Hangup, disconnect
Alt+M Configuration window for macros
Alt+P Configuration window for modem parameters
Alt+S Configuration window for ports
Alt+T Configuration window for terminal options
Alt+X Quit program
Ctrl+PgUp Starts preconfigured upload protocol (send file)
Ctrl+PgDn Starts preconfigured download protocol (receive file)
Ctrl+Del Clear screen
Ctrl+Ins Copy selected text to the clipboard
Shift+Ins Send the contents of the clipboard

All other keys except the internal Window key combinations are sent to the connection on-line system.

Connection menu

In the connection menu, connections can be initiated or disconnected:

Dial: Displays the phone book for selecting an entry..
Disconnects: Ends the connection.
Quit: Ends the program after disconnecting (if applicable)..

Edit menu

The edit menu offers functions for the clipboard, for selected text, and for clearing the screen:

Copy copies the selected text to the clipboard so that it can be accessed by other applications. This function is also available in the context menu (right mouse button).

Send clipboard transmits the text from the clipboard. For instance, you can write a text in an editor, copy it to the clipbard, and then send it using this function. This function is also available in the context menu (right mouse button).

Send selected text transmits the text which has been selected using the left mouse button. This function is also available in the context menu (right mouse button).

Save selected text saves the text which has been selected using the left mouse button to a file. This function is also available in the context menu (right mouse button).

Clear screen clears the terminal window locally without sending anything.

Save screen makes a snapshot of the text in the terminal window and save it as a file. Colour information is discarded.

Actions menu

This menu contains functions which can be used when a connection is established.

Record saves all incoming data into a temporary file, including all control characters and emulation sequences.

Interrupt pauses a recording without clearing the contents of the temporary file. To continue later, select "interrupt" again or click on the symbol.

Stop recording asks for a file name and then renames the temporary recording file to this new name. If you select "Cancel" instead, the recording is deleted.

Play text file: The effect of this function depends on the status of a connection.
Not connected: Displays a previously recorded text file (nothing is sent). If the text file contains any escape sequences (e.g. ANSI colours), these will be interpreted properly. A pause is inserted before each new page, press any key (or the "Play" button) to continue.
Connected: The selected file will be sent via the serial port (or ISDN) just as it was entered from the keyboard. No error-correcting protocol is used. The file is sent including all control characters and emulation sequences.

Send macro: This allows you sending a sequence of keystrokes which has been pre-defined in the configuration dialogue. Macros can also be sent by using ALT function keys (ALT-F1 to ALT-F10), or using the pop-up menu which appears when you press the right mouse button.

Start download starts receiving a file using the transfer protocol which has been predefined in the terminal configuration menu (see protocol configuration). Before downloading a file please make sure that the mailbox or gateway system uses the same protocol, e.g. Zmodem.

Start upload starts sending a file using the transfer protocol which has been predefined in the terminal configuration menu as default. Before uploading a file please make sure that the mailbox or gateway system uses the same protocol, e.g. Zmodem.

Configuration menu

Some configuration parameters depend on the online service to be used, others are affected by the hardware of your PC and modem, and another group may be set quite individually, such as sounds or fonts. The parameters depending on the online service (and thus on a phone book entry) are: Port, terminal, macros, and modem. So you may use different modems at different ports for specific services. For the groups port, terminal, macros, dial you can set one of your configurations as the default (start configuration). All profiles are accessible using the phone book configuration.

Phone book: Create an entry for each on-line system you wish to connect to. Enter a phone number for ISDN and modem connections, or a host name or IP address for TCP/IP connections, optionally with a port number behind a colon (if no port is given, the telnet port 23 will be used). Select the configuration type (port, modem, terminal emulation) or create a new one in this window. The parameter "Connect delay" allows to configure the number of seconds the modem needs for negotiation; this allows a more exact calculation of connection fees.

Font: Use this dialogue to select the character font for the terminal screen. One font is used for terminal emulations using a DOS/OEM character set, and another for ANSI symbols. For DOS/OEM we recommend the use of SHAMCOM.OEM since it allows all common character sizes. The character size is always automatically adapted to the size of the terminal window. For ANSI emulations the Courier font (true type) is advisable since it is also a fixed font which allows tables to be displayed correctly.

Sounds: WAV files can be played in some situations, e.g. if an action is successful or fails.

Use the diskette symbol to select a wave file, or the speaker symbol to play that file.

Macros: This function allows entering of up to ten macro text strings. These can then be sent by:

Macros can have these special properties:
A pause of 1 second while sending key strokes are programmed by "~".
Control characters are programmed with "^" and one character, e.g. ^M for a carriage return. Examples:  Linefeed (LF) = ^J, Formfeed (FF) = ^L, Carriage Return (CR) = ^M, Escape (ESC) = ^[. If you want to send ^, enter ^^.

The first macro (ALT-F1) can automatically be started after dialling and thus may be used for an automatic log-in.

Terminal settings: This menu allows to configure how screen data should be interpreted.

Terminal emulation: VT100/ANSI is a standard emulation most commonly used. VT52 is a much older standard used with some host computers. TTY is not a true emulation since no escape sequences are interpreted by the terminal.

Character set: The character set has effects on special national characters and symbols, such as and so on. Some mailboxes are using the special graphical characters of the IBM/OEM character set.

Received CR: Normally you should leave this at the default CR->CR. If an online system only sends CR (instead of CR+LF) at the end of each line, set it to CR->CR,LF to avoid that all text output appears in one single line.

<RETURN>: Normally you should leave this at "Sends CR". When connecting a Unix host a different setting might be advisable.

Echo mode: The normal operation is "No echo" since most online services send an echo of each key press. If you see the menus of the remote system but not your own entries, try "local echo". The "V.24 echo" is used for a connection between two terminals but never for online services and must never be activated on both sides.

Terminal width: Most online systems require a line width of 80 characters. Some videotext services require 40 characters when using their VT100 emulation.

National characters: In some cases (for 7-bit communications, for example) it may be necessary to suppress any national 8-bit character codes. If you select "Expand", characters like , , will automatically be converted to ae, oe, ue.

Default protocol: Select the protocol the online service needs. Mailboxes often use Zmodem, but sometimes Xmodem or Xmodem-1K is required.

Mouse double-click: Select what effect a double click with the left mouse button should have, either for sending the first character of the word only, or the whole word, and optionally a CR if required. This makes it easy to use a mouse to select items from a mailbox menu.

Dial parameters: This dialogue sets the parameters for modem and ISDN connection. The option "start configuration" means that the settings are used when ShamCom is started. If there is one configuration only, it will be used as start configuration automatically.

Parameters for modems: This configures AT commands. Three steps are required.

Parameters for CAPI 2.0: If you are using an ISDN card at an extension of a PABX, it may be necessary to tick the option for using 0 as external access digit.

Dial control: It is possible to configure how often the dialling should be repeated if the connect fails, and how long the pause should be between the retries. Most modems have a register for a similar function (e.g. ATS7=60); it should be set to a higher value so that the software keeps control.

Port: This sets the required port type.

TCP/IP: Allows using ShamCom as a Telnet application.

CAPI 2.0: Allows using an ISDN card with its CAPI2032.DLL driver which came with the card. When selecting CAPI 2.0 as a port type, you may use either X.75, HDLC or V.110 as ISDN protocol. Most mailboxes use X.75 which is the default. V.110 uses bit-stuffing to emulate slower modems and thus requires the selection of the speed wanted. - The MSN (multiple subscriber number) is your own phone number (typically without the area code). If you connect the ISDN adapter to a internal PBX bus, you must enter the local branch number as MSN, otherwise often even outgoing calls are impossible.

COMx: Uses a serial port of your PC. In this case, the following additional options are available:
Baud rate: Should be higher than the highest possible modem speed, e.g. 115200 bps for a 56k modem.
Stop bits: Default is 1, this should work in most cases.
Data bits: Default is 8, the correct value may depend on the on-line system.
Parity: Default is "none" which is almost always correct for 8 data bits.
Ignore CTS: Allows to send even if the CTS line is inactive or not connected (not recommended).

Transfer protocols offers some options for transferring files.

Minimize window during transfer minimizes ShamCom to an icon, only the transfer window is visible.

Upload directory sets the folder from where files are sent with X/Y/Zmodem. Download directory sets the folder where received files are saved. If these fields are empty, the current folder will be used, typically the folder where ShamCom resides.

ZModem options: Allows to set the autostart option for Zmodem when the other side requests a file transfer, to allow the continuation of transfers after the connection was lost, and to set the transmit window, i.e. how many bytes should be sent blindly without waiting for an acknowledgement (4 K is a good value for most cases).

Script files

ShamCom script files (extension .SSR) can be used for automatic procedures like dialling, log-in, file transfers, and log-out.

Variables in script files

Script files may contain variables which can be set in the file SHAMCOM.INI. To do that, open this file with an editor, create a section [Scriptvariablen] and enter the values you need. Sample:
...
[Scriptvariablen]
Name=EINSTEIN
Password=ALBERT
...
Variables can be used as arguments in script commands. A dollar symbol must be prepended to their names. Example:
DIAL MAILBOX
SEND $Name
SEND "^m"
SEND $Password
SEND "^m"

The string ^m sends a carriage return character after the name or password. Please also have a look at the sample script MAILPOLL.SSR which shows how the program can wait for certain strings before it sends the corresponding answers.

Script commands

Some rules: Comments can be written in lines starting with REM, they must not be appended to commands. Labels used for conditional or unconditional jumps begin with a colon at the start of a line but this colon is not part of their name. Upper or lower case is ignored. Strings containing spaces must be written in quotation marks; control characters can be written as ^ followed by one character, e.g. ^M for Return, ^J for Linefeed, or ^[ for Escape. The following commands can be used:

CHOICE "question" label Ask user for Yes/No, jump to label if No
DELETE "path\file" Delete a file
DIAL "name" [label] Dial phone book entry "name", jump to label if this fails
EXECUTE "prog" Execute a program, optional parameters behind a space
EXIT End ShamCom (after disconnecting, if necessary)
GOTO label Unconditional jump to a label
HANGUP Disconnect immediately
IFEXIST "path\file" label If the given file exists, jump to label
LOGSTART Start a recording
LOGSTOP "path\file" Stop recording and save/append to file
REM remark text Comment line, ignored by the script interpreter
RECEIVE_BIN "file" [label] Start file reception, jump to label if error
RENAME path\old path\new   Rename a file with explicit path
RENAME_DOWN old new Rename a file in the download folder
RENAME_UP old new Rename a file in the upload folder
MESSAGE "Text" Display a text in a standard message box
SEND "Text" Send a character string
SEND_ASCII "file" Send a text file (no protocol)
SEND_BIN "file" Send a file using X/Y/Zmodem
WAIT timeout [text[ label]] Wait for a character string, goto label if timeout

Here are some more comments on commands.

IFEXIST: This file allows a conditional jump if a given file exists. A path should be given. Example:
...
IFEXIST C:\MYDIR\UPLOAD.ARJ UPLOAD
GOTO END
....
:UPLOAD
SEND_BIN C:\MYDIR\UPLOAD.ARJ
:END
HANGUP


RECEIVE_BIN: For receiving files, the protocol can be given after an additional underscore: RECEIVE_BIN_X, RECEIVE_BIN_K, RECEIVE_BIN_Y, RECEIVE_BIN_Z. Adding a filename is only useful for Xmodem since the other protocols transfer the name together with the file content. If an error occurs, the script jumps to the label if one is given, otherwise the script ends.

SEND_BIN: Similar to the reception, a protocol can be given explicitely after an additional underscore: SEND_BIN_X, SEND_BIN_K, SEND_BIN_Y, SEND_BIN_Z. If an error occurs, the script jumps to the label if one is given, otherwise the script ends.

WAIT: Allows synchronization with the on-line system. Without a text it simply waits for the given number of seconds. If a text is given, it waits until this string is received or the timeout occurs. If a label is given after the text, the script will continue there after a timeout; if not, the script will stop if a timeout occurs. While waiting for a string, Escape sequences as used for terminal emulation are ignored. Examples:

WAIT 10 Wait 10 seconds and then continue
WAIT 10 Hello If Hello is not received in 10 s, disconnect and stop script
WAIT 10 Hello ERR    Jump to ERR if Hello is not received within 10 seconds

A sample script

The following script dials the phone book entry "shamrock", enters username and password, retrieves a file "demo.dat" and then hangs up:

REM Dial phone book entry
DIAL shamrock err
REM Wait for prompt (question mark)
WAIT 10 "?" err
SEND "name username"
WAIT 5 "Password:" err
SEND secret
REM Now retrieve a message
LOGSTART
SEND hello^m
WAIT 10 "?" err
LOGSTOP "c:\log.txt"
REM Retrieve file with default protocol
SEND "get demo.dat"
WAIT 10 "Start" fileerr
RECEIVE_BIN
:FILEERR
REM Disconnect friendly
SEND quit
GOTO end
:ERR
HANGUP
EXIT
:END

Your script as a link

It is possible to create a Windows link e.g. on the desktop to a ShamCom script file. Such a link launches ShamCom and automatically starts the execution of the given script.

To create a link, simply drag the script file from the Windows Explorer to the place where it should be, e.g. to the desktop, or create the link manually. The link will use the ShamCom symbol initially, but you can also change the icon using the right-click properties menu.


Shamrock Software GmbH