HELIOS ImageServer UB User manual

7 Script Server
HELIOS ImageServer includes a Script Server service, which implements a so-called hot folder mechanism. The idea of a hot folder is that, when files are dropped into this folder, a process is automatically started, acting upon the files according to a given script.
Major benefits of the Script Server are:
7.1 Introduction and example
Any folder within a HELIOS volume can act as a hot folder for the Script Server. In the following example, our designated hot folder may be named "for_web". HELIOS provides a variety of sample scripts for different file formats and purposes. The section Example line below shows a line from the sample script "" that the Script Server should call.
Start HELIOS Admin and go to Settings > Script Server Configuration to open the scriptsrv.conf window (Fig. 33).
Fig. 33: scriptsrv.conf window in HELIOS Admin

To access the sample scripts, connect to the HELIOS server and mount the volume "Settings". Then select "" from "Script Server > Samples" and open it in a text editor.

Important: Make sure that the editor does save files with UNIX line feeds ("LF" only). Windows "LF/CR" or Macintosh "CR" compatible editors will not work for this purpose!

Note: The "Settings" volume is write-protected for everybody but "root". If there is the need to extend write access rights to other users, assign proper permissions to the respective subfolders.

In the editor select the default configuration line. Each of the sample scripts contains default configuration lines which we will use in the Script Server configuration file.
Example line
# TIFF,JPEG,EPSF,8BIM,8BPS,PICT,BMP ,PNGf,..CT,PDF :tif,eps,psd,pct,bmp,png,sct,pdf:/demovol/,SCRIPTDEBUG=1
Copy the configuration line from within the editor window.
Append the line(s) which you have copied from the sample script to the end of the configuration file in the HELIOS Admin scriptsrv.conf window. Delete the hash mark (#) in the copied line and replace "/demovol/webjpeg" with the hot folder name and its path.
In our example the folder name is "for_web", and its path is "/images". Fig. 34 shows what the scriptsrv.conf window should look like after the lines have been pasted into the document.
Close the scriptsrv.conf window and save your changes.
Fig. 34: Edited scriptsrv.conf window in HELIOS Admin

As soon as you save your changes your hot folder is working. You can now drop image files into the hot folder. You will notice the new folder "DONE" inside the hot folder. This folder contains the converted JPEG images whose file name automatically has an "N" appended (e.g. "image.tif" becomes "imageN.jpg"), as well as your original images.
A detailed description of the Script Server configuration file, on starting/stopping and refreshing the Script Server process, on the included sample scripts, and on debugging scripts can be found in 7.4 "Configuration".
7.2 Script Server log files
The Script Server log file lists script actions or Script Server processes, with date and time (Fig. 35).
Script Server log files are arranged by date. Every night at midnight the (host) "cron" program starts automatically in the background and renames the log file information of the last seven days. The file "Today" becomes the file "Yesterday", "Yesterday" is renamed into "Two Days Ago", and so on. You can then select, for instance, the server log file of "Three Days Ago". Log files which are older than seven days are deleted automatically.
Select Script Server Log Files from the Lists menu and specify the required day.
Fig. 35: Script Server log file on host "ankh"

Choose Save as- from the File menu to save the complete Script Server log file as a text file.
You can then read this information into a word processor for further use. HELIOS Admin gets its information from the files "HELIOSDIR/var/adm/scriptsrv.log" ("Today") to "HELIOSDIR/var/adm/scriptsrv.6" ("Seven Days Ago"). See 7.3 "Script Server log file structure" below for more information.
7.3 Script Server log file structure
You might be interested in the Script Server log file, e.g. for troubleshooting purposes. It can easily be accessed from within HELIOS Admin.
Each entry in "HELIOSDIR/var/adm/scriptsrv.log" (with the appendices ".0", yesterday to ".6", seven days ago) has the following format:
date time scriptsrv[pid] or script: status

Note: HELIOS Admin does a live update of the displayed Script Server log files (Lists > Script Server Log Files).

7.4 Configuration
"HELIOSDIR/var/conf/scriptsrv.conf" is the main configuration file.
"HELIOSDIR/var/adm/scriptsrv.log" is the log file containing stdout/stderr of all scripts as well as some "scriptsrv" messages.
HELIOS delivers a variety of sample scripts (see also 7.4.3 "Included sample scripts") with the software. They can be accessed after mounting the "Settings" volume.
Access from HELIOS Admin
The Script Server configuration file "scriptsrv.conf" and log file "scriptsrv.log" can be accessed from HELIOS Admin (Settings > Script Server Configuration and Lists > Script Server Log Files).
7.4.1 Starting, stopping and refreshing the Script Server process
The "scriptsrv" process will automatically be started using the "start-helios" and "stop-helios" commands. The status of the "scriptsrv" service can be changed via "srvutil":

Note: The "srvutil" utility can be found in "HELIOSDIR/bin".

Stopping "scriptsrv"
srvutil stop scriptsrv
Stops the "scriptsrv" services, new events will not be processed. All queued events will be processed up to 30 seconds after receiving the stop event. All executed scripts will receive a TERM signal to notify them of the "scriptsrv" service shutdown.
Starting "scriptsrv"
srvutil start scriptsrv
Starts the "scriptsrv" services.
Reconfiguring "scriptsrv"
srvutil reconf scriptsrv
Will update its hot folder configuration from the "scriptsrv.conf" file as well as the preference settings for the "scriptsrv" service. When modifying "scriptsrv.conf" in HELIOS Admin, reconfiguration is automatically done (see Access from HELIOS Admin). Preferences for the "scriptsrv" service are listed and explained in 8.1.6 "Script Server preferences".

Note: If parts of the configuration lines are invalid a detailed error message is written to the system messages file.

7.4.2 The Script Server configuration file
The configuration file "scriptsrv.conf" includes one or more lines to specify the hot folder with its associated scripts to be executed:

Note: A colon is the separator between the fields, so if you use a colon in a field, it must be quoted by a preceding "backslash" character (\:).

Macintosh file type, e.g. EPSF or TIFF. Only files matching this file type will be processed (always 4 characters!). It is possible to specify the file types in a comma-separated list.
Alternatively, you can specify DIRECTORY as keyword to get directory events.
File extension, e.g. "tif". Only files matching this extension will be processed (always "xyz" syntax!). It is possible to specify the extensions in a comma-separated list.
Watched folder
All files in this folder - and its subfolders - will be processed.
A host shell script or a Perl script to be called to process a file. The first argument of this script is a file name, additional parameters will be passed via environment variables. Read-only sample scripts can be found in
"HELIOSDIR/var/settings/Script Server/Samples". Customized scripts should be saved to
"HELIOSDIR/var/settings/Script Server" in order to allow migration to the different server platforms. The Perl script should rececive the extension ".pl" , e.g.

Note: Alternatively, paths to customized scripts can be stated either absolute or relative in respect to "HELIOSDIR".

User ID
The host user name under which the script is executed, e.g. "root", "demouser", etc.. If not specified, the user "root" is used.
Environment variables
A list of comma-separated environment variables can be specified to be passed to the script, e.g. PRINTER=Laser,SCRIPTDEBUG=1. This allows having a general purpose script to be used with different parameters.
SCRIPT_TIMEOUT If set, it overrides the global preference RunTime (see 8.1.6 "Script Server preferences").
SCRIPT_OLDNAME Is set by the server and can be evaluated in the script containing the old name, if the event is move or dirmove.
SCRIPT_EVENT Is set by the server. Available events are close, move, dircreate, and dirmove.
# HELIOS Script Server configuration file
# Lines in this file have the form
# type:extension:dirpath:script:scriptuser:scriptenv
# type is the Macintosh Type, e.g. TIFF or a list
# of Types like TIFF,JPEG.
# extension is the Windows extension, e.g. .tif or a
# list of extensions like tif,jpg.
# if type and extension are empty, any file
# is monitored if type contains the keyword
# DIRECTORY, suffix is ignored and directory
# events are monitored
# dirpath is the full path of the hot folder to be
# watched and acted upon
# script is the program to be called for the hot
# folder, e.g. scriptname or
# /path/to/scriptname. If 'script' is not a
# fully specified path (starting with /), it
# is searched in HELIOSDIR and in
# "HELIOSDIR/var/settings/Script Server".
# It is recommended that you save all scripts
# in "HELIOSDIR/var/settings/Script Server".
# scriptuser is the user under which the script is
# getting called, e.g. root.
# if user is empty, script is executed as
# same user as the server is running
# scriptenv is a comma separated list of key=value
# items which are exported as environment
# variables for the script.
# SCRIPT_TIMEOUT specifies the maximum
# runtime, 0 means forever
# The default SCRIPT_TIMEOUT is set when no
# environment is set explicitely
# SCRIPT_EVENT is set by the server and
# contains a value like close, move,
# dircreate or dirmove
# SCRIPT_OLDNAME contains the old filename
# after a move or dirmove
# The fields are separated by colons. Colons
# used within a field must be quoted with a
# backslash (\:).
#PDF :pdf:/
#Wildcard registration for all file types/extensions:
7.4.3 Included sample scripts
We provide the following sample scripts for the Script Server functionality with our software (each sample script is listed with the respective configuration lines for the entry in "scriptsrv.conf"). Note that in the following examples "out" is used for the OUTDIR parameter:
Print PostScript files to a specified printer:
Print text files to a specified printer:

Note: The following five scripts require that PDF HandShake be installed on the same host:
Analyze and preflight PDF files:
PDF :pdf:/inspectPDFHotFolder:/usr/local/helios/etc/callas/scripts/,PROOFPROFILE=/usr/local/helios/callas/Profiles/test.profile,SCRIPTDEBUG=0
Replace OPI images and forms in PDF documents:
PDF :pdf:/demovol/,ERRDIR=
Print a PDF file to a specified PostScript printer:
PDF :pdf:/demovol/,SCRIPTDEBUG=1
Split a PDF file into single pages and move final PDF files into a directory specified in the OUTDIR parameter:
PDF :pdf:/demovol/,SCRIPTDEBUG=1
Convert a PDF page to an EPSF file and move final EPSF files into a directory specified in the OUTDIR parameter:
PDF :pdf:/demovol/,SCRIPTDEBUG=1

Note: In the following scripts, image conversion of PDF files does require PDF HandShake.
Convert all supported ImageServer file types into TIFF CIE-Lab and move converted files to OUTDIR:
PDF ,-:pdf,-:/demovol/,SCRIPTDEBUG=1

Note: For space reasons, the above line appears abbreviated. All image file formats that are supported by ImageServer are valid.
Generate a 128x128 pixel Internet PNG file and move final PNG file into a directory specified in OUTDIR. All colors (including spot colors) are converted to RGB:
PDF ,-:pdf,-:/demovol/,SCRIPTDEBUG=1

Note: For space reasons, the above line appears abbreviated. All image file formats that are supported by ImageServer are valid.
Generate a 128x128 pixel Internet JPEG file and move final JPEG files into a directory specified in OUTDIR. All colors (including spot colors) are converted to RGB:
PDF ,-:pdf,-:/demovol/,SCRIPTDEBUG=1

Note: For space reasons, the above line appears abbreviated. All image file formats that are supported by ImageServer are valid.

7.4.4 HELIOS default scripts location
We recommend to copy all scripts into the "Script Server" directory in the "Settings" volume. The benefits of the HELIOS default script location are:
7.4.5 Script Server service port
The Script Server service port is 2024.
Issue the command socket localhost 2024, type help for the command overview and quit to leave.

Note: By default, the Script Server service port can only be reached from localhost. See RemoteAccess in 8.1.6 "Script Server preferences".

Show validated and active configuration lines and statistics:
Hold How many jobs are queued for this script
Run How many jobs are currently running
Done How man jobs are done by this script
# /usr/local/helios/bin/socket localhost 2024
Welcome to the HELIOS Script Server service port
Config of scriptsrv
Hold time: 9, Default script timeout: 120
Total jobs done: 1
Hold Run Done Ftype:Suffix:Path:Script:User:Environment
   0   0    1 JPG :jpg:/
   0   0    0 DIRECTORY::/Volumes/MacOSX2/
Additional global information:
This can be used to debug/watch if the script is working correctly (statistics).
Show status of current jobs queued for processing in the hold, run and termination syntax:
h File scriptname user
t File scriptname user
r File scriptname user status
Status field is filled by script writing Status:- to "stdout" or "stderr", see also 7.5.2 "Status (shown on service port 2024)".
7.5 Developing and debugging scripts
Script Server is started automatically by the Service Controller. Please make sure via "srvutil status" that the "scriptsrv" service is running and there are no error messages in the system messages file.
All valid registrations for different scripts are displayed via port 2024.
Every time a custom script is called, the "scriptsrv.log" file contains a information similar to the following:
29.07.2005 18:00:07 scriptsrv [1747]: Create process[1854] job added by tim
29.07.2005 18:00:17 scriptsrv [1747]: Process[1854] done
All standard output, as well as error output of the script is automatically redirected into the "scriptsrv.log" file. Each line is prefixed by time stamp and script name.
7.5.1 Script parameters
Scripts are called with the file name as the first argument, e.g. a host shell script will contain the file name in $1, a Perl script will contain it in $ARGV[0].
Additional parameters are provided via the environment variables:
Additional custom parameters can be specified in the "scriptsrv.conf" file as the last argument of each configuration line, e.g. SCRIPTDEBUG=1,PRINTER=lw. The custom environment will be available as environment variables in the script. This allows developing one script and using it for different hot folders by using different parameters (e.g. printer, ICC profiles, color spaces, etc.).
7.5.2 Status (shown on service port 2024)
Script output starting with Status: is not written to "scriptsrv.log" but displayed in the "showq" command output on service port 2024. Intention: if a job takes long time to finish, the script can tell the user (who is monitoring the process on the service port) what is actually done by the script.
7.5.3 Debugging scripts stand-alone (without Script Server)
It is a good idea to test your scripts first manually in a host terminal session to verify that they work. The Script Server calls all scripts with the current directory set to the HELIOS product directory. Therefore it is required that you first change into the HELIOSDIR before executing a script manually.
Calling a stand-alone script manually, e.g. the "" script, using a bash or Bourne shell:
cd /usr/local/helios
chmod +x var/settings/Script Server/
export HELIOSDIR="/usr/local/helios"
export PRINTER="lw"
export SCRIPT_EVENT=close
var/scripts/printps "/data/demovol/TestFolder/"
If this produces error messages or the script does not do what it is expected to do, it needs to be solved before using it in the automatically event-driven Script Server.
Calling standalone scripts allows debugging, using the Perl debugger or a host debugger for C/C++ applications. Simple debugging by printing messages will work as well within the automated Script Server environment. All script output will later automatically be redirected into the "scriptsrv.log" file.

Note: Every HELIOS Perl sample contains the following file magic:

#!var/run/runperl -w
This means the script is executable just by calling it. It always needs to be called from the HELIOS directory (e.g. "/usr/local/helios"), otherwise "var/run/runperl" cannot be found. The file "runperl" will be a symbolic link to your Perl runtime, e.g. "/usr/bin/perl" on Mac OS X or Linux systems.
Whenever "start-helios" is issued, the "runperl" link will automatically be created. This might be helpful if Perl is installed at a later time (no changes in scripts required).
An alternative option to test your scripts in a different directory is to create the runperl link in your script directory.
Example (e.g. on Mac OS X or Linux):
cd /home/myhome
mkdir -p var/run
ln -s /usr/bin/perl var/run/runperl
7.5.4 Debugging scripts in the Script Server environment
To inspect "holdQueue" and "runQueue", and the configuration of the running "scriptsrv" daemon, connect to service port 2024, and use "showq" for inspecting the queue and "showconf" for inspecting the configuration.
If the configuration line is not displayed this may be due to a syntax error. Detailed error messages are written to the system messages.
If a job matches more than one configuration line, the first matching configuration line is considered.
To switch on the script debug variable SCRIPTDEBUG it is required to set the value to 1 either in the configuration file. You may also set the global debug preference scriptdebug:
prefvalue -k Programs/scriptsrv/scriptdebug -t int 1
Delete the scriptdebug preference via:
prefvalue -k Programs/scriptsrv/scriptdebug -d
Find a description of the "prefvalue" program in the Base manual.

Important: The global preference scriptdebug activates debugging for all scripts. Thus, we do not recommend to turn on the debug preference for production servers because it will produce heavy load on the server and can cause significant slow-down of the server!

7.6 Additional considerations
You should restrict the registered types/extensions and directories to those that are really processed by your scripts, so that the communication and processing overhead does not become too large.
When using scripts for layout generation (with "layout" in normal or convert mode) you should deactivate automatic layout generation for the hot folder, or the complete volume in which the hot folder resides.

© 2005 HELIOS Software GmbH