8 HELIOS utility programs

8.1 srvmsg

The “srvmsg” program allows a user to send a message to connected HELIOS AFP, SMB or Admin clients, to trigger the reconfiguration of a process, to set or change auditing options or to start live auditing for a process.

Usage:

srvmsg -m [-n <server>|-p <pid>|-u <user>] [-M <file>] ...          
srvmsg -r [-n <server>|-p <pid>|-u <user>]
srvmsg -c [-n <server>|-p <pid>|-u <user>] <command> ...          
srvmsg -d <pid> [-f <file>] [-l <level>] [-o <options>]
srvmsg -D <pid> [-l <level>] [-o <options>]
srvmsg -h

8.1.1 Options

-m

Send a message to one or more users connected to the host. The users are selected with the -n, -p or -u option. The number of characters in a message is limited to 255.

Note:: This feature is supported by OS X clients up to 10.8, and Windows clients up to XP. Likewise, all users that are connected to the host via HELIOS Admin can receive these messages.

-r

Send a “reconfigure” message to one or more processes. The processes are selected with the -n, -p or -u option.

-c

Send a command to one or more processes. The processes are selected with the -n, -p or -u option.

-d <pid>

Set auditing output options for the specified process. You must be “root” or owner of the process to use this option.

-D <pid>

Start live auditing of the specified process. The auditing output is printed to standard output. The auditing is turned off when you press Ctrl-C. You must be “root” or owner of the process to use this option.

Note:: The following options are used with -c, -m and -r to specify the users/processes where to send a message. If no process is specified, the message is sent to all users/processes. This can only be done by the user “root”.

-n <server>: Send message to all processes of the specified server, e.g. “afpsrv” or “pcshare”.
-p <pid>: Send message to a particular process ID.
-u <user>: Send message to a particular user. If the user is logged-on more than once, the message is sent to all processes of that user.

The following option is used with -m:

-M <file>: Take message from the specified file instead of command line.

The following option is used with -d:

-f <file>: Send auditing output to the specified file. If the file already exists, the auditing output is appended to the file. Auditing is turned off by specifying an empty file name (double-quotes only), e.g. -f "". We recommend to use the -D option which automatically turns auditing off when Ctrl-C is pressed.

The following options are used with -d and -D:

-l <level>

Specify auditing level, e.g. all. Otherwise a default level is used.

-o <options>

Specify the output options for auditing. Options can be “all” or a comma-separated list of the following options:

`time`	`short time stamp`
`fulltime`	`long time stamp`
`pid`	`process id`
`name`	`process name`
`thread`	`thread id`
`flag`	`flag name`
`file`	`source file name`
`line`	`source line number`
`func`	`function name`
`tabs`	`tab-separated output`

If -o is not specified, the following default options are used:

time,pid,name,line,flag,func

-h

Display help text.

Example 1:

# srvmsg -m -u neil "Closing down all services."

A message with the content “Closing down all services.” is sent to user “neil”.

Example 2:

# srvmsg -r -n pcshare

This command sends a flush/reconfigure to all “pcshare” processes. It forces “pcshare” to flush all files and to release unused resources.

Example 3:

# srvmsg -c -n desksrv freeze 20

This command freezes the desktop for 20 seconds, e.g. in order to do a snapshot of the volume.

Example 4:

# srvmsg -D 2990

Start live auditing on process 2990. Live auditing is stopped with Ctrl-C.

8.2 logrotate

Log files, such as printer or server log files, are updated whenever a related activity occurs. To maintain a certain order, they can be allocated a particular file name extension, e.g. by an ascending numbering. E.g. the printer log file which records the entries of today may be named “printer.acct”, the one with yesterday’s entries “printer.acct.0”, and so on (see C.1 “Printer log file structure”).

Usage:

logrotate [-n <numlogs>] [-m <mode>] [-o <owner>]
          [-g <group>] <logfile>

It may be reasonable to determine a cycle after which the oldest log file is discarded, e.g. after one week. “logrotate” coordinates the “rotation” of the log files with the following parameters.

8.2.1 Options

-n <numlogs>: Number of accumulated log files before “logrotate” starts the “rotation”.
-m <mode>: Octal expression for the file access rights. For example, 664 means that “owner” and “group” have the right to read and write, whereas “others” are just allowed to read the file.
-o <owner>: Owner of the file.
-g <group>: Group to which the file is allocated.

Example:

# logrotate -n 6 -m 664 -o John -g helios printer.acct

To change the default log rotation settings, the “HELIOSDIR/etc/daily/10base” file can be edited.

8.3 locktable

The “locktable” utility shows which files are locked by the HELIOS processes. You must be “root” to call the “locktable” command. The “locktable” program is also referred to as the “Open files tool”.

Usage:

locktable [-c]
locktable -d [-q]
locktable -h

8.3.1 Options

-c: Delete all locks in the locktable that are held by processes that do not run anymore.
-d: Delete the locktable file (only possible if HELIOS services are not running).
-q: Suppress error messages if locktable file cannot be deleted.
-h: Display help text.

Cross-platform file and record locking

An important HELIOS feature related to the protection of your files is cross-platform file and record locking. EtherShare and PCShare coordinate together to enable this feature. Without it, Windows applications are unaware when a Mac user has a file open, and vice versa. This means that they would be able to open and modify the same file at the same time, which could result in data loss. EtherShare and PCShare prevent this by accessing the same “locktable” file which allows cross-platform file and record locking even between Mac and Windows workstations.

Note:: Some applications do not use or support file locking, so it is prudent to verify this capability.

Example:

# locktable
Device:16777221 Inode:41643991 Open:1 Mode:RD,WR,DENY_RD,DENY_WR
Name: 'catalog.psd'
    Pid:6760 Owner:16 Fid:65535 Mode:RD,WR,DENY_RD,DENY_WR
Device:16777221 Inode:41643997 Open:2 Mode:RD,WR
Name: 'trading list.xlsx'
    Pid:6760 Owner:17 Fid:65535 Mode:RD,WR
    Pid:6760 Owner:19 Fid:65535 Mode:RD,WR
    Pid:6760 Owner:19 Fid:65535 Mode:WR Start:1 End:1

8.4 migrate

The “migrate” utility allows you to convert EtherShare and PCShare configuration files into preferences (though it is recommended that the 4.3.1 “Migrate settings” feature of HELIOS Installer be used instead). Beginning with EtherShare 3.1 and PCShare 3.1, all configuration settings are stored in one single file (“Preferences”). It is necessary to state the path which leads to the “old” EtherShare or PCShare (-e, -p) location in order to enable “migrate” to find the old configuration file. Additionally, the volume’s character set encoding must be stated (-E MacRoman, -P PC850 or -E SJIS).

Usage:

migrate [-e <esdir> -E <ESCharset>] [-p <pcdir> -P <PCCharset>]
        [volumes] [printers] [passwd] [interfaces] [ipaccess]
        [suffixes] [spot] [browsing]

8.4.1 Options

[volumes]

EtherShare and PCShare volume configurations will be migrated. If you do not want to migrate the PCShare volumes, the -p option can be omitted (-e for EtherShare).

The “afpvolumes” file is evaluated for HELIOS volumes. Here is an example for an entry in this file:

/es/volumes/ethershare:EtherShare::fixed:readonly:

The fields are separated from each other by colons. All fields listed here are taken on:

`Field`	`Content`
`1`	`UNIX path`
`2`	`Chooser name`
`3`	`password`
`4`	`Flags1 (only fixed or changeable permitted)`
`5`	`Flags2 (readonly, nopublish, noguest, charset=)`
`6`	`Groups (separated by commas)`

For PCShare volumes the “exports.pcs” file is evaluated. Here is an example for an entry in this file:
disk "pcsvol" '/data/pcsvol' public,utf8,charset=PC850

The following flags are accepted:

public
hidedotfiles
readonly
close
closefiles
utf8
charset=

[printers]

All EtherShare printer configurations will be migrated.

The following files are evaluated for EtherShare printers (“Preferences”, “atalk.conf”, “/etc/printcap”). Only those printers which have an entry in “atalk.conf” and in “/etc/printcap” are migrated. The “printcap” entry for a printer is taken on – except for the entries “lp”, “if”, “of”, and “af”. These receive HELIOS specific entries. The following spooler types are recognized in “atalk.conf”:

Balance
Disk
Hold
PAP
TCP
Preview
PDF

The spooler type, which was implicitly provided in “atalk.conf” through specific flags is set explicitly now in the “Preferences” by IfType=<Type>. Other flags keep their names, but are stored in the “Preferences”. For example, the parameter jobholdtime in the following excerpt from “atalk.conf” was taken on in the “Preferences” unchanged:

atalk.conf
hold: jobholdtime=21600

Preferences
[][Printers][hold][jobholdtime]
flags=0
type=int32
value=21600

[passwd]

The file “/usr/local/es/conf/afppasswd” is copied to “HELIOSDIR/var/conf/passwd”. This file is indispensable if the Encrypted Password Transport feature (compare 4.6 “HELIOS TCP/IP security overview”) is enabled.

[interfaces]

Network interfaces entries and zones entries in “atalk.conf” are migrated. They start with the following key words:

zone
zones
if
interface
nif
ninterface

[ipaccess]

The file “/usr/local/es/conf/afpipaccess” is copied to “HELIOSDIR/var/conf/ipaccess”.

[suffixes]

The file “/usr/local/es/conf/suffixes” is copied to “HELIOSDIR/var/conf/suffixes”.

[spot]

Spot colors are saved to the new configuration.

[browsing]

Adapts the browsing and WINS settings from the PCShare configuration files to preferences, which were introduced with CD018.

8.5 uniconv

The “uniconv” program, a Unicode conversion utility, allows the conversion of text strings from one character set encoding to another, e.g.:

	“PC850” to “UTF16BE”
	“SJIS” to “UTF8”

Currently supported encodings:

$ uniconv -l
MacRoman
PC850
ISO8859-1
UTF8
HeliosUTF8
UTF16LE
UTF16BE
UTF16
MacIcelandic
EUC-KR
MacArabic
MacCentralEurRoman
MacCyrillic
MacGreek
MacRomanian
MacTurkish
SJIS

Usage:

uniconv [-v] [-c] [-d] <InputEncoding> <OutputEncoding>
uniconv -l
uniconv -e

8.5.1 Options

-l: List all available encodings.
-e: Echo all arguments as UTF-8.
-v: Verbose mode.
-c: Convert Unicode to composite.
-d: Convert Unicode to decomposite.

<InputEncoding> and <OutputEncoding> can be one of the available encodings.

Example:

$ uniconv PC850 MacRoman <pcfile.txt >macfile.txt

8.6 socket

The “socket” command is similar to “telnet”. It reads data from “stdin” and sends it to a specified server. It also implements some functionality to measure throughput of data for message passing.

Connections can be established trough TCP or UNIX domain sockets (named pipes under Windows).

Using TCP based connections <server> and <port> can be used similar to telnet. If <server> is omitted, socket connects to “localhost”.

Usage:

socket [-v] [-d] [-k] [-r] [-b] [-m [-l <packlen>] [-c <count>]]
       [<server>] <port> 
socket [-v] [-d] -u <path> [-e] [-b] [-m [-l <packlen>] [-c <count>]] 
socket [-h]

8.6.1 Options

