Sensorsoft

SCOM Client Tool Manual

March 10, 2016



 
 

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;

It is also necessary to ensure that the expected modem response strings (i.e. CONNECT, NO DIALTONE etc..) are entered correctly for modem being used.

To send alphanumeric pages, you need to know;

To send numeric pages you need to know; In numeric paging mode the pound sign (#) is often used to indicate the end of your message. For scom version 4.3 and greater, the user must add this to the message string. The asterisk (*) can be used with some paging services as a dash sign or hyphen (-) to separate a series of digits. Not all services support this. If you include a double quote (") at the beginning of your message, many modems will convert letters to their numeric equivalent - as found on your telephone keypad. Refer to your modem's user guide for details of this feature.

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-2016 Sensorsoft Corporation, All rights reserved.
Sensorsoft, Soft Thermometer and SCOM Serial Communications Tool are trademarks of Sensorsoft Corporation.