dialer command

The dialer BASIC program controls the dialer subsystem, which allows transferring data to remote systems over the phone in a batch mode.

For Windows: Not Supported

Menu Keys

Without any argument, a menu displays. Below is a list of valid keys that can be used. When indicated, arrow keys can also be used.

Key Function
ENTER Executes the highlighted option.
Q or ESC Exits the menu and returns to previous menu.
X Exits the menu and returns to TCL.
n Indicates the number selected from 0 to 9.
Note: 0 is option 10.
letter Indicates the next menu letter option starting with the specified column.
Note: Select any letter except X or Q.
CTRL+N Moves cursor down. The down arrow can also be used.
CTRL+B Moves cursor up. The up arrow can also be used.
CTRL+K Moves cursor right to next column. The right arrow can also be used.
CTRL+J Moves cursor left to the previous column. The left arrow can also be used.
CTRL+X Cancels, in an input field.

Menu Displays

The screen is divided into two sections: an upper section for menu display, and a lower section for messages such as the help screen and user prompts.


The first time the system is installed, the user is required to enter a local system name and the time zone the system is located into.

  1. Enter any name, up to eight characters, and press ENTER.

    Note: This name is also displayed by the TCL command node.
    Setup Local Host Name
         Local host name:
         Confirm (y/n/q):
  2. Select the appropriate time zone, and then press ENTER.

    Setup Time Zone
         1 UK
         2 Azores
         Confirm (y/n/q):
  3. Set up the remote sites and serial devices using the setup menu.

Main Menu

The main menu operation is used for normal operations. These options are:

1 Queue status Displays the status of the queues to all systems (for example, the system name, the number of queued jobs, and the description of the next job) or of a specific system (that is, a detailed description of each job).
2 Device status Displays the last messages logged by a specified I/O daemon. The messages display with the most recent first.
3 Start dialers Starts the dialer I/O daemons. This command can also be executed from TCL to be used in macros or Procs. One I/O daemon is started for each defined device.
4 Stop dialers Stops the dialers I/O daemons. This command can also be executed from TCL to be used in macros or Procs.
Note: When a I/O daemon is in the middle of a call, it does not respond to a stop request.
5 Setup Displays the setup menu.
6 Check conflicts Displays any pending conflicts between changes made to the local database and changes received from remote systems.
7 List permanent log A permanent log that contains all messages logged by any I/O daemon. This log is not cleared automatically. The messages display with the most recent first. Use the functions keys displayed in the title to navigate through the log.
Note: When a colon is entered, a command menu displays, which allows searching for special text and starts the display at a specified time and date.
8 Messages Displays the messages sent by other systems, using the command msg of the dialer TCL command, or by the dialer subsystem itself. The list of all the pending messages, sorted by user and by time/date displays, with the destination user and the subject.
Note: The help section displays more information about each message. When selected, the first few lines of the messages display and the user can do any one of these options:
  • P)rint the message to the currently assigned form queue.

  • D)elete message.

  • Q)uit to leave the message.

The dialer subsystem generates Notice mail messages, in case of serious problems. The messages can also be read from TCL with the mail command.

Setup Menu

The setup menu allows defining the remote systems and devices used by the dialer subsystem and performing accessory functions, such as testing the communication, purging the queue, and so on.

1 Local Host name Defines the name of the local system. The local system name must also be declared in all the other systems that can accept messages from this local system. This mechanism is required for security reason, to ensure that messages are properly authenticated.
2 Remote system Defines a remote system. Remote systems must be defined so that they can be called and to be able to accept messages from them. A submenu displays the list of the currently defined systems, or new system to create a new entry. These elements must be provided:
  system name Any string of up to eight characters. If the system has been defined already, changing the name creates another system (it does not rename the specified system). This can be used to duplicate a system definition.
  calling schedule Defines each day of the week, if and when the system can be called. The system administrator should choose a window time to get the cheapest rates, when applicable, and, when many systems are calling one central site, try to spread the calling window to reduce the risk of collisions. Within an allowed schedule, the call is placed within a few minutes of the specified time. In case of problems, the system retries no more than three times to establish the communication. The syntax for the schedule is:
  never Does not call the system that day. If all days are set to never, the system will never be called. However, data can be transmitted to this system, but only when it calls in.