-b: Size of receivebuffer and sendbuffer.
-c <count>: Tell the client how many loops to run the test.
-k: Sets parameter to keep socket connection alive.
-l <packlen>: Size of a message packet the client should use for tests.
-m: Tell socket to do some message passing tests (see -b and -c).
-r: Use a reserved port on client side (only “root” can do that).
-u <path>: Specify a path the UNIX domain socket should be bound to (on Windows, a named pipe is used).
-e: Tell socket to discard received data.
-d: (UNIX only) disable line editing features to be able to enter non-ASCII characters.
-v: Cause socket to print debugging messages about its progress – this is helpful in debugging connections.
-h: Return the help info which also includes all service ports used by HELIOS software components.

Example 1:

$ socket -m -l 3072 -c 10000 172.16.7.155 12345

This call generates 10000 packages filled up with “A”s. Package length is set to 3072. “socket” is using a TCP connection to server 172.16.7.155 on port 12345.

Example 2:

$ socket localhost 2002

This call connects to the ImageServer service port 2002. Ctrl-C aborts the connection.

Example 3:

$ socket -u \\.\pipe\listen.pipe < someText

This call writes the content of the file “someText” to a Windows named pipe.

8.7 swho

The “swho” command can be used to list all currently active HELIOS child server processes, together with the process ID (PID), the network address, user name and process starting time:

$ swho 
Server   PID    Address        User     When 
pcshare  15984  tecra          anyuser  Thu  8:35 
afpsrv   56438  192.0.62.249   nobody   Thu  8:37 
pcshare  29610  Office         anyuser  Thu 10:31

In this example you can see one “afpsrv” login via EtherShare, as a guest user (“nobody”), and two logins via “pcshare”, with the user name “anyuser”.

The name of the PCs (“tecra” and “Office” in the above example) is only shown if the PC has been specified with name and IP address in “/etc/hosts” or in an equivalent host database. If the name is not known, the internet address is shown instead:

$ swho 
Server   PID    Address        User     When 
pcshare  15984  192.9.200.85   anyuser  Thu  8:35 
afpsrv   56438  192.0.62.249   nobody   Thu  8:37 
pcshare  29610  192.9.200.82   anyuser  Thu 10:31

Usage:

swho [-f stmp_file] [-c] [-n] [-p]

8.7.1 Options

-f [stmp_file]

Specify file other than default “HELIOSDIR/var/run/stmp” file, from which “swho” information is generated.

-c

Include an optional comment field, which shows more information about the session. PCShare servers show the name of the corresponding mounted UNIX directory or print command, EtherShare file servers (“afpsrv”) show the names of the currently mounted HELIOS volumes. In addition, sleeping clients are displayed in the Comment column:

$ swho -c
Server   PID    Address       User     When       Comment
pcshare  15984  192.9.200.85  anyuser  Thu  8:35  /public
afpsrv   56438  192.0.62.249  anyuser  Thu  8:37  Data SLEEPING

“swho” gets its information from the file “stmp”, which is updated by both PCShare and EtherShare servers. “stmp” is located in the “HELIOSDIR/var/run” directory.

-n

Suppress DNS lookup functionality. If this option is set, the network address always appears as IP address instead of its name.

Note:: If “swho” delivers quicker results with the -n switch set, you probably have a DNS configuration problem.

-p

Clear the “HELIOSDIR/var/run/stmp” file from entries which are orphans, i.e. cannot be assigned to current processes anymore.

Related information is available from the host’s current services list. See 14.1 “srvutil”.

8.8 ifstat

(This tool is not available on Windows.)

“ifstat” is a handy utility to see the network settings for each of the server’s network interface cards. Additionally, with the -l option specified, ifstat -l returns the IP number and subnet mask of the local subnet:

$ cd /usr/local/helios 
$ sbin/ifstat -l 
allow 192.168.123.0/255.255.255.0

These values can then be added to the default “ipaccess” list, in order to limit access to HELIOS services to only those nodes on the local subnet. The default “ipaccess” list does not provide any access restrictions to the host. See also 4.6.3 “IP access control list”, and ipaccess.local in 6.6.1 “HELIOSDIR/var/conf”.

Note:: Although the UNIX “ifconfig” offers more extensive network interface information, “ifstat” includes also AppleTalk settings – if available.

8.9 sqlite

This is a standalone public domain command line access program that can be used to administer an SQLite database and which serves as an example of how to use the SQLite library. The SQLite SQL documentation can be found here:
www.sqlite.org/docs.html

Usage:

sqlite [OPTIONS] FILENAME [SQL]

8.9.1 Options

-init filename: Read/process named file
-echo: Print commands before execution
-[no]header: Turn headers on or off
-column: Set output mode to “column”
-bail: Stop after hitting an error
-interactive: Force interactive I/O
-batch: Force batch I/O
-csv: Set output mode to “csv”
-html: Set output mode to HTML
-line: Set output mode to “line”
-list: Set output mode to “list”
-separator 'x': Set output field separator (|)
-nullvalue 'text': Set text string for NULL values
-version: Show SQLite version
-help: Show this text

8.10 toolclient

The “toolclient” application is the front-end of the HELIOS Tool Server and is installed with the HELIOS Base installation. It is available on any HELIOS supported server platform. “toolclient” requires a valid ImageServer license. The tool client finds the tool server via mDNS (“Bonjour”) or via a specified TCP/IP address. It can be integrated in any application by simply calling “toolclient” as an external application. HELIOS provides Script Server scripts for its included tools, for hot folder based job processing.

Find a description of the “toolclient” application in the Tool Server manual on the HELIOS website: www.helios.de/web/EN/support/manuals.html

8.11 “dt” tools

About the product

This chapter describes the “dt” tools, which mimic the functionality of some major UNIX commands for handling files, while maintaining the integrity of the HELIOS desktop database. “dt” tools also provide access to Mac specific file information from a UNIX prompt.

Important:: The “dt” program does not consider any file locking and can therefore also copy files in use. In order to avoid damage, consider this and make sure nobody is working concurrently on these particular files before manipulating them with ”dt“.

Why do I need the “dt” tools?

If you need to access files which are stored in a HELIOS volume from host scripts or commands, there are a lot of reasons for using the “dt” tools.

Note:: A host command is any script or program, e.g. a backup program, which accesses files stored in a HELIOS volume.

Any manipulation of a file or folder inside a HELIOS volume using ordinary UNIX commands, such as e.g. “cp”, “mv”, “rm”, will cause inconsistencies between volume information and the related desktop database, and you may lose additional data, e.g. file streams. Especially restoring files from a backup will cause such an inconsistency.

In the following sections, you will find more information on this problem, and on how the “dt” tools help avoid it.

NTFS file streams support

Files and directories in the Windows/NTFS environment may have a certain number of file streams. File streams contain metadata such as document title, subject, author, etc., similar to the resource fork of a Mac file.

The “dt” tools can handle Windows NTFS file streams. While accessing a file on the network that has been created in the Windows/NTFS environment, e.g. renaming or moving it on a HELIOS server, all pertinent file streams are considered as well.

File attributes such as Archive, Hidden, System, Creation date, Label settings, etc. are also preserved when using the “dt” tools. In addition, a fast file search can be performed via the desktop database, with file ID support.

The commands

Use the “dt” tools whenever you would (usually) use any of the following UNIX commands (if either source and/or destination files/folders are located in a HELIOS volume):

rm
rmdir
mv
cp
mkdir
touch
chmod
chown
chgrp

Two commands are similar but do not equal their corresponding UNIX commands:

ls
find (not on Windows)

“dt” has additional commands:

set (not on Windows)
upd
idinfo (not on Windows)
iddump
comment
ftsearch
ftinfo
sync (not on Windows)

You may use the “dt” tools even if the source or destination is not located in a HELIOS volume or if you are not sure about this. The “dt” tools automatically select the proper mode of operation. For example, if source and destination are not volumes “dt” acts like the corresponding UNIX program.

It is required to use the “dt” tools together with EtherShare, PCShare, WebShare and/or ImageServer. These HELIOS products have improved verification mechanisms to recognize potentially harmful configurations, and will disable access to volumes for which consistency between volume and desktop information cannot be assured. In addition, warning or error messages are written to the system log, which may help you locate the cause of the problem.

What are the differences to standard UNIX commands?

To help you understand the possible error messages and the specific behavior of the “dt” tools, here are the main differences from standard UNIX commands:

Each Mac file consists of two parts, the “data fork” which is stored as a standard UNIX file, and a corresponding “resource fork” which is stored in a “.rsrc” subdirectory. Additional information for each file is stored in a corresponding entry in a volume based “desktop” database. Therefore, when using UNIX commands, each operation like move, copy or delete, must consider both the “data fork” and “resource fork” as well as the database entry instead of just a single file
Windows files and directories may have additional streams as well
When looking at a volume as a UNIX directory you may not notice the differences, because the resource fork subdirectory and the database files are stored as hidden UNIX files
The “dt” tools simulate the behavior of standard UNIX commands as close as possible, but there are slight differences in the number and functionality of the available options, and due to the extended functionality you may notice a different behavior and different error messages. For example, you may see error messages about the resource fork of a file, which you would not see when using standard UNIX commands (the UNIX commands – in fact – ignore this part of the file)
You may see different errors on “dt chmod”, “dt chown”, and “dt chgrp” because in volumes, you need permissions to change not only the specified file but also the associated resource directory, the resource file and all streams
For more information about resource and stream handling errors, you may use the -v (verbose) option

Before you try and use any of the “dt” commands, you should be well familiar with the corresponding UNIX commands. If you need more information about how the “dt” tools work and how problems arise without the utilities, please read the technical notes following the command description, and 8.11.2 “Additional information”.

We do not recommend to sym-link regular “cp”, “mv”, “rm” commands to the “dt” tools. Although this is possible, you should verify your current and future system environment very carefully, to assure proper operation of your programs, scripts and established workflow.

Especially, you should check whether your site uses special HSM (Hierarchical Storage Management), tape robot or RAID (Redundant Array of Independent Disks) software which may also use their own versions of these UNIX commands. Take into account that different users and script based programs may make use of different shells and environment settings.

Before getting started …

We suggest to check for each HELIOS volume the consistency between the volume information and the volume’s desktop database. HELIOS Base offers a “rebuild” option, namely -s (scan only), which can be used for this purpose (see 8.12 “rebuild”).

Simply issue rebuild -s <path_to_volume_root> for every defined public or private HELIOS volume. Any output of this “scan” indicates a potentially harmful inconsistency between volume and desktop information. You should only continue after having re-synchronized the desktop database by means of an ordinary rebuild.

Note:: In the following, the term “volume” is used for a directory that is defined as a HELIOS volume which contains a desktop database (in contrast to a simple UNIX “directory”). Likewise, the term “volume root” refers to the top level folder of a HELIOS volume. The “HELIOS Applications” volume, for example, resides by default in the “/usr/local/helios/public”, which is its “volume root” directory under UNIX.

Take some time to make yourself familiar with the tools and the way they behave inside a HELIOS volume, between different HELIOS volumes, and between non-HELIOS and HELIOS volumes.

Notes about error messages

The “dt” tools use standard error messages starting with the program name (including the command argument), followed by the file or directory currently processed, and the error message, e.g.:

rm notHere may result in the error message:
dt rm: notHere: no such file or directory

The error messages are similar to those issued by standard UNIX commands. Please note that you may encounter additional error messages concerning the resource fork or the desktop database.

In some cases the “dt” tools may issue error messages displaying the full path of a file name instead of the passed relative one. This is due to the fact that the desktop database always needs absolute file names instead of relative ones. In this case, you may see the completely resolved (including symbolic links) absolute path name in the error message.

8.11.1 Command descriptions

General remarks

For the following command descriptions, the knowledge of the functionality of the corresponding UNIX commands is assumed. Please refer to your UNIX manual if you are not familiar with these commands.

