tcl.dialer Verb: Access/TCL


Command tcl.dialer Verb: Access/TCL
Applicable release versions: AP 6.1
Category TCL (746)
Description controls the dialer subsystem which allows transferring data to remote systems over the phone in a batch mode. The section 'dialer, General' explains the principle of the dialer subsystem and the main notions used here.

Using the menus :

Without any argument, a menu is displayed. The following are the valid keys. When indicated, arrow keys can also be used:
RETURN Executes the highlighted option.

'Q' Or ESC. Exit menu and go back to previous menu.

'X' Exit menu and go back to TCL.

n Number from 0 to 9. Select the option number 'n'. '0' is option 10.

letter Select the next menu option starting with the specified lumn. letter (except 'x' or 'q').

Ctrl-N Or down arrow. Move cursor down.

Ctrl-B Or up arrow. Move cursor up.

Ctrl-K Or right arrow. Move cursor right to next column.

Ctrl-J Or left arrow. Move cursor left to the previous column.

Ctrl-X Cancel, in a input field.

Displays :

The screen is divided in an upper section for menu display and a lower section for messages, help screen and user prompts.

Installation :

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:
Setup Local Host Name
Local host name :

Confirm (y/n/q) :
Enter any name, up to 8 characters and hit return. This name is also shown by the TCL command 'node'.
Setup Time Zone
1 UK
2 Azores
Confirm (y/n/q) :
Select the appropriate time zone and hit <RETURN>.

The remote sites and serial devices should then be set using the 'Setup Menu' described later.

Main Menu :

The main menu operation is used for normal operations. The options are:
1 Queue status
Display the status of the queues to all systems (system name, number of queued jobs and description of the next job) or of a specific system (detailed description of each job).

2 Device status
Display the last messages logged by a specified IO daemon. The messages are displayed most recent first.

3 Start dialers
Start the dialer IO daemons. This command can also be executed from TCL to be used in macros or PROCs. One IO daemon is started for each defined device.

4 Stop dialers
Stop the dialers IO daemons. This command can also be executed from TCL to be used in macros or PROCs. When a IO daemon is in the middle of a call, it will not respond to a stop request.

5 Setup
System setup and test. See the section 'Setup Menu' below.

6 Check conflicts
Display any pending conflicts between changes made to the local data base and changes received from remote systems. See the section 'Resolving conflicts' below.

7 List permanent log
The permanent log contains all messages logged by any IO daemon. This log is not cleared automatically. The messages are displayed the most recent first. Use the functions keys shown in the title to navigate though the log. Hitting a colon (':') displays a command menu which allows searching for special text and start 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 verb (see the section 'TCL Interface' below), or by the dialer subsystem itself. The list of all the pending messages, sorted by user and by time/date is displayed, with the destination user and the subject. The help section shows more information about each message. When selected, the first few lines of the messages are displayed and the user can P)rint it to the currently assigned form queue, D)elete it, or 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. See the section 'TCL Interface' below.

Setup Menu :

The setup menu allows defining the remote systems and devices used by the dialer subsystem, and perform accessory functions, like testing the communication, purging the queue, etc...

1 Local Host name
Define the name of the local system. The local system name must also be declared in all the other systems which can accept messages from this local system. This mechanism is required for security reason, to ensure that messages are properly authenticated.

2 Remote system
Define 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. The following elements must be provided:

System name
Any string of up to 8 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
Define for 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 will retry no more than three times to establish the communication. The syntax for the schedule is as follows:
Do 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.
any (or empty string)
Call at any time, as soon as data is queued for transmission. The actual transmission time will be within the next minute. This should be reserved to leased lines only, since it would be very inefficient to dial for each update.
The first four digits specify the starting time of the calling window, in 24 Hr format. The second set specifies the ending time. For example '2000-0100' means from 8:00 p.m. to 1:00 a.m.; '0100-0530' means from 1:00 a.m. to 5:30 a.m.
Define 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 a.m., 2:00 a.m., etc.. during the whole day. It is not advised to use too small a period. One hour should be a minimum, except in some very exceptional cases.

Phone number
Up to 4 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, possibly, should include any prefix, wait, extension, etc...

Specifies which devices can be used to establish communication. If none is specified, the system will select the first available device. See the section below about creating serial devices on Unix implementations. The syntax of the device number is:
S nnn
Dedicated serial device number 'nnn'. The system assumes it has exclusive access to this device.
Use the serial device normally associated to the Pick process number 'nnn'. When the serial device is needed, the Pick process will be 'unlinked' to take control of the device, and linked back on to it when the transfer is complete.

Defines the operations the specified system can or cannot do when calling IN. Enter 'y' or 'n' to each field:
Defines if the system is allowed to call in at all. If set to 'n', the local host will hang up if receiving a call from this remote site.
Defines whether the remote system is allowed to execute commands on the system. Commands are run by the IO daemon itself and should be short.
Defines whether the remote system is allowed to update the local system's data base.
Defines whether the remote system is allowed to perform remote maintenance operations.