empty string
Calls, at any time, as soon as the data is queued for transmission. The actual transmission time is called within the next minute. This should be reserved to leased lines only, since it would be inefficient to dial for each update.
  hhmm-hhmm First four digits specify the starting time of the calling window, in 24-hour format. The second set specifies the ending time. For example, '2000-0100' means from 8:00 PM to 1:00 AM; '0100-0530' means from 1:00 AM to 5:30 AM.
  *hhmm Defines a periodic calling schedule. A call can be placed every hh:mm. For example, '*0100' means that a call will take place at 1:00 AM, 2:00 AM, and so on throughout the whole day.
Note: It is not recommended to use too short of a time period. One hour is the minimum, except in some very exceptional cases.
  phone number Up to four phone numbers can be specified. In case of failure, they are tried in the given order. The syntax of the phone number must be compatible with the modem and should include any prefix, wait, extension, and so on.
  device Specifies which devices can be used to establish communication. If none is specified, the system selects the first available device. The device number has two forms:
  Snnn A dedicated serial device number nnn. The system assumes it has exclusive access to this device.
  nnn Uses the serial device normally associated to the D3 process number nnn. When the serial device is needed, the D3 process is unlinked to take control of the device, and linked back on to it when the transfer is complete.
  permissions Defines the operations the specified system can or cannot do when calling in. Enter a y or n in each field:
  call Defines if the system is allowed to call in at all. If set to n, the local host hangs up if receiving a call from this remote site.
  exec Defines whether the remote system is allowed to execute commands on the system. Commands are run by the I/O daemon itself and should be short.
  upd Defines whether the remote system is allowed to update the local system’s database.
  adm Defines whether the remote system is allowed to perform remote maintenance operations.
3 devices Defines a serial device. A submenu displays the list of currently defined devices or new device to create a new entry. These elements must be provided:
  device ID Device name. For a dedicated device, the ID must be prefixed by an s. For a shared device, enter the D3 process number, which is linked to the device to be used. Do not use device 0. If shared, also specify the take over time (see take over time below).
  state Enables or disables. If disabled, no I/O daemon is started and the device cannot be used.
  type A direct device or modem. A direct device is assumed to be constantly connected to the target system through a leased line, for example. Only one system can be reached through this device. Make sure the system definition is consistent with this setting.
  dialer name Defines the name of the dialer if the device is a modem type. By default, the dialer is Hayes. This name is the item-ID of the BASIC subroutine in the dm,dialers file, which handles the dialog with the modem.
  mode Defines whether the device is input only (that is, it can only receive calls), output only (that is, it does not accept any incoming calls), or both.
  settings Defines the serial port setting.
Note: The device must support 8-bit characters.
  take over time Defines the time window during which the dialer takes over the serial device shared with a regular D3 process (that is, a device which does not start with an s). The syntax of the time is identical to the one described for the calling schedule on a remote system. If a time interval (for example, '2200-0700') is specified, the device keeps the device attached for the specified duration. This should be the normal setting, for example to specify a time out of normal opening hours when nobody would dial on the system to log on to D3. If a periodic schedule (for example, '*0030') is specified, the device attaches to the device for a period, then detaches for the same period, then reattaches for a new period, and so on. Specifying any or leaving this field blank, effectively makes it dedicated since the I/O daemon attaches permanently to the device.
Changing the take over time schedule requires stopping and restarting the dialer subsystem for the change to become effective.
  user reset Optional command string to send to the modem to reset it to a user defined state when the dialer daemon either terminates or relinquishes the shared device. A carriage return is appended to the string. If left empty, a modem dependent string is used ("atz" in case of the Hayes dialer). If this command fails (for example, does not respond OK), a factory reset is done.