If you do not need or want to know, how the “dt” tools operate, you only need to read the main command description for each UNIX command which is emulated by the “dt” tools. The technical description following each command is meant for advanced users or system administrators, and explains some details or the special behavior of the respective command.

With very few exceptions, “dt” behaves identically on all platforms supported by HELIOS. Please note that, for this reason, some platform-specific options could not be implemented.

For all commands, the standard UNIX permissions apply when accessing, removing or overwriting a file.

“dt” checks each passed argument for the following names:

.Desktop 
.DeskServer 
.rsrc

These files are handled implicitly by “dt” and there is no need to specify them directly. You should never move, copy or remove these files with other commands, as e.g. the standard UNIX tools. Do not manipulate them at all.

“dt” recognizes a HELIOS volume by locating its desktop database “.Desktop” file. Likewise “dt” recognizes access to HELIOS volumes from another server only by means of available “.DeskServer” files.

“dt” processes data and resource parts of files/folders in HELIOS volumes. If no resource information exists, “dt” will create at least minimum information. Especially copy or move operations may require more free space on destination file systems.

The following command modes are supported:

rm: Remove a file or directory (UNIX “rm”).
rmdir: Remove directory (if empty) (UNIX “rmdir”).
mv: Move/rename a file or directory (UNIX “mv”).
cp: Copy a file or directory (UNIX “cp”).
set (not on Windows): Set or change the Mac or Windows specific file attributes.
ls: List contents of a directory including Mac or Windows specific file attributes (UNIX “ls”).
mkdir: Create a directory (UNIX “mkdir”).
touch: Create a file or set its access and modification time (UNIX “touch”).
upd: Force update of HELIOS volume view.
chmod: Change or assign the mode of a file (UNIX “chmod”).
chown/chgrp: Change the user and group ID of a file (UNIX “chown”, “chgrp”).
idinfo (not on Windows): Display database information for the passed ID.
iddump: Display database information of all IDs for the passed volume.
find (not on Windows): Instead of recursively searching the directory tree of a volume, “dt” contacts the “desksrv” to let it find the file or folder names in its volume desktop database. This is usually very much faster than searching the complete directory tree.
ftsearch: Search HELIOS network volumes for content and metadata.
ftinfo: Get metadata information from a file in a HELIOS network volume.
comment: Display or change comment from resource information.
sync (not on Windows): Synchronize entire volumes, disks, or just a folder from one source to another destination.

If called without any argument, “dt” prints the usage line:

Usage: dt { rm | rmdir | mv | cp | set | ls | mkdir | touch | upd |
            chmod | chown | chgrp | idinfo | iddump | find | ftsearch | 
            ftinfo | comment | sync }

Calling “dt” with the command argument but no further arguments, prints the usage for the specific command. For getting the “dt ls” help lines, you must enter dt ls -h.

Many “dt“ tools support the options:

`-X`	Suppress desktop close delay
`-y`	Force scanning for streams
`-E`	Send events to notification server

-X (Desktop close delay)

Usually, the desktop of a volume is kept open for about 30 sec. when being used by “dt” in order to avoid overhead (open/close desktop database completely). This is because further access is to be expected. However, for certain workflows it is not advisable to keep the desktop for a volume open that long. Hence, with the -X option set, the desktop is closed immediately.

-y (Force scanning for streams)

Force scanning for streams that are not specified in the resource information of a file. This option checks the entire “.rsrc” directory of the current file. To avoid unnecessary search operations, the standard resource is marked if additional streams are available.

-E (Send events to notification server)

If this option is specified, file events are sent to the notification server.

dt rm

The “dt rm” command removes the directory entry specified by each file argument.

Usage:

dt rm [-firyXE] file ...

The following options are supported:

-f: Force removing without prompting the user.
-i: Prompt for confirmation for each file. If the answer begins with y (yes), the file is deleted, otherwise the file remains.
-r: Recursively remove passed directory and its subdirectories.
-y: Force scanning for streams.
-X: Suppress the desktop close delay.
-E: Send events to notification server.

In case of symbolic links, the link itself and not the file which the link refers to is removed.

If the standard input is not a terminal, the command will operate as if the -f option was set.

Examples:

$ dt rm file1 file2

removes the files: “file1” and “file2”.

$ dt rm -rf imagedir

removes the directory “imagedir” and all its contents, without prompting.

Note:

Missing resource forks are not reported unless the -v verbose option is set.

The volume root directory is automatically touched to announce the changes to any client that has mounted the volume.

When removing a directory using the -r option, “dt” automatically tries to remove any orphan resource forks or file streams. The volume root directory may only be removed if this volume is not in use by any other client, either EtherShare, PCShare, WebShare or the “dt” tools, otherwise a “directory not empty” error is issued.

dt rmdir

The “dt rmdir” command will remove the directory entry specified by each dirname operand, provided that this operand refers to an empty directory.

Usage:

dt rmdir [-psyXE] dirname ...

The following options are supported:

-p: Allow users to remove the directory dirname and its parent directories which become empty. A message is printed to standard error if all or part of the path could not be removed.
-s: Suppress the message printed on the standard error when -p is in effect.
-y: Force scanning for streams.
-X: Suppress the desktop close delay.
-E: Send events to notification server.

dt mv

“dt mv” moves the selected files or directories to the destination file or directory.

Usage:

dt mv [-fiknvzcyXEC] f1 f2 
dt mv [-fiknvzcyXEC] f1 ... fn d1 
dt mv [-fiknvzcyXEC] d1 d2

The three different usages are provided for the following cases:

Move a file “f1” to the destination file “f2”
Move the passed files “f1 … fn” into the destination directory “d1”
Move the passed directory into the destination directory “d2”. If “d2” does not exist, rename “d1” to “d2”

The following options are supported:

-f

Move the file(s) without prompting even if it is overwriting an existing target. Note that this is the default if the standard input is not a terminal.

-i

Prompt for confirmation for each file. If the answer begins with y (yes), the file is moved, otherwise it remains where it is.

-k

Keep ID, try to allocate the source ID and use it for the destination as well (see 8.11.3 “Using “dt” for backup/restore”). If this is impossible, you will only get a warning if -v is set. You can use this parameter to preserve proper working of Mac aliases.

-n

No resource forks if no desktop (see Default resource fork handling).

-v

Verbose, display extended warnings.

-z

Force zero ID for destination, please refer to Zero IDs and 8.11.3 “Using “dt” for backup/restore”.

-c

Move a file from one HELIOS volume to another with a different character set, without converting the character set or reporting corresponding error messages.

Important:: If you do not use the -c option with the “dt mv” and “dt cp” commands, an error message is only issued if you copy/move files from a HELIOS volume to another with a different encoding. Copying/moving from a UNIX directory will not provoke any warning at all.

-y

Force scanning for streams.

-X

Suppress the desktop close delay.

-E

Send events to notification server.

Note:: If a folder is moved with dt mv -E from a directory outside a HELIOS volume, or from one HELIOS volume to another HELIOS volume, the files within the folder are also subject to notification. Only if the folder is moved within a HELIOS volume, notification is issued only for the folder itself.

-C

Does not utilize the operating system disk caching. Use this option to avoid that heavy “dt” use takes all available cache memory.

The behavior of the different UNIX implementations differs if both the -f option and the -i option are set. “dt mv” uses the following rule: if both the -f option and the -i option are set, this is not considered an error; here, the -f option will override the -i option.

Important:: If you move a directory between HELIOS volumes, “dt” cannot simply rename just the directory entry (as a simple UNIX “mv” command would do). Here, “dt” as well as the Mac Finder would have to perform two steps for this operation, namely copying a folder from one volume to the other and then deleting the folder on the source volume. “dt” has a similar task to accomplish. For every file and folder within the directory to move, first the object must be copied to the destination volume and registered in the destination desktop. Then, the moved objects must be deleted from the source volume and unregistered from its desktop database.
This is similar to moving a UNIX directory to a different device, where also all affected files must be copied and then deleted, with the difference that here all resources and streams must be handled, too.

Please note that any Mac file/folder to which aliases are pointing will have lost its connection after successfully been moved between volumes. This would be the same if you used the Mac Finder for this operation. If source and target directory are on different file systems, “dt mv” copies the file and deletes the original; any hard links to other files are lost.

Volume root for both source and destination, is automatically touched to announce the changes to any client that has mounted the volume.

Usually, if a file is copied to a directory without a desktop database (pure UNIX directory), the file ID is set to zero. When using the -k option, the file ID is maintained.

Even though the execution bit of the data fork should be masked out (according to the permission handling implemented by “afpsrv”), this is often inconvenient to UNIX users. Therefore, any existing execution bit is preserved by default.

dt cp

“dt cp” copies the passed files or directories to a destination file or directory.

Usage:

dt cp [-fikpnvzcyXEC] f1 f2 
dt cp [-fikpnvzcyXEC] f1 ... fn d1 
dt cp -r[R] [-fikpnvzcyXEC] d1 ... dn-1 dn

The three different usages are provided for the following cases:

Copy a file “f1” to the destination file “f2”
Copy the passed files “f1 … fn” into the destination directory “d1”
Copy the passed directories into the destination directory “dn”

The following options are supported:

-f: Copy the file without prompting even if it is overwriting an existing target. Note that this is the default if the standard input is not a terminal.
-i: Prompt for confirmation for each file. If the answer begins with y (yes), the file is copied, otherwise not.
-k: Try to keep desktop ID.
-p: Preserve the owner and group IDs, permission modes, modification and access time.
-n: No resource forks if no desktop (see Default resource fork handling).
-v: Verbose, display extended warnings.
-z: Force zero ID for destination, please refer to Zero IDs and 8.11.3 “Using “dt” for backup/restore”.
-c: Copy a file from one HELIOS volume to another HELIOS volume with a different character set, without converting the character set or reporting corresponding error messages.
-y: Force scanning for streams.
-X: Suppress the desktop close delay.
-E: Send events to notification server.
-r: Recursively copy passed directory (see -R).
-R: Recursively copy passed directory while preserving symbolic links (see -r).
-C: Does not utilize the operating system disk caching. Use this option to avoid that heavy “dt” use takes all available cache memory.

The volume root directory for both source and destination, is automatically touched to announce the changes to any client that has mounted the volume.

If your source does not have a resource fork, and your destination is a volume, a default resource fork is created. Please do also take into account that every default resource will require 64 bytes, thus using the minimum disk block size on the destination file system. If there is only little free disk space on the destination volume, first check whether the destination file system can store all of the files. You can roughly calculate 1K (fragment size) per file/folder. Consult your UNIX system administrator or the appropriate pages in your UNIX manual for information on how to retrieve more exact information about your file system settings.

dt set (not on Windows)

“dt set” modifies the additional file information stored in the file’s resource fork. For more information about the flags and fields used here refer to your Apple documentation.

For a description of setting type and creator see 7.8.5 “Extension Mappings”.

Usage:

dt set [-t type | -c creator | -f file] file ...
-E send notify events
-X suppress close delay for desktop
dt set -l label-color (0-7) file ...
dt set -v [mini|symbol|name|date|size|type|label|button] dir ...
dt set -a[-][BisrlbpIPS] file ...
      B:bundle  i:Invisible  s:system  r:readonly  l:locked
      b:backup  p:protected  I:inited  P:Package   S:shared
dt set -L launchcount file ...
dt set -C file ...

The following options are supported:

-E

Send events to notification server.

-X

Suppress the desktop close delay.

-t

Set the file type for “file” to the passed value.

-c

Set the file creator for “file” to the passed value.

-f

Copy file type and creator from another file.

-l

Set label color (integer value 0-7).

-v

Flag which specifies one of the following Mac view modes for a folder (Mac OS 9 only):