3 Devices
Define a serial device. A submenu displays the list of currently defined devices or 'New device' to create a new entry. The following elements must be provided.
Device id
Device name. For a dedicated device, the id must be prefixed by a 's'. For a shared device, enter the Pick process number which is normally linked to the device to use. Do not use device 0. If shared, also specify the take over time below.
Enable or Disable. If disabled, no IO daemon is started and this device will not be used.
Direct 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.
Defines whether the device is Input only (it can only receive calls), Output only (it does not accept any incoming calls), or both.
Defines the serial port setting. Note the device MUST support 8 bit characters.
Take over time
Defines the time window during which the dialer will take over a serial device normally shared with a regular Pick process (i.e., 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 (eg '2200-0700') is specified, the device will keep 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 logon to Pick. If a periodic schedule (eg '*0030') is specified, the device will attach to the device for a period, then detach for the same period, then re-attach, for a new period, etc... Specifying 'any' or leaving this field blank, effectively makes it dedicated since the IO daemon will attach permanently to the device.
IMPORTANT: Changing the take over time schedule requires to stop and restart 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 (eg does not respond 'OK'), a factory reset is done.

4 Delete remote system
Delete the definition of a remote system.

5 Delete device
Delete 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 IO daemon started. The IO daemons MUST not be started on the local system else 'no device available' message will be 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 shows a sorted list of the accounts on the system (up to 256 accounts can be shown). Select the account to be set up, or 'ALL ACCOUNTS'. Note the 'dm' account is never selected. Then select to update either 'All files' or 'Select files or a select list of files. When the 'Select Files' option is chosen, the list of files in the account is displayed; Hit the <space> bar to select the file(s) to be changed and hit <return> when all the files have been selected; a '*' is displayed 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 level(s) 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. Finally, the list or remote system(s) where the data is to be sent must be entered, as well as 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 account(s) 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 (see the section 'TCL interface' below).

9 Purge queued updates
Purge the queue of data to be transmitted to either all systems or a select system.

10 Clear permanent log
Clear selected messages or all messages from the permanent log. A sub-menu allows selecting messages older than one week, one month, or all messages.

11 Connect to device
Connect directly to the device to send it some simple commands, like resetting the modem. The device must not be attached. Note that only simple 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 execute a command on it. The local site must have been declared with 'sysadmin' privilege n 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 IO 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 logon.

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 data base structure. Only raw data is presented. A more advanced conflict resolution requires understanding the data base organization and cannot be accomplished by a general purpose tool. The following section 'Conflict Data Format' details the stucture of the data stored in case of a conflict so that an application dependent tool can be developed.
When a conflict is selected, the following information is displayed:
From: sys Date: 12/14/94-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 hand side of the display shows the remote file information and the right hand side the local one.
The screen is then divided into two columns and more information is shown. The message area on the screen explains the reason of the conflict and prompts the user for action. The various conflicts are:
Number of attributes has changed
This indicates that, originally, the items on the local and the remote systems had different sizes. The display of the two items is an attempt at showing the the data on both systems. It is likely to be strange...

Conflicting attribute
The original attribute on the local system is not what it was on the remote system. The display shows the results of both changes.

Conflicting values in attribute
At least one value in the original attribute on the local system is not what it was on the remote system. The display shows the results of both changes.

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
1 Use the data received from the remote system to overwrite the local data.
2 Keep 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 will wait 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 which will be transmitted will the item at the time the transfer takes place, not the item the way it is at the conflict resolution time.
Q Quit. Leave the conflict unresolved.
C Cancel the conflict. The data is left as is on each system, CREATING INCONSISTENCIES ON THE DATA BASES. This option should be used with extreme caution.

Conflict Data Format :

The conflicting data is stored in the file 'dialer.log,conflict'. Each conflict is represented by 3 items:
- Conflict definition item. The item-id is a unique time date stamp. It contains the following attributes (defined in 'dm,bp,includes'):
CFLCT$DATE : Local conflict date.
CFLCT$TIME : Local conflict time.
CFLCT$ACCOUNT : Account on LOCAL system.
CFLCT$DICT : 'dict' if a dict, or ''.
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# in the diff string (see below)
CFLCT$REMACC : Account on REMOTE (source) system.

- 'Old' item. The 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. The 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 change to be applied. Each command is composed of one or more attributes, and start by a one letter code. The valid commands are:

Ln Original number of attributes in the item 'n'.

Cn{]m} Change attribute command starting at attribute 'n'. Change 'm' (default 1) attributes. This command is followed by 'm' pairs of attributes 'oldvalue/newvalue'.

Vn{]m} Change value command starting at attribute 'n'. Change 'm' (default 1) attributes. This command is followed by 'm' triplets of multi-valued attributes built as follows:
valnum ] valnum ] ...
oldval ] oldval ] ...
newval ] newval ] ...
'valnum' is the value number which is modified. 'oldval' is the old value. 'newval' is the new value. If the number of 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. In the example shown in the section 'dialer, General', the value change command would be:

An{]m} Add attribute command starting at attribute 'n'. Change 'm' (default 1) attributes. This command is followed by 'm' attributes which contain the added attributes. If the attribute 'n' is not empty, the new attributes are inserted before it.

Dn{]m} Delete 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 Pick/BASIC 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
include dm,bp,includes merge.sub
if m$code=0 then
* OK
end else
* Error
Note the include is not a subroutine. It is a fragment of code which can be included in-line. See the include itself for a description of the interface.
Other includes of interest are 'dm,bp,includes sdiff.sub' which builds a difference string between two items and 'dm,bp,includes sdiff2.sub' which merges (combines) two difference strings into one, cumulating the changes.

Creating Serial Devices on AP/Unix :

The AP/Unix implementations have the possibility to create serial devices dynamically which are not linked to any Pick process. These devices are accessible only through Pick/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 (see the documentation 'dev-make, TCL'). 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 Start the IO daemons.

stop Stop the IO daemons. When a IO daemon is in the middle of a call, it will not respond to a stop request.

queue Display the queue(s). The (V) option shows detailed information about the queues instead of just the number of queue entries.

purge Purge a queue. The system must be specified by a clause system=name . NO confirmation is required.

status Display a device last message. The device must be specified by a clause device=name .

mail Read the messages. This option has the following arguments: . If 'user=' is omitted, the current user name is used. If the (Q) option is used, only the number of messages is displayed. A prompt '*' is displayed. The commands are:
n : Show the message number 'n'
L : List the messages numbers and subject.
Pn : Print the message number 'n' on printer.
D[{n}|*] : Delete the message 'n', or the last message message displayed or printed, or all messages ('*') for the selected user.
Q : Return to TCL.

msg Send 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 the following arguments: text=message subject=subject.text . When there is a space in a field, the data must be enclosed in quotes. 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 Set the system map. The option account=accname defines the account to be changed. The option system=[*list|name{,name,...}] defines to which system(s) the updates must be transmitted. '*list' specifies that the list of system(s) is in the select list 'list'. The optional option remacc=accname{,accname,...} specifies the account name(s) on the remote system(s). If this last option is not specified, of 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 name s specified as there are remote system names. The optional option files={-}{dict|data}[*|-|*list|name{,name,..}] specifies the files to be changed. If this last option is not specified, the file sin the account are not changed, only the system map is affected. The '-' sign specifies that the CALLX correlative must be removed from the specified files. If the key word '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 quotes. The form 'files=*' specifies all files in the account. The form 'files=*list' specifies that the list of files is contained in the select list 'list'. The form 'files=name{,name...}' gives an explicit list of file names. See the examples below for practical examples.


The file 'dialer.log' used by the dialer subsystem is created automatically in the 'dm' account. Its data levels are:
System wide file keeping track of the posted updates.
Contains the conflict information
Valid devices list.
Status of the IO daemons.
Permanent log.
File containing messages for the System Administrator, like error notice, acknowledgments, submit results, etc...
System map.
queue* system
Queue to the system system .
Spooled data.
Remote system definitions.
Syntax dialer {cmd} {device=name} {system=[*list|name{,name...}} {user=name} {subject=descr} {text=message} {account=accname} {files={-}[*|*list|name{,name,..}} {remacc=name,{name,,}} {(options}
Options Q Quiet. Suppress all messages. On the 'mail' command, this option just shows the number of messages, if any.

V Verbose. Display more information.
Examples :
dialer start
  Start the dialer subsystem from TCL

dialer queue (v
  Display a detailed status of the queues

dialer status device=s120
  Display the last messages produced by the IO daemon asociated to the device 

dialer stop (q
  Stop the dialer subsystem, suppressing all messages.

dialer purge system=seattle
  Purge the queue to the remote system 'seattle'.

dialer msg system=dev user=bob subject="Down time" text="We will 
shut down tomorrow at 12:00"
  Queue a message for the user 'bob' on the system 'dev'.

dialer sysmap account=bob system=dev,prod,back remacc=bob2,,bob3 files=*
Defines the system map for the account 'bob'. Updates will be 
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, dict and data, are affected.

dialer sysmap account=bob files=-*
Defines the system map for the account 'bob'. The CALLX correlative 
is removed from all files. Note it is not necessary to specify the remote 
system when removing the CALLX correlative.

dialer sysmap account=bob system=dev files='data *'
Defines the system map for the account 'bob'. Updates will be 
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. Note the required quotes.

dialer sysmap account=bob system=dev files='data names, address,zip'
Defines the system map for the account 'bob'. Updates will be 
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. Note the required quotes.

dialer sysmap account=bob system=dev files='dict *myfiles'
Defines the system map for the account 'bob'. Updates will be 
transmitted to the system 'dev'. The remote account is the same as on 
the source machine. Only the dict section of the files specified in the select 
list 'pointer-file myfiles' are affected.

dialer sysmap account=bob system=dev remacc=bob2
Defines the system map for the account 'bob'. Updates will be 
transmitted to the system 'dev'. The remote account is bob2. Only the 
system map is changed. No file is affected.
Related tcl.dialer-copy