4 Delete remote system Deletes the definition of a remote system.
5 Delete device Deletes the definition of a device.
6 Test access to system Attempts to establish a call to the specified system. This option can be used to test a new installation, or to make sure a remote host is reachable. This option dials out, establishes the communication and sends 10 test messages to the remote system which must be powered up and have an appropriate I/O daemon started. The I/O daemons must not be started on the local system else no device available message is issued.
7 Set local time zone Defines the time zone the local system is in.
8 Set system map Defines where the updates to a system are to be sent. This option displays a sorted list of the accounts on the system (up to 256 accounts can be displayed).
  • Select the account to be set up, or ALL ACCOUNTS.
    Note: The dm account is never selected.
  • Select to update either All files, Select files, or a Select list of files. If the Select Files option is selected, the list of files in the account displays.

  • Press the space bar to select the files to be changed, and then press ENTER when all the files have been selected. An asterisk displays in front of the selected files. The list is saved in a list, which can be used as input to the Select list of files option.

  • The user can elect to post updates to both the data levels and the dictionary, to the dictionary only, or to the data level only. An option remove callx allows suppressing the posting of the updates on the entire selected account.

  • Enter the list or remote system where the data is to be sent and the optional account name on the remote system. If an account name is not specified, the remote account is assumed to be the same as the local account name. Up to four remote systems can be entered. An remote system cannot be specified twice in the list.

  • Confirmation is required. This option updates the D-pointers of the dictionaries and/or data levels of the selected accounts and files to insert or remove, as appropriate, the callx correlative to perform the update posting.

  • This menu option can be used as long as there are less than 6 target system names. Otherwise, it is more convenient to use the TCL form.

9 Purge queued updates Purges the queue of data to be transmitted to either all systems or a select system.
10 Clear permanent log Clears selected messages or all messages from the permanent log. A submenu allows selecting messages older than one week, one month, or all messages.
11 Connect to device Connects directly to the device to send commands, like resetting the modem. The device must not be attached.
Note: Only certain types of commands can be sent to the device (like a reset). Dialing to a system may be difficult.
12 Submit remote command Connects to a remote system and executes a command on it. The local site must have been declared with sysadmin privilege in the remote system. This option prompts for the remote system to dial on and a command menu: Submit TCL command to execute any TCL command on the remote; Terminate remote to force the I/O daemon on the remote system to terminate. The submit command prompts for a command, dials to the remote system, submits the command and disconnects without waiting for the end of the command. The terminate option should be used only if the device on the remote system is a shared device. This allows a user to free the device to be able to do a remote log on.

Resolving Conflicts

This option from the main menu examines the conflict file and shows any conflict still not resolved. The first menu selects all the conflicts and shows the account, file and item-ID. The help message in the message section gives more information about the conflict. The Check conflict option requires that the system administrator has good knowledge of the database structure. Only raw data is presented. A more advanced conflict resolution requires understanding the database organization and cannot be accomplished by a general purpose tool. Conflict Data Format details the structure of the data stored in case of a conflict so that an application dependent tool can be developed.

When a conflict is selected, this information displays:

From:                     sys Date: 02/14/03-09:18 Cause: Conflict change
Acc:                      dev File: tmp           Item: x
sys!dev,tmp, x            LOCAL!dev,tmp, x
----------------          -------------------------------------------------

In this example, sys is the name of the remote system the conflicting changes is coming from, the time and date are the local time and date, the cause is a short description of the conflict, dev is the local account, tmp the file and x the item. The left side of the display shows the remote file information and the right side the local one.

The screen is then divided into two columns showing the attributes that are different on the local system before and after the changes from the remote system have been applied.

The user is then prompted to take an action:

Use data from system 'xxx '         ..............................   1
Use local data and update remote    ..............................   2
Quit (leave conflict unresolved)    ..............................   Q
Cancel conflict. Leave data alone   ..............................   C
Show next attributes in item        ..............................   N
Show top of item                    ..............................   T


1 Uses the data received from the remote system to overwrite the local data.
2 Keeps the local data and copy the local data to the remote to force it to use the local copy. Note that the copy is just enqueued. The system waits until the next calling time to actually copy the data. More changes can be made to the same item before the copy is performed. The item that is transmitted at the time the transfer takes place, not the item the way it is at the conflict resolution time.
Q Quit leaves the conflict unresolved.
C Cancels the conflict. The data is left as is on each system, creating inconsistencies on the databases. This option should be used with extreme caution.
N Shows the next attributes.
T Returns to the top of the item.

Conflict Data Format

The conflicting data is stored in the file dialer.log,conflict. Each conflict is represented by three items:

Conflict definition item Item-ID is a unique time date stamp. It contains these attributes (defined in dm,bp,includes dialer.inc):
CFLCT$DATE Local conflict date.
CFLCT$TIME Local conflict time.
CFLCT$ACCOUNT Account on local system.
CFLCT$DICT dict if it is a dictionary, or two single quotation marks.
CFLCT$FILE File name
  CFLCT$SYSTEM Remote system name.