mini symbol name date size type label button

-a

Flag which specifies the following modes:

	`Mac`	`Windows`
`B`	`bundle`
`i`	`invisible`	`Hidden`
`s`	`system`	`System`
`r`	`readonly`	`Read-Only`
`l`	`locked`
`b`	`backup`
`p`	`protected`
`I`	`inited`
`P`	`package`
`S`	`shared`
`[-]`	`Clear following flag`

-L

Set the file to number of allowed concurrent program launches, where “integer” is the number of launches.

-C

Clear the file ID numbers in the resource fork (set to zero) and force the “afpsrv” to allocate new ID numbers.

Please note that you may list this information using “dt ls”. If you need to set type or creator info with non-printable values, you may enter these values as octal values with a preceding backslash (“\”), and use the following escape sequences:

\b  backspace 
\n  newline 
\r  carriage-return 
\t  tab 
\f  form-feed 
\E  escape

Please note that for both type and creator, all characters including the 0 byte (\000) are valid. Each passed creator or type must be exactly 4 bytes long.

Examples:

$ dt set -t "TEXT" -c "R*ch" file

sets type and creator for “file” using ASCII values.

$ dt set -c "\000\000\000\000" file

sets creator for “file” using octal values.

$ dt set -f mypic file

copies type and creator from “mypic” to “file”.

$ dt set -ai file

sets the invisible flag for “file”.

$ dt set -a-i file

clears the invisible flag for “file”.

When you call “dt set” for a file without a resource fork, a default resource fork is created that is updated with the passed parameters, even if the destination file is not located in a HELIOS volume.

Please note that “dt set” does not create a missing “.rsrc” directory; use “dt touch” first on the file name in order to force creation of a related “.rsrc” subdirectory where the file’s resource information can be stored.

dt ls

For each file that is a directory, the directory content is listed; for each file that is an ordinary file, the name and resource related information are listed. When no argument is given, the current directory is listed.

Usage:

dt ls [-1FSUacdiIlmnprstux] { -e[STBacdfilopstxy] } file ...

The following options are supported:

-1: List one file per line.
-F: Append indicator [*/=@|] to names.
-S: Sort by file size.
-U: Do not sort – list entries in directory order.
-a: List all entries, including those beginning with a dot character (“.”), which are normally not listed.
-c: Show and sort by ctime (last modification of file status).
-d: Show directory itself instead of contents.
-i: Print inode number for each file.
-I: Print inode number in hex for each file.
-l: Long listing (flags, link count, user, group, size, date, name).
-m: Comma-separated list of entries.
-n: Like -l, but list numeric UIDs and GIDs.
-p: Append indicator [/=@|] to names.
-r: Reverse sorting order.
-s: Print size of each file as block count.
-t: Sort by modification time.
-u: Show and sort by last access time.
-x: Show entries by lines instead of by columns.

Extended flags (must be called with -e):

-S

Show resource file and streams for each entry. Each file, resource, or stream is displayed in a single line, preceded by an indicator letter: R for a resource file, E for a resource file with the extended additional stream flag set, and S for an additional stream. No indicator preceding the line means all other.

-T

Show resource creation time.

-B

Show resource backup time.

-a

Like -e cfit.

-c

Show resource creator.

-d

Show resource file name instead of UNIX name.

-f

Show resource flags.

flags: d:directory  A:alias      B:bundle
       P:package    i:invisible  s:system
       r:readonly   l:locked     b:backup
       p:protected  I:inited     S:shared

Note:: Mac aliases cannot be created by use of the “dt” tools. The internal structure of aliases is not documented by Apple.

-i

Show desktop ID.

-l

Show label color (integer value 0-7).

-o

Show nonprintable type and creator characters octal.

-p

Show desktop parent ID.

-s

Show combined resource and streams size.

-t

Show resource type.

-x

List non-printable type and creator characters hexadecimal.

-y

Force scanning for streams.

Examples:

$ dt ls /support/temp 
abc.mov

This command prints the names of all files in the passed directory “/support/temp”.

Sometimes you may wish to include more resource and stream specific information:

$ dt ls -l -ea /support/temp
-rw-rw-rw- 1 -----r--p-- 5 'MooV' 'TVOD' Jon admin 21988
Jan 5 2005 9:34 abc.mov

This command prints the file mode (read-write access for owner, group, and others), the number of links (1), Finder attributes (read-only, protected), Desktop ID (5), type and creator (MooV, TVOD), user (Jon), group (admin), size (21988 bytes), date and file name (abc.mov).

Please note that the output format (e.g. the time format) depends on the current settings for the local environment.

“dt ls” uses user and group information from the authentication server (if running), otherwise only UNIX users/groups are displayed.

dt mkdir

The “dt mkdir” command creates the passed directories including the corresponding resource fork and the desktop database entry.

Usage:

dt mkdir [-m <mode>] [-pyXE] dir ...

The following options are supported:

-m <mode>: Specify the mode to be used when creating the directory.
-p: This option creates “dir” by creating all the non-existing parent directories first. The mode given to intermediate directories will be the difference between 777 and the bits set in “umask”.
-y: Force scanning for streams.
-X: Suppress the desktop close delay.
-E: Send events to notification server.

Example:

$ dt mkdir -m0444 mydir

creates the directory “mydir” with the passed modes.

Note:: If no mode parameter is set, the final directory is created in octal mode 777 considering the file mode creation mask “umask”.

dt touch

The command “touch” sets the access and modification time for the passed files. A file is created if it does not already exist.

Usage:

dt touch [-XEy] file ...

The following options are supported:

-X: Suppress the desktop close delay.
-E: Send events to notification server.
-y: Fix extended streams flag.

Example:

$ dt touch myfile

dt upd

The “upd” command touches the volume directory for the passed file or directory, so that all Macs that have mounted this volume can display the changes. This may be necessary e.g. if a file is created under UNIX and the Mac would display the new icon only after closing and re-opening the corresponding window.

Please note that all “dt” commands automatically update any needed volumes; so this command is only required, if files are created or changed by other, non-“dt” commands. Check if you can adjust your workflow to “dt” commands and thus avoid potentially harmful non-“dt” commands.

Usage:

dt upd [-X] file ...|dir ...

The following option is supported:

-X: Suppress the desktop close delay.

Example:

$ dt upd myfile

dt chmod

The “chmod” command changes the permission mode of a file. The mode may be absolute or symbolic.

Usage:

dt chmod [-fRXy] absMode file ... 
dt chmod [-fRXy] [ugoa]{+|-|=}[rwxstugo] file ...

The following options are supported:

-f: Force, do not complain if the mode change fails.
-R: Recursively descend through directory arguments.
-X: Suppress the desktop close delay.
-y: Force scanning for streams.

An absolute mode is specified using octal numbers (0-7), please see the UNIX documentation for a full description.

A symbolic mode specification is a comma-separated list (without any spaces) of symbolic mode expressions of the form:

[who] operator [permissions] ([ugoa]{+|-|=}[rwxstugo])

In order to adjust permissions for files/directories and their related resource parts, you must own the directory in question. In case the resource directory does not match the enclosing directory’s permissions, “dt chmod” cannot adjust the “.rsrc” directory’s permissions. You have to log in as “root” in order to synchronize permissions of the two directories. Please refer to the UNIX documentation for a full description.

Examples:

$ dt chmod 444 file

sets read-only permission (0444) to “file”.

$ dt chmod a=rwx,g+s file

sets read (“r”), write (“w”), and execution (“x”) permission for all (“a”) users, and adds group set-ID mode (“s”) for groups’ permissions.

Note:: On Windows servers, when HELIOS volumes are shared via the AFP server, only basic permissions/access rights are supported. In addition, it is recommended to use the Windows “icacls” tool to manage permissions.

dt chown

The “chown” command changes the user ID of the passed file to the new user ID specified by owner and, optionally, the group ID to the new group.

Usage:

dt chown [-fhRXy] owner[:group] file ...

Note:: It is also possible to specify user and group information separated by a dot rather than a colon (GNU/BSD style). If a user name contains a dot, user and group must be separated by a colon.

Example:
'dt chown firstname.lastname:groupname file' or 'dt chown firstname.lastname: file' (preserves the current group).

The following options are supported:

-f: Do not report errors.
-h: If the file is a symbolic link, change the owner of the symbolic link (not the owner of the file that is referenced by the symbolic link). This option is not supported on all platforms.
-R: Recursively descend through the directory when setting the ownership for each file.
-X: Suppress the desktop close delay.
-y: Force scanning for streams.

A user ID and an optional group ID can be assigned. Both IDs may either be specified by the numeric ID or by the corresponding user or group name.

Please note that you need the necessary access rights to change the user or group ID of a file – according to UNIX semantics, only the user ID “root” is allowed to change ownership settings.

Examples:

# dt chown frank:support myfile

changes the owner for “myfile” to “frank”, and the group to “support”.

# dt chown 100 myfile

changes the owner for “myfile” to the user defined with the ID 100.

dt chgrp

The “chgrp” command changes the group ID of a given file to that of the new group.

Usage:

# dt chgrp [-fhRXy] group file ...

The following options are supported:

-f: Do not report errors.
-h: If the file is a symbolic link, change the group of the symbolic link (not the group of the file that is referenced by the symbolic link). This option is not supported on all platforms.
-R: Recursively descend through the directory when setting the group for each file.
-X: Suppress the desktop close delay.
-y: Force scanning for streams.

A group ID may either be specified by the numeric ID or by the corresponding group name.

Please note that you need the necessary access rights to change the group ID of a file – according to UNIX semantics, only the user ID “root” is allowed to change ownership settings.

Examples:

# dt chgrp support myfile

changes the group to “support”.

# dt chgrp 100 myfile

changes the group for “myfile” to the group defined with the ID 100.

dt idinfo (not on Windows)

The main purpose of this command is problem detecting. The Mac file or respective directory ID, is stored in both the file’s resource fork and the desktop database. The ID stored in the resource fork may be listed by using the “dt ls” command.

The “idinfo” command may be used to display database information for the passed ID. If there is no difference between the resource data and the corresponding database entry, you should get the same information, otherwise the system administrator should issue a “rebuild” for the specific volume. You can use rebuild -s <volume root> to verify that the volume information is properly reflected in the related desktop database.

Usage:

dt idinfo [-v volume] [-X] id ...

The following options are supported:

-v

Allows specifying the volume to be used or any file or directory inside the target volume.

Note:: Each volume has its own ID scope. Therefore, you must specify the correct volume for each ID you request. If you do not specify a volume with the -v option, the current working directory is assumed.

-X: Suppress the desktop close delay.

Examples:

$ dt idinfo -v /support 3159

prints the following information:

volume: '/support' id=3159 pid=2 name: 'temp'
path: /support/temp

specifying the detected volume, the ID, the parent ID for this file, and the corresponding name stored in the database.

Note:: Please note that an ID detected in the database that does not have any corresponding file in that volume does not cause any problems or data loss.

dt iddump

Each file in a HELIOS volume has an ID number that is stored in both its resource fork and the desktop database. The “dt iddump” command outputs all file IDs of the volume in question (specify volume path) from the desktop database to “stdout”.

Usage:

dt iddump [-X] volume

The following option is supported:

-X: Suppress the desktop close delay.

dt find (not on Windows)

Instead of recursively searching the directory tree of a volume, this command contacts the “desksrv” to let it find the file or folder names in its volume desktop database. This is usually very much faster than searching the complete directory tree.

Usage:

dt find [-v volume] [-eiX] pattern ...

The following options are supported:

-v: Specify the volume path (default is the current directory).
-i: Print the file ID.
-e: Match also partial strings.
-X: Suppress the desktop close delay.

