NAME
scom - serial communications tool (client)
SYNTAX
scom [-options] serialport | host-name:port [transmit string]
DESCRIPTION
scom is a general purpose serial communications tool that is designed to
send a command string and or file to a serial device, wait for a response,
and display the response on the standard output device. It allows administrators
and programmers easy access to serial devices without writing C programs and
without the need to understand UNIX or LINUX termio/stty parameters.
scom can be deployed directly from command line or through various scripting languages. It checks for an existing lock file, if not present, creates its own so that it can operate in harmony with other programs like uucp, cu, tip, scomd and other instances of scom.
scom provides the flexibility to communicate with a large variety of serial
devices, by allowing command options that specify the communication parameters,
character handling and modes to be used with each device. It also provides
special support for modems, pagers, sensors and network cameras. scom and
scomd also provide client-server support
to allow access and sharing of remote serial and USB devices over TCP/IP networks
and the Internet.
OPTIONS
scom accepts the following options:
-d [fpval] Read delay time-out
This option is followed by a floating point value (fpval) that represents
the time in seconds to wait for a response from the serial device, before
timing out and exiting. scom will wait for each character received from the
device port. If the character is available, the read will be satisfied immediately.
If there are no characters received, scom will wait until 'read delay' expires,
before exiting. All characters received to this point will be output to stdout.
The range for fpval is 0 - 99999999999999999.9 seconds or 17 digits before the decimal point and one recognized digit after the decimal point. If this option is not specified the default is 1 second.
If fpval is 0, scom will wait indefinitely. This feature is useful when it is necessary to keep the device port open, waiting for the serial device to emit a message. In combination with -S or -n option explained below, the port can remain open till a special character or a set number of lines are received.
-f [path-filename] Send file
to port
scom opens the path-filename and sends each byte out the port. The file may
be a text or binary.
When a transmit string is supplied, the transmit string is sent first, then the contents of the file. This allows a setup or configuration string to prepare the serial device before the file is sent, as might be required in some applications.
-c [XON | RTS | NONE] Flow
control
The XON option-argument is for software flow control, also known as XON/XOFF.
The RTS option-argument is for RTS/CTS hardware flow control. The NONE option-argument
simply turns off all flow control. The default is XON.
-n [num | ALL] Number of lines
to read
Read only num lines from the device, then exit, regardless of the
number of lines returned by the device or the read delay that is specified.
A line is defined as all characters up to the receive line terminator.
See -r option description below.
Range of num is 1 - 4.294 billion. Arguments can be in decimal, octal or hexadecimal. The default is ALL lines. Lines left unread from the device will be flushed and subsequently lost, when scom exits.
-r [###] Receive line terminator
to expect
scom determines the end of a received line by the value ###. Range
is 0 - 255 decimal. Arguments can also be in hexadecimal or octal. If not
specified, the default is line feed (i.e. decimal value 10).
-s [bps] Bit rate or Speed
Valid speeds or bit rates are 50, 75, 110, 134, 150, 200, 300, 600, 1200,
1800, 2400, 4800, 9600, 19200 and 38400 bits per second (bps).
The SOLARIS version of scom supports the following higher rates; 57600, 76800, 115200, 153600, 230400, 307200 and 460800 bps. The 4.4 BSD version of scom also supports the following additional rates; 7200, 14400, 28800, 57600, 76800 and 115200 bps. The Linux version of scom also supports the following additional rates; 57600, 76800 and 115200 bps. The default is 9600.
-e, -o Parity and data byte
size
The -e option sets parity to even and data bits to 7. The -o option sets
parity to odd and data bits to 7. The default, if these options are not used,
is 8 data bits and no parity.
-z [#] Number of stop bits
Choose from 1 or 2 stop bits. The default is 1.
-t [### | crlf] Transmit terminator
The specified character ### will be transmitted to the serial device
with or without a transmit string. If the transmit string is supplied, then
the terminator will be appended. When no transmit terminator is needed, omit
this option. Range is 0 - 255 decimal. Arguments can also be in hexadecimal
or octal. To terminate with both carriage return and line feed, use crlf
as the argument.
-m Monitor mode
Displays control characters as mnemonic labels. This is often useful as an
inexpensive substitute for a protocol analyzer. For example a null character
is displayed as <NUL> instead of going unnoticed. All control characters
in the ASCII table are supported. Regular or printable ASCII characters are
displayed as normal. Binary bytes, that are neither control characters nor
printable characters, are displayed as angle bracketed hexadecimal numbers
as explained in probe mode below. Use this mode when you want to observe
ASCII control characters and text from a serial device.
Using this mode or the probe mode, it is possible to troubleshoot serial links using an RS232 breakout box. Simply connect the breakout box somewhere between the two link end points. Then connect the receive RX lead from a second serial port to either the TX or RX line on the link. This type of eavesdropping can allow for monitoring and troubleshooting of protocol problems. scom therefore replaces an expensive protocol analyzer with an easy to use on site tool. If two additional serial ports are available, then both RX and TX traffic can be monitored with two instances of scom.
-p Probe mode
Similar to the monitor mode, except all received bytes are displayed as angle
bracket hexadecimal numbers ( <00h> <FFh> ). Useful for viewing
the contents of binary streams being received from a serial device.
-S [###] Exit on special received
character
When this option is provided, scom exits when the special ### character
is received. The range of this character is 0 - 255 decimal. The argument
can also be expressed in hexadecimal or octal.
-v Display version, target CPU and OS
This option displays the following information and exits; software version, target CPU class
such as x86 (32 bit) or x64 (64 bit) and operating system type.
-D Do not drop DTR on exit
(UnixWare, SOLARIS and HP-UX ONLY)
This option is useful when working with modems and you do not want to drop
a modem connection between shell script lines. It can also be used with port
powered RS232 peripherals where the DTR is used to power the device. When
this option is not selected, by default DTR will be dropped on exit.
-R Do not drop RTS on exit
(UnixWare, SOLARIS and HP-UX ONLY)
This can be used with port powered RS232 peripherals where the RTS or RTS/DTR
is used to power the device. When this option is not selected, by default
RTS will be dropped on exit.
-Q [setupfile] Sensorsoft
Device Mode
This option mode allows scom to communicate with Sensorsoft devices with
protocol version 2.0 and 3.0. It requires the path and name of a setup file that
contains keywords that specify parameters used when communicating with the
Sensorsoft device. The setup file is an ASCII file and are model-specific.
These files can be tailored by the user using a text editor and or copied
and renamed to suit the application. If you use this option mode with
a none argument for the setupfile it will use default settings to communicate with the Sensorsoft device.
scom supports CRC error detection and command re-transmission to overcome communication errors over long or noisy communication links. It also handles the plug and go acrobatics to make the Sensorsoft Device easy to work with.
The -L -N options are the only other options that can be used with
the -Q option-mode. They must precede -Q to be recognized.
-P [setupfile] [message_string]
SMS-TAP/DTMF Paging Mode
This option mode allows scom to use a standard modem to communicate with
alphanumeric paging terminals that use the SMS-TAP protocol (Telocator Alpha-Paging
Protocol). scom also works with numeric paging systems that use a voice announcement.
To use this mode you must specify a setup file and a message to be sent to the pager. The provided setup file contains keywords that specify parameters used when communicating with the paging providers terminal. The paging message can be provided as a string or shell variable enclosed in double quotes. scom will allow a message length up to 210 characters. Some providers may not use these many characters and may truncate the message after the page is accepted. Ask your provider how many characters they accept.
The setup file also specifies a modem setup file with modem specific strings. Any of these files can be copied and edited to suit the application. Standard setup files are supplied for numeric or alphanumeric paging. Three modem setup files are supplied, one for recent Hayes compatible modems, another for older Hayes compatible (300-1200) modems and the last for US Robotics Sportster modems. Modems other than these could be supported if the user can create their own modem setup file. Important modem settings for this are;
To send alphanumeric pages, you need to know;
Most alphanumeric paging providers work at 300 or 1200 bps. A debug feature
can be invoked by a setting in the setup file, that allows you to monitor
progress between your paging modem and host computer. The -D -R -L -N options
are the only other options that can be used with the -P option-mode. They
must precede -P to be recognized.
-E [setupfile] [subject_string] [message]
Email SMTP Client Mode
This option mode allows scom to implement a TCP client that can send email
to an SMTP server. The hostname:port specifies the SMTP server that accepts
connections. The port (number) is usually 25 for the SMTP protocol.
To use this mode you must specify a setupfile, subject string and message. The setupfile is an text file that contains various keywords that are used to control the communication between the SMTP client and server. The subject string can be up to 100 characters long. The message can be a string (up to 255 characters long) containing the email message or a path-filename where the message is stored.
The setupfile can be used to enable SMTP authentication with the SMTPauth keyword.
If desired, one may also attach a file of any given format to the email using the -A option. The -A (attachment) option and -R (recipient) option are the only options that can be used with this mode and musr precede -E switch.
-A [attachmentfile] Attach File
to Email
This option only has an effect when used in conjunction with the -E mode.
This option must precede the -E switch or it will be disregarded.
To use this option you must specify a valid path-filename for transmission. The file can be of any format, and will be attached to the outgoing email in base64 encoding.
-R Specify email recipients
on command line (LINUX ONLY)
This option must precede -E switch or it will be disregarded.
-C [setupfile] Network Camera Mode
This option mode allows scom to gather an image from an Axis or similar Network Camera
through its HTTP protocol. This file will be in JPEG file format, that is
then readable by most image viewers and manipulation software.
This mode requires the path and name of a setup file that contains keywords that specify parameters used when communicating with the camera. The provided setup file is an ASCII file and is configured to work with the Axis Network Cameras. This file can be tailored by the user using a text editor and or copied and renamed to suit the application. If you use this option mode with a none argument for setupfile it will use default settings to communicate with the Axis camera.
A debug feature can be invoked by a setting in the setup file to allow monitoring of communication between the camera and host computer.
Support for the Olympus digital cameras has been removed as of SCOM Version 6.30.
-X [pluginfile] [setupfile] Plug-in Reader Mode
This mode is used in the Sensorsoft Alert appliance to work with third party devices. The generation of
plugin files is something done only by Sensorsoft technicians on behalf of customers.
LOCK FILES
Lock files are used by programs like cu, uucp, scom and scomd to signal other
processes that a serial port is in use. scom checks for an existing lock
file, if not present, it creates its own. The format for this lock file is
identical to that used by cu and uucp.
See FILES heading below for the directory where lock files are created. In some instances it may be possible for a lock file to get left behind even though no processes are using the serial port. This can happen if the process ends abnormally without a chance to remove its lock file. In this case it would be necessary to remove the lock file manually.
-L [path | filename] Specify custom lock file directory or filename
Solaris and UnixWare:
Allows user to specify an alternate lock filename. Supply only the filename.
The directory name is included by scom. A maximum of 80 characters is allowed
for the entire file specification. When this option is not specified, scom
uses a default algorithm for generating the file name.
ALL OTHER UNIX's
Allows user to specify an alternate lock file directory path. The file name
is generated by scom. A maximum of 80 characters is allowed for the entire
file specification. When this option is not specified, scom uses the default
directory path for the lock file.
-N Use no lock file
Do not look for or create a lock file. This can be used, if the user does
not have permissions to the lock file directory and is testing in a non-production
environment.
OPERANDS
serialport | host-name:port
This is the device name where your serial peripheral is connected. It may
be a local physical device such as a serial/USB port or a remote device connected to a device/terminal server
or a host running a TCP/IP terminal server program like Sensorsoft scomd or RWMS.
A physical device name may be entered as ttya or with the complete path name /dev/ttya. Some SPARC machines may require an alternate device name to work correctly (/dev/cua/a vs. /dev/term/a or /dev/ttya). The difference is in the minor device number for each of these devices.
UnixWare user's should note that accessing any of the available COM ports requires the use of device names ending with the "t" character (i.e. term/00t). Other device names (i.e. term/00 term/00h term/00s) require that the DCD input of the port, be asserted (+12V) before the port can be used.
You may specify a remote port, if the serial device is connected to remote computer or terminal server on a TCP/IP network or the Internet. The remote port may be entered as such:
ip-address:port
host-name@port
domain-name:port
The ip-address, host-name or domain-name must be in your local /etc/hosts
file. The port is a four digit number, determined or defined by the
remote host or terminal server where the port is physically located. If the
remote system is a computer, then usually that information can be contained
in a file called /etc/services. If a terminal server, then refer to
the technical manual for that equipment.
transmit string
The transmit string is optional and must be the last argument on the scom
command line. This string gets sent to the serial device. Enclose the string
in quotes, when special shell characters are used. The special shell characters
are not interpreted. For example \n is not converted to a linefeed
character. Maximum string length is 256 characters. When a transmit terminator
is required at the end of transmit string use the -t option. Please
note that when some scom option modes are specified (Q,P,C,E), a transmit
string is not used.
EXIT STATUS
0 indicates success
1 indicates a general failure
2 indicates a device time-out problem
3 indicates a TCP or modem connection problem
4 indicates an unsupported device problem
5 indicates a termination signal was received
6 indicates a device interrupt was received
FILES
/scom/scom executable scom client program
/scom/scomd executable scom server program
/scom/setupfiles/*.ini setup files for supported peripherals
/scom/scripts/*.sh application shell scripts
/var/spool/locks/* lock files for Sun Solaris 2.X, 7 and 8
/var/spool/locks/* lock files for HP-UX
/var/spool/lock/* lock files for 4.4 FreeBSD
/var/lock/* lock files for Linux
/usr/spool/uucp/* lock files for SCO OpenServer UNIX 4.2 and 5.X
/var/spool/locks/* lock files for SCO UnixWare 2.X and 7.X
/etc/hosts names and ip addresses of remote servers or hosts
/etc/services names and port numbers of services available on a TCP/IP
server
/scom/html/*.html HTML manual pages
SEE ALSO
scom_app(HTML) , scomd (HTML)
NOTES
scom may be called multiple times from within any script to create communication
sessions with many types of serial devices, using variables to set a number
of different communication parameters. Its output can be redirected to files
or variables.
Under Solaris 2.4 and possibly some earlier releases, an error message is issued, by the operating system, complaining about a problem with library ld.so.1 and the usleep system call. Refer to Sunsolve support for a patch to solve this problem.
scom will be terminated with a graceful exit, when a kill command (kill <pid>) is issued. Using kill -9 <pid> will not result in a graceful exit.
Sensorsoft devices may not power-up correctly on the serial ports of a
Sun workstation running Sun Solaris 8. This is due to a driver bug that prevents a system call from asserting RTS and DTR. To correct
this problem, install Sun driver patch 109793-22 (available from sunsolve.sun.com).
Copyright (C) 1995-2019 Sensorsoft Corporation, All rights
reserved.
Sensorsoft, Soft Thermometer and SCOM Serial Communications
Tool are trademarks of Sensorsoft Corporation.