CFLCT$CODE Reason for the conflict.
CFLCT$NOFILE Missing file.
CFLCT$BADDIFF Bad difference string.
>0 Line number in the difference string (see difference string).
CFLCT$REMACC Account on remote (source) system.
Old item Item-ID is the concatenation of *OLD* and of the conflict ID it depends on. This item contains the item coming from the local system at the time the conflict occurred.
New item Item-ID is the concatenation of *NEW* and of the conflict ID it depends on. This item is not really the new item: it contains the difference string describing the changes applied to the remote host. The attribute CFLCT$CODE contains the attribute number in this new item on which the conflict was detected.

The difference string is composed of a series of commands, which describes the changes to be applied. Each command is composed of one or more attributes, and start by a one letter code. Valid commands are:

ln Original number of attributes in the item n.
cn{]m} Changes attribute command starting at attribute n. Changes m (default 1) attributes. This command is followed by m pairs of attributes oldvalue/newvalue.
vn{]m} Changes value command starting at attribute n. Change m (default 1) attributes. This command is followed by m triplets of MultiValue attributes built as follows:
valnum] valnum]...
oldval] oldval]
newval] newval]...
valnum Value number that is modified. oldval is the old value. newval is the new value. If the number of the old values is less than the number of new values, it indicates that the values were added. If the number of old values is greater than the number of new values, it indicates that the values were removed. The value change command would be:
an{]m} Adds attribute command starting at attribute n. Changes m (default 1) attributes. This command is followed by m attributes, which contains the added attributes. If the attribute n is not empty, the new attributes are inserted before it.
dn{]m} Deletes the attribute command starting (including) at attribute n. Delete m (default 1) attributes.

Merging the changes described by a difference string into an item is accomplished by the FlashBASIC program in dm,bp,includes merge.sub. For example:

* Get the old item
read m$olditem from conflict,’*OLD*’:ID
* Get the difference string
read m$diff from conflict,’*NEW*’:ID
* Merge the changes in
* m$nocheck = 1 ;* Set to force merging
include dm,bp,includes merge.sub
if m$code=0 then
* OK
end else
* Error
* Changes cannot be merged because of a
* conflict. (use m$nocheck=1 to force merge)
Note: The include is not a subroutine. It is a fragment of code that can be included inline. Other include statements of interest are:
  • dm,bp,includes sdiff2.sub—combines two difference strings into one, cumulating the changes.

Creating Serial Devices on D3

For UNIX: The possibility to create serial devices dynamically, which are not linked to any D3 process. These devices are accessible only through BASIC get and send statements. It is convenient to create devices this way by inserting in the user coldstart macro the dev-make statements required to create these devices. For example:

dev-make -t serial -n 120 -a ’/dev/tty9’

creates a device ’s120’ associated to the UNIX device ’/dev/tty9’.

TCL interface

Some functions are accessible from TCL to be inserted in macros:

start Starts the I/O daemons.
stop Stops the I/O daemons. When a I/O daemon is in the middle of a call, it does not respond to a stop request.
queue Displays the queue. The v option shows detailed information about the queues instead of just the number of queue entries.
purge Purges a queue. The system must be specified by a clause system=name. No confirmation is required.
status Displays a device last message. The device must be specified by a clause device=name.

Reads the messages. This option has these arguments:

  • user=user.name. If user= is omitted, the current user name is used.

  • If the q option is used, only the number of messages displays.

  • An asterisk prompt displays. The commands are:

n Displays the message number n.
l Lists the messages numbers and subject.
pn Prints the message number n on printer.
d[{n}|* Deletes the message n, or the last message displayed or printed, or all messages (*) for the selected user.
q Returns to TCL.
msg Sends a message to a user on another system. The messages are stored in the dialer subsystem mail file, and can be examined with the option 7 on the main mail menu. This option has these arguments:
  • user=user.name
  • text=message
  • subject=subject.text
Note: When there is a space in a field, the data must be enclosed in quotation marks.
If user= is omitted, the current user name is used. If subject= is omitted, the user is prompted for an optional one line subject. If text= is omitted, the user is prompted for several lines of text, terminated by one line containing only a period. If the text of the message is null, no message is queued.
sysmap Sets the system map.
  • The option:

  • account=accname

    defines the account to be changed.

  • The option:

  • system=[*list|name{,name,...}]

    defines to which system the updates must be transmitted, where *list specifies that the list of system is in the select list, list.

  • The option:

  • remacc=accname{,accname,...}

    specifies the account name on the remote system. If this last option is not specified, if an account name in the list is missing, the account name on the remote system is identical to the local account name. There must be as many remote account names specified as there are remote system names.

  • The option:

  • files={-}{dict|data}[*|-|*list|name{,name,...}]

    specifies the files to be changed. If this last option is not specified, the files in the account are not changed, only the system map is affected. The hyphen specifies that the callx correlative must be removed from the specified files. If the keyword dict or data is specified, then only this element of the file is affected.

    Note: A space must be present, therefore the whole argument must be surrounded by quotation marks.

    The syntax:

  • files=* specifies all files in the account.

  • files=*list specifies that the list of files is contained in the select list, list.

  • files=name{,name...} specifies an explicit list of file names.

nopost Suppresses the posting of updates on the current port. This option remains in effect on the current port until the dialer post command is issued or the process logged off. This option can be used to manually update a local file without the changes being transmitted to the remote sites.
post Enables the posting of updates on the current port. This option is on by default when the process logs on.
files A dialer.log file used by the dialer subsystem is created automatically in the dm account. Its data levels are:
billboard A system-wide file keeps track of the posted updates.
conflict Contains the conflict information.
devices Valid devices list.
dialer.log Status of the I/O daemons.
log Permanent log.
mail File containing messages for the system administrator, such as error notice, acknowledgments, submit results, and so on.
map System map.
queue* system Queue to the system.
spool Spooled data.
systems Remote system definitions.

In case of incidents, files dialer.dump.mm/dd/yy are created, with the same data levels as the dialer.log file (except the permanent log). These dump files contain images of the dialer.log files at the time of the incident. An item reason in the dictionary explains the cause of the dump.


dialer {cmd} {device=name} {system=[*list|name{,name...}} {user=name}
{subject=descr} {text=message} {account=accname} {files={-}[*|*list|name{,name,...}}
{remacc=name,{name,,}} {(option}s


options q Quiet option suppresses all messages. On the mail command, this option displays the number of messages, if any.
v Verbose option displays more information.


Starts the dialer subsystem from TCL.

dialer start

Displays a detailed status of the queues.

dialer queue (v

Displays the last messages produced by the I/O daemon associated to the device s120.

dialer status device=s120

Stops the dialer subsystem, suppressing all messages.

dialer stop (q

Purges the queue to the remote system seattle.

dialer purge system=seattle

Queues a message for the user bob on the system dev.

dialer msg system=dev user=bob subject="Down time" text="We will shut down
tomorrow at 12:00"

Defines the system map for the account bob. Updates are transmitted to the systems dev, prod, and back. The remote accounts on these systems are respectively, bob2, bob (same as on the source machine) and bob3. All files, dictionary and data, are affected.

dialer sysmap account=bob system=dev,prod,back remacc=bob2,,bob3 files=*

Defines the system map for the account bob. The callx correlative is removed from all files.

dialer sysmap account=bob files=-*
Note: It is not necessary to specify the remote system when removing the callx correlative.

Defines the system map for the account bob. Updates are transmitted to the system dev. The remote account is the same as on the source machine. All files are affected. Only the data sections are changed, not the dictionary.

dialer sysmap account=bob system=dev files=’data *’
Note: Quotation marks are required.

Defines the system map for the account bob. Updates are transmitted to the system dev. The remote account is the same as on the source machine. Only the data sections of the files names, address, and zip are affected.

dialer sysmap account=bob system=dev files=’data names, address,zip’
Note: Quotation marks are required.

Defines the system map for the account bob. Updates are transmitted to the system dev. The remote account is the same as on the source machine. Only the dictionary section of the files specified in the select list pointer-file myfiles are affected.

dialer sysmap account=bob system=dev files=’dict *myfiles’

Defines the system map for the account bob. Updates are transmitted to the system dev. The remote account is bob2. Only the system map is changed. No file is affected.

dialer sysmap account=bob system=dev remacc=bob2