dt ftsearch

Search HELIOS network volumes for content and metadata. The “dt ftsearch” usage, including all supported options and an example, are described in the HELIOS Index Server manual.

dt ftinfo

Get metadata information from a file in a HELIOS network volume. The “dt ftinfo” usage, including all supported options and an example, are described in the HELIOS Index Server manual.

dt comment

Display comment from resource information.

Usage:

dt comment [-s comment] file ...

The following options are supported:

-E: Send events to notification server.
-s: Set comment.
-v: Add file name to output.

dt sync (not on Windows)

Synchronize entire volumes, disks, or just a folder from one source to another destination (see 7.5.9 “Syncs”).

Usage:

dt sync [-fiknovVzcyXEKDSLC] [J -jobname] SRC DEST

The following options are supported:

-f

If an existing destination file cannot be opened, remove it and try again. This option is normally not required if “dt sync” is running as root (as recommended).

-i

Interactive: ask before overwrite.

-k

Try to preserve all desktop file IDs. However this works only if the destination has no files stored so far. For subsequent syncs the -k option makes no sense.

-n

Do not sync SRC file resource forks and streams to the destination.

-o

Print warning if files are write open during sync process.

-v

Show warnings and imply the -V option to show statistics (see below).

-V

Show a summary statistics line at the end, e.g.:

updated (files/size): 14122/17.3G - skip: 0/0B
- removed: 0/0B - directories: 733 - elapsed: 3 min
31 s 790 ms

-z

This option will set all destination IDs to zero. However the main benefit of “dt sync” is that it can sync between two active volumes. In most workflows this option may not be required.

-c

Copy a file from one HELIOS volume to another HELIOS volume with a different character set, without converting the character set or reporting corresponding error messages.

-y

Force scanning for streams.

-X

Suppress the desktop close delay. However, for “dt sync” this option is not of any benefit.

-E

Send events to notification server.

-K

Copy the link target instead of creating a symbolic link when copying files containing symbolic links.

-D

Do not remove files in DEST that no longer exist in SRC. This option is switched off by default because it is best to remove files from the destination if they do not exist in the source. Only this way can the synchronization destination size be calculated because then the destination requires the same amount of space as the source.

-S

Only scan what needs to be done and print the summary. Together with the -L option, it prints the individual files being scheduled for a sync.

-L

List one line per processed file to identify what would be changed, e.g.:

cp ovr : /Volumes/Temp/demovol/.DS_Store
cp new : /Volumes/Temp/demovol/Altona/
         altona_visual_1v2a_x3.pdf
cp new : /Volumes/Temp/demovol/Altona/
         altona_visual_1v2a_x3.pdf.annotation
rmdir  : /Volumes/Temp/demovol/Altona/
remove : /Volumes/Temp/demovol/Altona/
         altona_visual_1v2a_x3.pdf
chown  : /Volumes/Temp/demovol/Altona/
         altona_visual_1v2a_x3.pdf
chmod  : /Volumes/Temp/demovol/Altona/
         altona_visual_1v2a_x3.pdf

-C

Do not utilize the operating system disk caching. Use this option to avoid that heavy “dt” use takes all available cache memory.

-J

Specifies the sync job name. The sync job name is mainly used by HELIOS Admin to avoid duplicate tasks and for statistic purposes. This setting corresponds to the entry in the HELIOS Admin “Syncs” configuration Sync Job column.

Example 1:

Sync a source folder with a destination folder

# dt sync /SRC /DEST

A proper crontab entry to sync every night at 3am would be:

0 3 * * * /usr/local/helios/bin/dt sync /SRC /DEST

An enhanced cron entry which also sends notifications by e-mail would be:

0 3 * * * /usr/local/helios/bin/dt sync /SRC /DEST  2>&1 |
          mail -s "Daily Sync" admin@yourdomain.com

By default, “dt sync” prints nothing but critical errors. The exit code 0 means that the job was successfully done. The -V option shows a summary statistics line after the sync is completed. The -v option shows warnings and statistics. -E sends file notification events to keep the Spotlight search index up to date.

Note:: Especially to create and schedule recurring sync jobs, it is convenient to use the “Sync” feature in HELIOS Admin (see 7.5.9 “Syncs”).

Example 2:

Synchronize a single folder within a path

# dt sync /SRC/FolderA /DEST/FolderA

Example 3:

Scan only; print report of what would be synced

# dt sync -S /SRC /DEST

or alternatively:

# dt sync -S -L /SRC /DEST

Note:: When syncing folders containing symbolic links, these links will also be re-created in the destination because the modification dates of symbolic links cannot be set, and therefore “dt sync” just re-creates them.
“dt sync” supports UTF-8 volumes and file name encodings.

8.11.2 Additional information

The information in this section is mainly meant for system administrators who want to integrate the “dt” tools into custom solutions, e.g. backup scripts. You do not need this information for the simple use of the “dt” tools (however, it does not hurt to read on).

Files under UNIX

Each HELIOS volume is accompanied by a corresponding desktop database, which holds additional information about each file or directory stored in this volume.

Each file, directory or stream in a HELIOS volume consists of two parts: the “data fork” and the “resource fork”.

Though invisible to the user, both parts of a file and the corresponding information in the desktop database are handled transparently and automatically by EtherShare. On Mac and Windows, a file can contain a large number of additional streams (but no desktop database info).

If you also use ImageServer and/or PCShare these HELIOS products will also coordinate access to shared files/folders with the HELIOS volume desktop databases, and handle the resources and streams.

Looking at a volume from the UNIX point of view, you will find two files: the data fork as the “normal” UNIX file, and the resource fork in a subdirectory “.rsrc” with the same name, and all corresponding streams.

You will find more information about this in “Directory and file formats” in the HELIOS EtherShare manual.

Default resource fork handling

Since UNIX files consist of only one part, but Mac files of two (see Files under UNIX), each pure UNIX directory (“UNIX-dir”) should only have entries without a corresponding resource fork, and in a HELIOS volume (“volume-dir”) each entry must have a corresponding resource fork and can contain optional streams.

If you now copy or move an entry from a “UNIX-dir” into a “volume-dir”, “dt” always creates a default resource for this file. This is also the default behavior, if you move or copy a file from one “volume-dir” to the other. If you copy an entry from a “volume-dir” into a “UNIX-dir”, “dt” copies or moves the resource fork and streams as well, even if the resource fork is not needed here. This is done in order to avoid any unintentional data loss. If you do not want to consider the resource forks here, you may use the -n option for the “mv” or “cp” command.

Local and remote desktops

The “dt” tools do not require the desktop server to run on the UNIX server where you issue the commands, but by default the “dt” tools first try to connect to the local desktop server on the server where you issue the commands.

If this volume is already in use (e.g. mounted as a volume on a Mac) the “dt” tools try to connect to the current server which serves this volume. This could be a different server, e.g. if this directory is mounted via NFS. Source and destination are handled completely independently, e.g. a source file for a copy command may be served by a local desktop server, while the destination directory which is located in a NFS-mounted directory is served by another HELIOS desktop server.

The “dt” tools are unable to connect to a desktop server, when the target directory is not mounted by any HELIOS client and no local desktop server is running. In this case start a local desktop server or mount this volume on a HELIOS client.

The “dt” tools will do an extensive verification in order to connect to the proper desktop server. Nevertheless, please verify your environment so that no single HELIOS volume can be accessed at the same time from different HELIOS servers. See also the note in 13.2.3 “Relocate the desktop databases”.

Note:: If the same NFS data is accessed from multiple HELIOS servers, the check for cross-mounting can only work if both HELIOS servers are installed from the same HELIOS installation CD.

In case of different desktop servers being involved in a “move directory” operation, it may be necessary to traverse through directories and copy instead of just moving the directory entry – see dt mv for details.

Mount points and auto-mounter

Double mounts (access to the same directory under different mount points), e.g.:

mount     myserver:/usr/es /es 
mount     myserver:/usr/es /home/user1/es_copy)

will lead to differences between volume and desktop information, resulting in inconsistencies.

Please note that you may unintentionally cause this problem by accessing an already mounted file system via auto-mounter:

$ dt cp /net/myserver/usr/es/file1 file2

You can avoid this problem by not running auto-mounter on any of the involved servers (source and destination).

Zero IDs

In any mounted volume, the HELIOS file servers automatically detect any file which has an accompanying resource fork with a zero ID (the ID set to numerical zero) when the parent directory is opened from a Mac or Windows client.

A file without a valid ID does not have any database entry, and therefore, a new desktop database entry is created, and the resource fork is updated using the new ID.

The “dt” tools never create zero ID resource forks in volumes unless you force this behavior using the -z flag for the “cp” and “mv” commands.

Important:: This option should only be used by system administrators – it is not intended for normal use!

8.11.3 Using “dt” for backup/restore

One main purpose of the “dt” tools is to avoid problems when restoring data from a backup device. Here we describe how you should use the “dt” tools for backup/restore purposes:

Backup

You may backup your data as usual directly from your volume. HELIOS “dt” ensures that the hidden “.rsrc” directories are included. To prevent backup of incomplete data in files, make sure that the files/folders to be backed up will not be manipulated from other client or UNIX applications. If you intend to do a complete backup and restore of a HELIOS volume and include the “.Desktop” file, see 13.2.1 “Online backup copies of a live volume”.

Important:: Never restore your data directly into the destination volume!

Restore

Please create a restore directory on the same device (partition) where the destination volume resides, e.g. if you intend to restore files into “/data/mypics”, create a directory “/data/restore”. This “restore” directory must not be defined as a volume. Now restore your data using your usual restore procedure into this newly created directory “restore”. Make sure that you do not restore the “.Desktop” and “.DeskServer” files.

Important:: Never remove these files (“.Desktop” and “.DeskServer”) from a mounted volume or manipulate them directly! This may cause not only data loss for this volume, but may cause problems for all defined volumes on the server. In case you want to backup/restore these files, make sure that EtherShare and PCShare (if you are sharing volumes) are stopped completely PRIOR to your backup/restore operation. Only if you stop HELIOS by means of “stop-helios” and stop access from other HELIOS servers, can intermediate access to these files from HELIOS processes be prevented.

Finally you must move the restored files into their final destination. This procedure avoids any data loss and may be used in a mounted destination volume.
Usually, new (unused) file IDs are assigned when you copy files to a backup destination. It may, however, be sensible to keep the file ID (using the -k option). Thus, the file can be re-used with its original ID. This is especially useful if you are using Mac aliases pointing to these files/folders. You should use this option sensibly. In case a complete desktop rebuild has been conducted after your backup operation, aliases may point to the wrong destination. To avoid any problems, it may be a good idea to run an integrity check for the destination volume by entering rebuild -s on the command line, before restoring any files.

The HELIOS “dt” tools provide UNIX compatible file management to Windows. “dt” supports UTF-8 parameters and listings, and does not need a CLI to work. Setting UNIX like file permissions (“owner”, “group”, “other”, “mode”) can be done from within “dt” and will be translated into Windows ACL permissions. Using “dt” tools within scripts has the advantage that Perl scripts will work on both Windows and UNIX platforms.

Complementary solutions for archiving purposes can be found on the HELIOS website: www.helios.de

8.12 rebuild

Note:: If you are not familiar with desktop rebuilds, we strongly recommend to use Rebuild Desktop in HELIOS Admin instead of the “rebuild” program. For volume conversions use the HELIOS utilities “convertvol” and “converthome”, which are described in the HELIOS EtherShare manual.

However, there is one particular situation where it may be required to use the “rebuild” program:

If you want to rebuild the “.Desktop” database for your home volume. The desktop server will create a “.Desktop” database and resource directories the first time you access your home volume from the client, and will rebuild it if it becomes corrupted, but you will not be able to rebuild it manually from HELIOS Admin because it does not appear in the volume list.

Resource orphans

The “rebuild” program offers an option to clean (delete) resource orphans. As discussed earlier, the file server creates resource files for files created by UNIX applications when the corresponding folder is opened. However, when you delete a file directly from the host, the matching resource remains untouched. But when you delete a file from a client, the resource file is deleted, too. So particularly if your HELIOS volume contains a mixture of client files and UNIX-only files, after a period of time the volume will tend to collect a number of unused resource “orphans”, wasting space. Calling the “rebuild” program will automatically delete the resource orphans. You would have to set the cleanorphans preference of the “rebuild” program to FALSE to prevent the program from automatic deletion (see 19.7 “Rebuild preference keys”).

Usage:

rebuild [-2cfnopsvxt] [-C oldes|utf8] [-U charset] [-D charset]
path_to_volume_root

8.12.1 Options

-2: Disable 2 ID check passes (by default 2 ID check passes is active, which is slower but more accurate).
-c: Do not clean resource orphans automatically (clean orphans is default if -c is not specified).
-f: Force “.Desktop” file to be rebuilt (force create is off if -f is not specified).
-n: Output to system messages file instead of “stdout”.
-o: Open “.Desktop” file only, repair if corrupted.
-p: Output the converted file names.
-s: Scan file system and verify with desktop file (scan is off if -s is not specified).
-v: Verbose for diagnostics (verbose is off if -v is not specified).
-x: Volume is exclusively opened for rebuilder.
-t: Print rebuild statistics every 10000 items.
-C: Convert volume file names from old EtherShare “:hex” to “UTF-8”.
-U: Specify character set for a volume (e.g. PC850).
-D: Change the display character set. The default are raw UTF-8 characters.

Examples:

Force “.Desktop” file to be rebuilt:

# rebuild -f /usr/local/helios/public

Convert volume file names from the old EtherShare to the UTF-8 volume character set:

# rebuild -C utf8 /data/my_testvolume

Read-only volumes

In the case of CD-ROM volumes or volumes such as magneto-optic (MO) cartridges which have been mounted with HELIOS Admin as “read-only”, the desktop server first checks to see if a valid “.Desktop” file is available on the volume’s root. This can be the case, for example, for MO cartridges which were previously mounted under EtherShare as “read-write”, allowing a valid desktop to be created.

If a valid “.Desktop” file cannot be found (this will almost always be the case for CD-ROMs), the desktop server creates a temporary desktop file in the host’s “/tmp” directory using a unique file name starting with “desksrv…”. Since the files on the CD-ROM almost certainly have no resource forks in this case, the Finder will use the information that are available in the extension mapping table or show one of the about 20 generic EtherShare icons.

8.12.2 Preferences of the “rebuild” program

When it starts, the “rebuild” program first accesses the main configuration file “Preferences” to determine its configuration. 19.7 “Rebuild preference keys” lists the preferences, which can be changed if necessary by using the “prefvalue” command. See also 8.13 “prefvalue”.

8.13 prefvalue

Setting and retrieving single entries in the preference database (see 19 “Preferences”) can be done using the program “prefvalue” in “HELIOSDIR/bin”.

Current preference value

To get the current value of a preference only, specify a key.

Usage:

prefvalue -k '<key>' [-ld[r]] [-t type] [-p PreferenceFile]
                     [-f valuefile||value]

The preference key is the whole string containing the preference key strings which are delimited by “/” characters.

Important:: Please note that key names are case-sensitive!

Example:

# prefvalue -k 'Programs/pcshare/hostname'

“prefvalue” is the command and -k the preference key (here Programs/pcshare/hostname).

Important:: If the key contains a path, the “/” characters within the path must be “marked” by preceding each with a “\” character.

Example:

# prefvalue -k 'Volumes/\/data1\/applications/AFPName'

Setting a preference

To set a preference value, specify key, type and value.

Usage:

# prefvalue -k '<key>' -t <type> <value>

value is the value the preference will be set to. type is one of the following and may only be used when setting a preference:

Type	Value
`bool`	TRUE or FALSE
`int (int32)`	Signed (32-bit) integer value
`uint (uint32)`	Unsigned (32-bit) integer value
`int64`	Signed (64-bit) integer value
`uint64`	Unsigned (64-bit) integer value
`double`	Floating point number
`ulist`	List of unsigned integers, separated by comma
`str`	String
`strlist`	List of strings, separated by comma
`data`	The value cannot be taken from the command line and therefore requires a value file specified

Example:

# prefvalue -k 'Programs/pcshare/hostname' -t str ankh

“prefvalue” is the command, -k the preference key (here Programs/pcshare/hostname), -t the value type (here str for string), and the last argument is the value to set (ankh).

Deleting a preference

To delete a preference, specify a key and the -d option.

Example:

# prefvalue -k 'Programs/pcshare/hostname' -d

“prefvalue” is the command, -k the preference key (here Programs/pcshare/hostname), and -d the option to delete the preference.

Deleting all preferences of a key

To delete a key with all its sub-preferences, specify the -r (recursive) option.

Important:: Use this command with caution! Make a backup copy of “HELIOSDIR/var/conf/Preferences” first.

Listing preferences

To list all preferences of a key, specify the -l option.

Example:

# prefvalue -k 'Programs/pcshare' -l 
hostname
enablewins
ipaccess

8.14 prefdump

Dumping preferences into a readable form can be done using the “prefdump” command in “HELIOSDIR/bin/”.

Usage:

prefdump [-o DumpFile] [PreferenceFile]

Example:

# prefdump -o 'HELIOSDIR/var/tmp/prefs.txt'

“PreferenceFile” is the binary preference database file which contains the preferences. If omitted, the default file “HELIOSDIR/var/conf/Preferences” will be taken.

If “DumpFile” is specified the preference database will be exported to that file. If omitted, the preference database will be printed to “stdout”.

8.15 prefrestore

Restoring preferences which have been dumped into a readable text file (e.g. with “prefdump”) back into the binary “Preferences” file can be done using the command “HELIOSDIR/bin/prefrestore”.

Usage:

prefrestore [-p PreferenceFile] [-c] [DumpFiles ...]

Example:

# prefrestore 'HELIOSDIR/var/tmp/prefs.txt'

“PreferenceFile” is the binary preference database file which imports the preferences from the file “DumpFile”. If omitted, “HELIOSDIR/var/conf/Preferences” will be taken.

With the -c option set, all old preferences are deleted and then the new preferences are loaded. Without -c option, new preferences are loaded additionally to the already existing preferences. In doing so, those with the same key are overwritten.

Not all available preferences are set by default, which means that they are not listed in the “prefdump” output, and the HELIOS products will use the given default values. When a different value is set by means of “prefvalue”, this will take precedence. To revert back to the HELIOS default value, use prefvalue -k <key> -d to delete the preference entry.

8.16 mail

“mail” is a cross-platform mail client. It is based upon the HELIOS libraries, which is the reason why it works independently from the used architecture, and why it can be used very well in a scripting environment.

The program delivers the e-mail to an SMTP server. The SMTP server can be specified via options or via preferences (see -m option below).

Usage:

mail  [-f sender] -t to-address [-c cc-address] [-B bcc-address]
      [-s subject]  [-r replyto] [-e encoding] [-m SMTPServer]
      [-b msgtext]  [-o <options>]
mail  -h (for help info)

8.16.1 Options

-f

Sender address (“From:”). If the sender address is not specified, the current user name is used

Note:: External mail services/providers require the specification of a correct “From:” address. Otherwise, various error messages – which may be misleading – can be issued, e.g. Syntax error in parameters or arguments.

-t

Comma-separated list of recipients (“To:”). This parameter is mandatory

-c

Comma-separated list of additional recipients (“Cc:”)

-B

Comma-separated list of additional recipients whose addresses are not included in copies of the message (“Bcc:”)

-s

The subject line

-r

Address to which replies should be sent (“Reply-To:”)

-e

Character encoding used in the mail message. The default is UTF-8

-m

SMTP server which is used for delivering the mail. If the option -m is not set, the preference SMTPHost (19.3 “Global preference keys”) is used

-b

The mail message (text). If this parameter is missing the input is read from standard input, until the input is terminated or a line with only a dot “.” is read

-o

A comma-separated list of <key>=<value> pairs, specifying additional options for the connection with the SMTP server. If this option is not given, the value of the “Global/Programs/SMTPOptions” preference (see SMTPOptions in 19.3 “Global preference keys”) is used.

Possible options are:

Security=None
Do not encrypt the SMTP connection.

Security=STARTTLS
Start an unencrypted connection and change to SSL/TLS if supported by the server. This is the default if the connection does not use port 465.

Security=SSL
Create an SSL/TLS connection to the server. This is the default if the connection uses port 465.

SSLCert=<path>
Path to an SSL certificate file (in PEM format) to be used for the SSL connection. The file must contain both the certificate and the corresponding private key. By default, no client certificate is used.

In addition, SMTPHost may also contain – apart from the actual address of the SMTP server – name and password for authentication:

name:password@Serveraddress

Examples:

Send a simple e-mail to “user@domain.com”:

$ mail -t user@domain.com -s 'Test subject' -b 'This is a mail test.'

For longer e-mail messages it is easier to put the message text into a temporary file and send the message with:

$ mail -t user@domain.com -s 'long test' < msgfile

Send an e-mail using an SMTP server requiring authentication:

$ mail -t user@domain.com -m "user:password@smtpserver.com"

Send an e-mail using an SMTP server requiring SSL authentication, via a specific port:

$ mail -f sender@domain.com -t recipient@domain.com -oSecurity=SSL
-m 'sender@domain.com:password@smtpserver.com:port' -s 'test1'
-b 'This is test 1'

8.17 machid

A “machid” request from the command line delivers the host's machine ID.

Example:

$ cd /usr/local/helios 
$ bin/machid 
c21d9296-d3

8.18 oiinfo

The “oiinfo” program allows you to view a list of all “OpenImage” plug-ins that are installed and available. The program, by default, searches the directory “HELIOSDIR/lib/OpenImage/Plug-ins”. Every file in this directory will be checked to find out whether it is a plug-in and, if so, what type of plug-in it is.

The program returns information about name and version of the respective plug-ins.

Example:

$ /usr/local/helios/bin/oiinfo 
Found Plugin at /usr/local/helios/lib/OpenImage/Plug-ins/opibase.so: 
       Magic is HeliosOpenImage. 
       Version is 1.0. 
       Module is HeliosBase 
       Module description is "HELIOS ImageServer base functionality". 
       Module version is 3.5.

Furthermore, for every correct plug-in, the “oiinfo” program lists all included “OpenImage” managers.

Example:

Modtoc: 
	Sectiontype 1: HeliosUnixFs (Helios Unix Fs mgrs)
	Sectiontype 1: HeliosNativeFspec (Helios Native Fspec mgrs)
	Sectiontype 1: HeliosESFspec (Helios EtherShare Fspec mgrs)
	Sectiontype 1: HeliosPCSFspec (Helios PCShare Fspec mgrs)
	Sectiontype 1: HeliosTiff (Helios TIFF mgrs)
	Sectiontype 1: HeliosJPEG (Helios JPEG mgrs)
	Sectiontype 1: HeliosEPSF (Helios EPSF mgrs)
	Sectiontype 1: HeliosScitexCT (Helios Scitex CT mgrs)
	Sectiontype 1: HeliosAdobePhotoShop (Helios Adobe PhotoShop mgrs)
	Sectiontype 1: HeliosLargePhotoShop (Helios Large PhotoShop mgrs)
	Sectiontype 1: HeliosPICT (Helios PICT mgrs)
	Sectiontype 1: HeliosMacintoshIcons (Helios Macintosh Icon mgrs)
	Sectiontype 1: HeliosAdobePath (Helios Adobe Path mgrs)

After that, you will get a list of “OpenImage”-registered managers. This specific list provides information about which managers are available for use.

Example:

Manager type : Color
 Predicate   : 17610
 Version     : 1  
 Quality     : 127
 Registered key is
   Scope              : (00271) HeliosColorICC
   Filesystem         : (00000) *
   Filespec           : (00000) *
   Filecreator        : (00000) *
   Filetype           : (00000) *
   Filetype Extension : (00269) ICC
 Manager supports raster images.
 Manager supports the following capabilities:
  Capability 1:
   Supports colorspace mapping:
    Maps colorspace from Bilevel to Bilevel.
   Supports ICC colormatching.
   Supports image valuating.
   Supports inkset change:
    Accepts imagedata with any inkset.
    Produces imagedata with any inkset.
   Supports bpc change:
    Accepts imagedata with 1 bpc.
    Produces imagedata with 1 bpc.
…
  Capability 3:
   Supports colorspace mapping:
    Accepts imagedata in any colorspace.
    Produces imagedata in any colorspace.
   Supports ICC colormatching.
   Supports image valuating.
   Supports inkset change:
    Accepts imagedata with any inkset.
    Produces imagedata with any inkset.
   Supports bpc change:
    Accepts imagedata with 16 bpc.
    Produces imagedata with 16 bpc.

-f: Additionally includes information about all registered fonts.

8.19 pstext

The “pstext” program in the “HELIOSDIR/bin” directory allows simple ASCII files and files in “nroff” format to be printed on PostScript printers. Since PostScript printers usually cannot accept print jobs consisting of “flat” ASCII data, it is normally not possible to print UNIX program listings or to print from UNIX programs that only support a simple matrix printer. The necessary conversion can be made with this program. “pstext” can also check the print job for special sequences starting with the “Esc” character, which can be used to control simple highlighting features such as bold printing, underscoring, and different fonts.

The HELIOS print server is able to differentiate “flat” ASCII data from PostScript data automatically, and calls “pstext” to convert the job accordingly. Thus, it is usually not necessary to call “pstext” manually. See also magic in 19.4 “Printer preference keys” for related information.

“pstext” is started from the command line in order to convert an existing file for printing or from inside a server host pipe in order to be able to directly print from an application without having to spool the ASCII print output to disk. “pstext” can be controlled with additional parameters in typical host style.

Usage:

pstext -f <Font> -s <Size> -h <Title> -e <PrepFile> 
       -L <LeftMargin> -T <TopMargin> -t <Tabsize> 
       -c <LineSpace> -o -l -m -n -p <Printer> file1 file2 
       -d <NewPrepFile>

The following is an example of a typical command to print an ASCII file:

$ pstext -p lw .profile

This command converts the file “.profile” to PostScript and sends it to the printer “lw”. To do this, “pstext” calls “lpr” with the specified printer name. If the option -P printername is omitted, the generated PostScript code is output to the terminal for test purposes, rather than to the printer.

The following is an example of the use of “pstext” in a server host pipe. It outputs the current directory to the printer “lw”:

$ ls -l | pstext -p lw

The following example prints an entry from the UNIX manual:

$ nroff -man /usr/man/man1/ls.1|pstext -p lw

8.19.1 Options

-f: Font with which the document should be printed. The default here is “Courier”, because this is one of the few commonly available non-proportional fonts, which makes it particularly suitable for listings and tables.
-s: Size of the font in points. The default is 10 points. One point is 1/72 inch.
-e: Name of a PostScript language “prep” file which should be added to the start of each print job. If you do not specify the -e option, “pstext” automatically uses the internal “prep” file. This file contains definitions which are needed by “pstext”. Instead of specifying an alternative “prep” file name in the command line with the -e option as above, you can set the name with the UNIX environment variable “$PSTEXT_PREP”. This avoids having to specify the -e option. See the -d option below for more information about using and editing the “prep” file.
-m: Print the date of the last modification to the file on the top line of each page, instead of the current date.
-h: The specified title is automatically printed on the top line of each page. If this option is omitted, “pstext” automatically prints the file name and the date on the top line.
-L: Specifies the space to the left paper edge in points. The default varies slightly from printer to printer, and is approximately 20 points.
-T: Specifies the space from the top paper edge in points. The default varies slightly from printer to printer and is approximately 14 points.
-o: Suppresses the title line. You normally want to suppress the title line if you are using the “pstext” escape interpreter, because you are probably printing with a more “intelligent” program which generates its own header in this case.
-l: Rotates the printed output by 90° (landscape mode printing).
-n: Turns off the “pstext” escape interpreter. No characters are checked for control functions.
-t: Specifies the distance of each tabulator stop in units of the width of the character “M”. The default is eight, i.e. the width of eight “M”s (“MMMMMMMM”) for each tab stop.
-p: Name of the printer to which the file should be output. If this option is omitted, the generated PostScript code is output to the terminal (“stdout”).
-c: Defines the desired line spacing in font height. The default is once the height of the used font.
-d: Can be set to dump the internal “prep” file “pstext.ps” to a file for further editing and use it with the -e option.

8.19.2 Escape interpreter

“pstext” can check the print job for special sequences starting with the “Esc” character, which can be used to control simple highlighting features such as bold printing, underscoring and different fonts. This is particularly useful for programs that normally work with a matrix printer. With such programs, it is often possible to enter the control codes to specify particular print attributes into a configuration table.

An escape sequence for “pstext” has three parts: The first is the “Esc” character (Hex 1B), which is then followed by a command (a digit between one and six), followed by the value of the parameter within square brackets, for example:

ESC 4 [10] or in hex: 1B 34 5B 31 30 5D

Escape sequences

The following is a list of the supported escape sequences:

ESC 1 [1]

Underline on.

ESC 1 [0]

Underline off.

ESC 2 [1]

Bold printing on.

ESC 2 [0]

Bold printing off.

ESC 3 [Helvetica]

Choose a new font, in this example “Helvetica”.

ESC 3 [Courier]

Choose the standard font. “Courier” is the default font.

ESC 4 [12.5]

Choose a new font size in points, in the example 12.5 points.

ESC 5 [ 
gsave 
newpath 
50 50 moveto 
80 80 lineto 
closepath 
stroke 
grestore 
]

This escape sequence example shows how to include your own PostScript code (e.g. a trademark) during the printing procedure. It is important to store and restore the current position, which is why the program should always start with “gsave” and finish with “grestore”.

ESC 6 [2]

Set line spacing (in this example to 2 times the font height).

8.19.3 Umlauts and special characters

“pstext” provides facilities to allow the PostScript coding (character set translation) of the printer font to be changed, for example to allow national accented characters such as umlauts to be printed correctly. The default character set coding in PostScript only supports a few of the available accented characters. “pstext”, however, re-codes the allocation of such characters by accessing the PostScript language “prep” file that is built into HELIOS Base. This file contains two different, modified versions of the “Standard Encoding Vector”, called “decEncoding” (for DEC Ultrix computers) and “ibmEncoding” (for IBM computers) respectively. Neither of these encoding tables are complete implementations of the corresponding character sets, they have only been set up to support the German umlaut characters. However, they can easily be extended to add other special characters or to specify completely new codings. Note that modification of the coding requires some knowledge of the PostScript language.

To edit the default “prep” file, you have to use the “pstext” program with the -d option. This dumps the “prep” contents into a file which can then be revised. We assume that the file name of the editable “prep” file is “pstext.ps”.

The two alternative encoding tables can be found at the beginning of the “pstext.ps” file. They both function by copying the standard coding and changing it to add the required special characters. The following is the code table provided for the DEC VT200 character set:

% reencode font for DEC VT200 font 
/decEncoding StandardEncoding dup length array copy 
dup 196 /Adieresis put 
dup 228 /adieresis put 
dup 220 /Udieresis put 
dup 252 /udieresis put 
dup 214 /Odieresis put 
dup 246 /odieresis put 
dup 223 /germandbls put 
def

Each line of this table re-defines a single character. The decimal number (e.g. 196) is the decimal value of the character (“ASCII” value) in the input file’s character set. This is followed by the PostScript name of the character. In PostScript, characters have names and not numbers. For example, “/Adieresis” is the PostScript name for “Ä”.

The encoding tables are followed by a line which determines which of the two tables are used when printing. The table “decEncoding” implements a character set according to ISO 8859-1 (DEC VT200) whereas “ibmEncoding” implements a character set that corresponds to the IBM PC extended ASCII code. The following line in “pstext.ps” selects DEC encoding:

% we use the DEC encoding by default 
/theEncoding decEncoding def

If you want to use IBM PC umlaut codes, change the above line as follows:

% we use the IBM encoding by default 
/theEncoding ibmEncoding def

You can as well make a local copy of “pstext.ps” with a new – more individual – name, then modify this file, and specify its name with the -e option when calling “pstext”, e.g.:

$ pstext -e myprep1.ps -P lw testfile

This command prints the file “testfile” using a new PostScript definition contained in the “prep” file “myprep1.ps”.

8.20 start-helios

The “start-helios” command starts all available HELIOS services on the host (see 4.5 “Start/stop HELIOS services manually”).

Usage:

start-helios [-i]

8.20.1 Option

-i

Initialize the HELIOS services during startup. If this option is used, a reinstallation will be done before starting the HELIOS services.

Note:: The -i option will re-setup the HELIOS used Java and Perl versions. It will override any modifications in the HELIOS startup rc scripts and drivers with the original HELIOS versions.

8.21 stop-helios

The “stop-helios” command stops all HELIOS services on a UNIX host 5 minutes after entering the command, on Windows immediately.

Usage:

stop-helios [-g <grace>] [-m <message>] [now]

8.21.1 Options

now: Stops the services immediately.
-g: Allows specifying the time until shutdown in minutes.
-m: Allows issuing a shutdown message.

8.22 uwhat

The “uwhat” command displays the software version number of a HELIOS program.

Usage:

uwhat [-R] [-q] [-e <path>] <file|directory ...>

8.22.1 Options

-R: Search recursively (through all subdirectories) for version numbers.
-q: Quiet option; files without HELIOS version number (or files without access permitted) are not displayed. Can be used in combination with the -R option.
-e <path>: Exclude specified subdirectories from search. Can be used in combination with the -R option. The -e option can be specified, for several paths.

Examples:

Finding out the software version number of “swho”:

$ cd /usr/local/helios
$ bin/uwhat bin/swho 
swho 1.6.14

Or finding out the HELIOS software version numbers in the “/usr/local/helios” directory, while suppressing files without HELIOS version number:

$ cd /usr/local/helios 
$ bin/uwhat -R -q /usr/local/helios 
/usr/local/helios/bin/authutil 1.0.8
/usr/local/helios/bin/dt 4.1.5
...

8.23 lscom

This command lists all HELIOS COM (Common Object Model) plug-ins that have been loaded by the HELIOS server. It helps verify available COM plug-ins and to monitor their status.

Typical plug-ins, which are loaded by the HELIOS server, are:

Unicode conversion plug-ins
Service starter plug-ins

Usage:

lscom [-l]

8.23.1 Option

-l: Displayed plug-ins are additionally loaded. This may be helpful when troubleshooting or error tracking.

8.24 psyslog

This is a tool to list syslog entries. Records will be read from syslog files which are defined in the syslog configuration file. Depending on the platform, the syslog configuration file can be “/etc/syslog.conf”, “/etc/rsyslog.conf”, or “/etc/syslog-ng/syslog-ng.conf”. On Windows, records are read from the Windows Event Log. All records will be mixed to one list so that records appear in chronological order. “psyslog” will print all events since 00:00:00 of the current day unless it is overridden with the -d parameter.

Note:: You must have appropriate access rights to the syslog files. Otherwise “psyslog” will issue an error message on the command line.

Usage:

psyslog [-d <date>][-f][-s]                (print syslog)
psyslog -t <tag> [-p <pid>] message ...    (post to syslog)
psyslog -h                                 (print help)

8.24.1 Options

-d <date>: <date> specifies a date to start listing entries from. Using -d all prints all entries from the beginning.
-f: Causes “psyslog” not to stop when end of syslog file is reached, but to wait for additional data to be appended instead.
-s: Just show the first line of a multiline entry.
-t <tag>: Post a message to syslog and exit. <tag> is used as identifier prefixing the message. Normally the program name is used here.
-p <pid>: Write the given process ID in square brackets behind the tag.
-h: Show this help.

Example 1:

# psyslog -d '13.01.2015 12:00:00'

List all entries in syslog files which are younger than 13 Jan 2015 at 12 p.m.

Example 2:

# psyslog -f

Continuously read syslog entries until “Ctrl-C” is issued. Output contains entries since 00:00:00 of the current day.

Example 3:

# psyslog -d all

Print all entries found in log files.

Example 4:

# psyslog -t myscript.pl Converting of image failed

Post “myscript.pl: Converting of image failed” to syslog.

Note:: On Windows there is no syslog service. Therefore Windows event logging is used.

8.25 htar

“htar” is a HELIOS implementation of a UNIX tar file compatible archive program. It is designed to handle these features:

Unicode UTF-8 file names
Mac resource information
Mac Finder information
Creation date
Restores folder modification date
Supports Windows file streams
Supports backup, archive, read-only and hidden attributes
UNIX file permissions
“Owner”, “Group” and “Others” information

On Windows, additional file streams are used. “dir/file:stream:type” is stored in the archive as “dir/file” and “dir/.rsrc/file:stream:type”. Finder information is converted into the resource format while the creation date is preserved.

: To extract archives using default permissions on Windows, specify both --no-same-owner and --no-same-permissions.

Usage:

htar [-c|-t|-x] [-z|-Z] [-v] [-k] [-m] [-b,-s blocksize] [-C <dir>]
[-f <file>] [<file|dir> ...] 
htar -h

8.25.1 Options

-c, --create

Create archive from the passed files and directories.

-t, --list

List/Test archive. “htar” tests the integrity of the entire archive and listst the contents.

-x, --extract

Extract archive. If additional <file|dir> arguments are passed only those entries in the tar archive are extracted that begin with the same characters as one of the <file|dir> arguments.

-f <file>, --file=<file>

Use tar archive in <file>. If this option is omitted or given as “-”, “htar” reads from standard input (list/extract) or writes to standard output (create).

-v. --verbose

Be more verbose: print file names when creating or extracting an archive, print detailed information on files when testing an archive.

-z, --gzip, --gunzip

Create/read “gzip” compressed tar archive.

-Z, --compress, --uncompress

Create/read “compress” compressed tar archive.

-C <dir>

Change to <dir> before creating/reading an archive.

--exclude=pattern

Exclude files from archive. The pattern can contain the wildcard characters * and ?. Multiple exclude options can be specified.

--newer=DATE-OR-FILE

When creating an archive, only consider files that have been modified since DATE-OR-FILE. “htar” will look at the modification and status change time of files and directories. If DATE-OR-FILE starts with a “/” or “.” (plus “\” or drive letters on Windows) it is taken as a reference file whose modification time specify the date to compare to.

--newer-mtime=DATE-OR-FILE

Similiar to --newer, but only looks at the modification time of files and directories.

--keep-old-files

When extracting do not overwrite existing files.

Note:: On Windows, due to Windows' handling of streams, empty files still get overwritten.

--keep-newer-files

When extracting keep existing files if they are newer than those contained in the archive. On Windows empty files still get overwritten.

--numeric-owner

Always use the uid/gid numbers in the archive, do not look at the user names/group names.

--same-owner

Try to set the ownership of extracted files to that specified in the archive. This mode is the default for the root/Administrator account.

--no-same-owner

Do not try to set the ownership of extracted files to that specified in the archive. This is the default if running under a non-privileged account.

--preserve-permissions, --same-permissions

Set file permission as in archive. This is the default.

--no-same-permissions

Do not use permission information from archive.

-b, --tarblocksize blocks

Change the tar archive read/write blocking factor, the default file I/O is 1 MB blocking factor. Values can be specified in bytes, 512 byte blocks, kilobyte or megabyte blocks, e.g:

-b 1024 (1024 bytes) 
-b 10b  (10*512 byte blocks) 
-b 10k  (10*1024 byte blocks) 
-b 10m  (10*1024*1024 byte blocks)

-s, --fileblocksize blocks

Change the file read/write blocking factor, the default file I/O is 1 MB blocking factor. Values can be specified in bytes, 512 byte blocks, kilobytes or megabytes blocks.

-m, --nomap

Do not memory map files and tar archives.

-k, --keepid

Keep Mac file IDs when extracting. Use this option with caution because the file IDs may conflict with file IDs of existing files on a HELIOS volume and “htar” does not add these IDs to the desktop database.

-h

Display help text.

Note:: Use HELIOS “xtar” to handle HFS Mac files. Details are given at: www.helios.de/web/EN/news/xtar.html

Examples:

Create a gzip compressed archive:

$ htar -c -z -f backup.tgz file1 file2

Extract the above created archive:

$ htar -x -v -z -f backup.tgz

8.26 printerlog

“printerlog” is a tool to list the “printer.acct” files in “HELIOSDIR/var/adm” in a human readable form.

Usage:

printerlog [-p][-v][-a|-1...7]
printerlog [-h]

8.26.1 Options

-p: Repeat printing a headline every 60 entries.
-v: Verbose output of all information recorded.
-N: N can be a value between 1 and 7 which represents the log file “N” days ago.
-a: Print out all files.
-h: Show this help.

Examples:

Print out the current log file with all information:

$ printerlog -v

Print out the log file 4 days ago, writing a headline every 60 entries:

$ printerlog -p -4

8.27 serverlog

“serverlog” is a tool to list the “server.acct” files in “HELIOSDIR/var/adm” in a human readable form.

Usage:

serverlog [-p][-a|-1...7]
serverlog [-h]

8.27.1 Options

-p: Repeat printing a headline every 60 entries.
-N: N can be a value between 1 and 7 which represents the log file “N” days ago.
-a: Print out all files.
-h: Show this help.

Examples:

Print out the current log file:

$ serverlog

Print out the logfile 4 days ago, writing a headline every 60 entries:

$ serverlog -p -4

8.28 HELIOS Windows tools

The following additional tools are available on a HELIOS Base installation on Windows.

Note:: All HELIOS Windows tools are located in “HELIOSDIR\bin”, except for “crontool” which is in “HELIOSDIR\sbin”.

8.28.1 kill

This tool resembles the UNIX “kill” command on Windows machines. It sends a signal to the Windows processes specified by the pid operands.

Usage:

kill [-s signal] pid… 
kill -signal pid… 
kill -l [signal…] 
kill -h help info

The following options can be used with “kill”:

-s <signal>: A symbolic signal name specifying the signal to be sent instead of the default “TERM”.
-signal: A number or a symbolic name specifying the signal to be sent instead of the default “TERM”.
-l [signal…]: If no operand is given, list the signal names. Otherwise, for signal numbers write the signal names and vice versa.

Examples:

`kill -TERM pid`	Shutdown the process
`kill -HUP pid`	Reconfigure the process
`kill -KILL pid`	Kill the process without shutdown

8.28.2 ln

The “ln” tool resembles the UNIX “ln” command on Windows machines and creates a link which points to the original file or a directory.

Usage:

ln [-fsn] <source_file> [<target_file>|<target_dir>]
ln -h for help info

The following options can be used with “ln”:

-f: If the target file exists, “ln” unlinks it first before creating the link.
-s: Creates a symbolic link.
-n: If the target file or the target directory is a symbolic link, do not follow it (useful with -f).
-h: Display help info.

Examples:

Create “data” in the current working directory as a symbolic link to the “F:\data” directory:

$ ln -s F:\data data

Create “myhardlink” as a hard link to “myfile”:

$ ln myfile myhardlink

Note:

Symbolic links created by “ln” use a special HELIOS format and are only recognized by HELIOS processes. Symbolic links are different from the Windows “Shortcuts”.

Hard links created by “ln” are Windows NTFS hard links. They should only be used with extreme care.

8.28.3 dd

HELIOS “dd” is a BSD-compatible “dd” tool which allows creating, copying, and splitting files. It can be used for benchmarking purposes, and emulates “/dev/null” and “/dev/zero”.

: Enter dd -h on a Windows command line to get a usage description for “dd”.

Note:: On Windows, no “dd” tape device functions are supported.

Examples:

Copy file with a block size of 512 bytes:

$ dd if=input_file of=output_file bs=512

Create 100 MB file with 100 blocks of 1024 kB:

$ dd if=/dev/zero bs=1024k count=100 of=output_file

Read 100 MB file with a block size of 1024 kB:

$ dd if=input_file of=/dev/null bs=1024k

8.28.4 crontool

This tool can add scheduled jobs on Windows machines to the Windows “Task Scheduler” window (Administrative Tools > Schedule Tasks). It can start and stop specified programs at midnight.

Usage:

crontool [-H] [-i <task name> <command> [<args>]] [-u <task name>] [-l]

The following options are supported:

-H: Specify an hourly job.
-i: Schedule job to run every day at midnight.
-u: Remove job from the list of scheduled commands.
-l: Print the list of scheduled commands. Another way to print this list is with the Windows “at” command.

Examples:

Schedule “C:\Program Files\My Company\mycronjob.bat” to run hourly:

# crontool -H -i "/C:/Program Files/My Company/mycronjob.bat"

Remove the above job from the list of scheduled commands:

# crontool -u "mycronjob.bat"

Note:: Another way to execute daily jobs is to place a Perl script into the“HELIOSDIR\etc\daily“ folder.

8.29 Windows tools

8.29.1 Windows Sysinternals

There are two tools by Windows Sysinternals that are recommended to monitor HELIOS products on a Windows platform: “Process Monitor” and “Process Explorer”.

For installation and use of the tools, please see the Windows Sysinternals website: technet.microsoft.com/en-us/sysinternals/default.aspx.

Process Explorer

Process Explorer shows a list of the currently active processes, including the names of their owning accounts. Process Explorer also has a powerful search capability that will quickly show which processes have particular handles opened or DLLs loaded.

Process Monitor

Process Monitor is a monitoring tool for Windows that shows real-time file system, Registry and process/thread activity. It combines the features of two legacy Sysinternals utilities, “FileMon” and “RegMon”, and adds an extensive list of enhancements including rich and non-destructive filtering, comprehensive event properties such session IDs and user names, reliable process information, full thread stacks with integrated symbol support for each operation, simultaneous logging to a file, and much more.

8.29.2 Wireshark Network Analyzer

Network Analyzer

Wireshark (formerly known as “Ethereal”) is used by network professionals around the world for troubleshooting analysis, software and protocol development, and education.

For installation and use of the tool, please see the Wireshark website:
www.wireshark.org.

HELIOS Manuals February 6, 2019