Vous êtes sur la page 1sur 650

Columbus OM

Installation and Configuration

5.000

Publication number

Trademark acknowledgements

UQCO-5000-01 (September 2012)

The following is a trademark of Macro 4 Limited or of


UNICOM Global: Columbus OM.

Information in this publication is subject to change.


Changes will be published in new editions or technical
newsletters.

Documentation set
This is the only manual for this product.

Copyright notice
Columbus OM (the Programs and associated materials) is a
proprietary product of Macro 4 Limited a division of
UNICOM Global. The Programs have been provided
pursuant to License Agreement containing restrictions on
their use. The programs and associated materials contain
valuable trade secrets and proprietary information of
Macro 4 Limited and are protected by United States Federal
and non-United States copyright laws. The Programs and
associated materials may not be reproduced, copied,
changed, stored, disclosed to third parties, and distributed in
any form or media (including but not limited to copies on
magnetic media) without the express prior written permission
of Macro 4 Limited, The Orangery, Turners Hill Road,
Worth, Crawley, West Sussex, RH10 4SS, U.K.

Columbus OM
Copyright 1995-2012 All Rights Reserved. Macro 4
Limited a division of UNICOM Global.
No part of this Program may be reproduced in any form or
by electronic means, including the use of information storage
and retrieval systems, without the express prior written
consent and authorization of Macro 4 Limited.
No part of this manual may be reproduced or transmitted
in any form or by any means, electronic or mechanical,
without prior written permission from Macro 4 Limited.

Disclaimer
We cannot guarantee freedom from, or assume any
responsibility or liability for technical inaccuracies or
typographical errors. The information herein is furnished
for informational use only and should not be construed as a
commitment by Macro 4 Limited a division of UNICOM
Global.

SAP and R/3 are trademarks or registered trademarks of


SAP AG in Germany and in several other countries.
Product and company names mentioned herein may be the
trademarks or registered trademarks of their respective
owners.

Contents

Columbus OM Installation and Configuration UQCO-5000-01

About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9


Conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
New features in Columbus OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Chapter 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Overview of a Columbus OM output management environment . . . . . . . . . . . . 16
Configuration functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Chapter 2 Installing Columbus OM . . . . . . . . . . . . . . . . . . . . . . . 23


Preparing to install Columbus OM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Installing Columbus OM (Windows) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Installing a Columbus Intelligent Office Printing (IOP) deployment . . . . . . . . . . 37
Installing Columbus OM (UNIX). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Configuring Columbus OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Starting Columbus OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Using Columbus OM in a VMWare environment . . . . . . . . . . . . . . . . . . . . . . . . 50
Upgrading Columbus OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Uninstalling Columbus OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53

Chapter 3 Columbus OM utilities . . . . . . . . . . . . . . . . . . . . . . . . . 55


Columbus OM Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
IOP Universal Driver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Columbus Windows Gateway. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
IOP Messenger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
IOP desktop components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Columbus OM PC Printer Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Columbus OM Novell Gateway . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

COLUMBUS OM INSTALLATION AND CONFIGURATION

CONTENTS

Chapter 4 Managing servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95


Server types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Adding servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Configuring servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Starting servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Stopping servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Monitoring servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104

Chapter 5 Configuring a Columbus OM printing environment . . . 107


Setting parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
Configuration for local printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Configuration for distributed printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Chapter 6 Setting up printers . . . . . . . . . . . . . . . . . . . . . . . . . . . 129


Adding printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Changing the properties of printers from the command line . . . . . . . . . . . . . . . 145
Managing print servers from the command line . . . . . . . . . . . . . . . . . . . . . . . . . 146
Managing printer servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Defining printer types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Defining paper types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
Creating printer classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
Creating printer groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Chapter 7 Configuring the printer features . . . . . . . . . . . . . . . . . 163


Configuring the printer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Controlling the documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Supported document formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Applying overlays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Printing banner pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Formatting documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Assured delivery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
Handling documents that fail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Processing documents in batches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183

Chapter 8 Using the xprinter driver . . . . . . . . . . . . . . . . . . . . . . 185


Devices supported by xprinter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Configuring a printer to use the xprinter driver . . . . . . . . . . . . . . . . . . . . . . . . . 188
xprinter delivery modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189
Banner pages for xprinter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192
Monitoring entries submitted to xprinter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Example configurations for xprinter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

COLUMBUS OM INSTALLATION AND CONFIGURATION

CONTENTS

Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 202

Chapter 9 Adding entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211


Adding entries by using Columbus OM Explorer . . . . . . . . . . . . . . . . . . . . . . . . 212
Adding entries from the command line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Intercepting the lp and lpstat commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224
Converting lpr/lpd requests to Columbus OM print entries . . . . . . . . . . . . . . . . 227
Transferring documents from other hosts into Columbus OM . . . . . . . . . . . . . . 232
Processing files in scanned folders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

Chapter 10 Managing entries. . . . . . . . . . . . . . . . . . . . . . . . . . . . 241


Displaying entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
Changing entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
Resubmitting documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Restarting documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Deleting entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264

Chapter 11 Managing queues . . . . . . . . . . . . . . . . . . . . . . . . . . . 265


Displaying the queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Increasing the capacity of the queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267
Reducing the capacity of queues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Maintaining queue integrity and efficiency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
Indexing queues. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
Controlling the entry numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273
Controlling what documents are put in the queues . . . . . . . . . . . . . . . . . . . . . . . 274
Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275

Chapter 12 Controlling Columbus OM with the dispatch server . . 279


Configuring a dispatch server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
Creating rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
Rule format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
Selecting documents using a condition. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Specifying the actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Monitoring the status of dispatch entries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308
Example rules using the dispatch server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
Reference section. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 320

Chapter 13 Archiving documents. . . . . . . . . . . . . . . . . . . . . . . . . 335


Maintaining an archive queue of completed entries . . . . . . . . . . . . . . . . . . . . . . 336
Transferring documents to Columbus DW . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341
Transferring documents to other archiving applications . . . . . . . . . . . . . . . . . . . 348

COLUMBUS OM INSTALLATION AND CONFIGURATION

CONTENTS

Chapter 14 Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351


Access to the Columbus OM instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353
Access to Columbus OM features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
Access to administration functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
Access to documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369
Access to printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
Additional security features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
Reference section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 382

Chapter 15 Working with multiple instances . . . . . . . . . . . . . . . . 387


Configuring the network communications. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388
Enabling instances to work together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Copying and deleting files in multiple instances . . . . . . . . . . . . . . . . . . . . . . . . . 390
Communicating with remote instances on different ports . . . . . . . . . . . . . . . . . 398
Accepting users from remote hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Chapter 16 Monitoring the system . . . . . . . . . . . . . . . . . . . . . . . . 405


Getting status information from printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 406
Operating system actions during processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417
Writing journal information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418
Log files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Recording information about events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 421
Monitoring the system: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

Chapter 17 Processing email messages . . . . . . . . . . . . . . . . . . . . 445


Configuring Columbus OM to send email messages . . . . . . . . . . . . . . . . . . . . . 446
Processing incoming email messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451
Processing email messages: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

Chapter 18 Configuring a fax environment . . . . . . . . . . . . . . . . . . 463


Configuring Columbus OM to send faxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
Sending fax documents. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476
Receiving faxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480
Configuring a fax environment: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483

Chapter 19 Intelligent Office Printing (IOP) . . . . . . . . . . . . . . . . . 495


Introduction to Intelligent Office Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496
Configuring the IOP deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 500
Accessing the IOP administration features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501
Working with zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502
Working with printers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506
Working with printers for OnCall printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509
Working with quota-based scanning: Scan2Print . . . . . . . . . . . . . . . . . . . . . . . . 514

COLUMBUS OM INSTALLATION AND CONFIGURATION

CONTENTS

Managing users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 515


Working with enforcements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517
Working with diversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519
Managing Columbus OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521
Printing documents in an IOP deployment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524
Pull printing with SecureJet printers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Printer code mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529
Intelligent Office Printing (IOP): Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 534

Chapter 20 Integrating Columbus OM with SAP R/3 . . . . . . . . . . 539


Columbus OM in a SAP R/3 environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Configuring SAP R/3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Configuring Columbus OM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550
Integration with SAP R/3: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553

Chapter 21 Integrating other applications . . . . . . . . . . . . . . . . . 571


Integration with Columbus Accounting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 572
Integration with ColumbusZ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577
Integration with formatter applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 580
User Program Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583
Integrating with other applications: Reference . . . . . . . . . . . . . . . . . . . . . . . . . . 598

Chapter 22 Parameters, variables and attributes . . . . . . . . . . . . 601


Common parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 602
Substitution variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603
User variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613

COLUMBUS OM INSTALLATION AND CONFIGURATION

CONTENTS

COLUMBUS OM INSTALLATION AND CONFIGURATION

About this manual

Installation and Configuration UQCO-5000-01

This manual explains how to install, configure and maintain a Columbus OM


system.

COLUMBUS OM INSTALLATION AND CONFIGURATION

10

About this manual

Conventions

Conventions
The following typographic conventions are used:
boldface

Indicates a command or keyword that you should type, exactly


as shown.

italics

Indicates a variable for which you should substitute an


appropriate value.

monotype

Indicates literal input and output.

Ctrl+D

Indicates two or more keys pressed simultaneously.

Brackets surround an optional value.

Vertical bars separate alternative values from which you must


make a selection.

...

An ellipsis indicates that the preceding element may be


repeated.

Files, folders and environment variables


References to files, folders and environment variables use the Windows
conventions, for example: the %UNIQDIR%\config folder. On UNIX, this is
equivalent to: the $UNIQDIR/config directory.
uniq and uq
Terms that include uniq and uq, such as the $UNIQDIR environment variable
and the uqserver program, derive from the previous name of Columbus OM:
UniqPrint. These terms are still valid for Columbus OM.

COLUMBUS OM INSTALLATION AND CONFIGURATION

About this manual

New features in Columbus OM

New features in Columbus OM


Columbus OM 5.000

Support for quota-based scanning and printing. For more information, see
Working with quota-based scanning: Scan2Print on page 514.

Improved IOP web interface.

Support for IPv6 addresses.

Columbus OM 4.930

Columbus OM supports PCL 6.

xmessage supports newline characters in message texts. See Sending messages

using IOP Messenger on page 72.

The filein server can process files either in the order in which they were put
in the scanned folder, or in alphabetic order. See the Directory_Read_Order
parameter on page 235.
Print indexing can be turned off by setting the PCL_Converter system
parameter to NONE. See page 239.
req command: Entries for deletion can be selected by their status. See
page 260.

Event monitoring: New events record when queues are automatically purged,
extended and archived (see page 433); and when printers are started, stopped
and initiated (see page 434). New parameters for evserver control when
events are written to a logfile: see Flush_Filter and Flush_Logfile on
page 438.
uqsfcache: Remote_User parameter specifies a userid on a remote computer
that Columbus OM is to send feedback to. See page 443.

IOP: OnCall_Rls_Medium parameter specifies a medium to be applied to


entries when they are released. See page 534.
xnacc_get_acct command: Get records from a device and then delete them
(-gap parameter); and specify a timeout period (-t parameter). See page 574.
xnacc_purge command: Specify a timeout period (-t parameter). See

page 576.

xmlserver parameters: Action_Frequency, Action_On_SQLError,


Cache_SQL, and Timeout. See page 598.

Columbus OM 4.920

Support for partial PCL5 printing.

Improved feedback mechanism when integrating with Columbus DW. For


more information, see Tracking the progress of documents that have been
archived on page 343.

Ability to send information from Xerox devices that support network


accounting to Columbus Accounting.

COLUMBUS OM INSTALLATION AND CONFIGURATION

11

12

About this manual

New features in Columbus OM

Columbus OM 4.915

Combined installation program for Columbus OM for IOP, the Columbus IOP
web interface, and Columbus Accounting. For more information, see Installing
a Columbus Intelligent Office Printing (IOP) deployment on page 37.

Columbus OM 4.910

Intelligent Office Printing features select most suitable devices for printing
documents, based on document properties and user authorisation, with options
to divert to other devices or enforce special requirements. For more
information, see Intelligent Office Printing (IOP) on page 495.

Combined installation program installs all the IOP desktop components


(Columbus Windows Gateway, IOP Messenger and IOP Universal Driver) at
once, without user interaction. For more information, see IOP desktop
components on page 78.

Columbus OM 4.900

The file-locking system to prevent two users accessing a file at the same time
has been supplemented by a faster and more reliable method that provides
more effective support for multi-processor computers.
On Windows, mutexes are used. On UNIX, semaphores are used. The method
used is specified by the ULM_Method parameter in the default.tab file.

xprinter supports the Internet Printing Protocol (IPP). For more information,

see Configuring IPP printers on page 200.

A single Columbus OM password file can now be shared by multiple instances.


You can maintain the password file on one instance, and then on other
instances, use the csupwd -Redirect command to use that password file. For
more information, see page 358.
uqserver timeouts for packages and clients can now be configured separately.
For more information, see the UQ_Timeout parameter in the default.tab file

(spage 400).

The dispatch server can now handle acknowledgements (ACK/NAKs) from


other servers. For more information, see the dispatch servers Process_Acks
parameter (page 321).

A printers connection parameters can be more finely specified: the values for
the Connect_Delay, Disconnect_Delay and Connect_Interval parameters
can be specified in milliseconds (instead of seconds) by adding M after the
value.

The uqsfcache server can make a copy of its cache file before processing it,
ensuring that statuses are not lost if the server stops abnormally. For more
information, see the servers Backup_Cache parameter (page 442).
You can control whether the dispatch server counts the pages and lines in a
bundle of documents. For more information, see the servers
Count_Bundle_Pages parameter (page 320).
Errors that occur in the status feedback reporting system can be recorded in a
logfile. For more information, see the Log_SFB_Errors system default
parameter (page 437).

COLUMBUS OM INSTALLATION AND CONFIGURATION

About this manual

New features in Columbus OM

IOP Universal Driver: There is more control over which options in a printers
Properties dialog box are available, and the text in the dialog box can be
edited. Oncall printers can be configured at installation time or by using the
Properties dialog box. For more information, see Configuring the IOP
Universal Driver on page 59.

COLUMBUS OM INSTALLATION AND CONFIGURATION

13

14

About this manual

New features in Columbus OM

COLUMBUS OM INSTALLATION AND CONFIGURATION

15

CHAPTER 1

Chapter 1

Introduction

This chapter provides an overview of the configuration features that enable you to
set up Columbus OM so that it can be used for printing documents and sending
faxes. These features include:

setting up the network communications that enable users to access


Columbus OM, and instances of Columbus OM to access other instances

administering the document queues that enable users to process, track and
archive documents

configuring a printing environment, including how to set up printers so that


they can be used and controlled by the Columbus OM print facility, and also
how to manage documents using the Columbus OM dispatch facility

configuring a fax environment for sending and receiving faxes by using the
Columbus OM fax facility

controlling access to documents and Columbus OM by using the security


features

setting up Columbus OM for end-users

monitoring the use of Columbus OM with audit trails, log files and archives

integrating Columbus OM with other applications.

COLUMBUS OM INSTALLATION AND CONFIGURATION

16

CHAPTER 1

Introduction

Overview of a Columbus OM output management environment

Overview of a Columbus OM output management


environment
This section briefly describes how a Columbus OM output management
environment works, and shows the components that you have to configure.
Users select the documents that they want to print or fax by using Columbus OM
Explorer on their PC. Columbus OM Explorer transfers the documents to a
Columbus OM print or fax instance on a host computer. (An instance is an installed
copy of any Columbus OM product.) Documents can also added to an instance by
using the command line, or directly from another application (for example,
ColumbusZ or a SAP system).
Then the instance transfers the documents to a printer or fax modem as
appropriate. The printer or fax modem sends status information back to the
instance, and the instance sends the status information back to Columbus OM
Explorer, so that users can track the progress of their documents.

Columbus OM
Explorer

document
status

Columbus OM
instance

document
status

printer or
fax modem

There may be several Columbus OM instances on the same host: either different
Columbus OM products or copies of the same product, configured differently.
Each instance usually controls several printers or fax modems.

Columbus OM
Explorer

Columbus OM
print instance A

printers

Columbus OM
print instance B

printers

Columbus OM
fax instance C

fax modems

In a Columbus OM print system, there may be several hosts with print instances.
Users may be able to access each instance directly or they may access one instance
which in turn accesses another instance.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 1

Introduction

Columbus OM
Explorer

Overview of a Columbus OM output management environment

Columbus OM
instance A

Columbus OM
instance B

printer or
fax modem

For greater control over the use of a Columbus OM print system, you can use the
Columbus OM dispatch features. You can specify rules to select documents
according to their attributes (for example, the owner or the destination) or their
contents, and then process them differently. For example, documents sent to a
printer that has been taken offline for maintenance can be automatically redirected
to another printer.

Columbus OM
Explorer

Columbus OM
Dispatch

Columbus OM
Print

printer or
fax modem

The dispatch functionality can be provided either by the dispatch server that is
contained within the Columbus OM print instance or by a separately installed
Columbus OM dispatch instance.
For more information, see Controlling Columbus OM with the dispatch server on
page 279.

COLUMBUS OM INSTALLATION AND CONFIGURATION

17

18

CHAPTER 1

Introduction

Configuration functions

Configuration functions
This section briefly describes the areas that have to be configured to create a
Columbus OM system.

Network communications
The network communications enable the components of a Columbus OM system
to communicate with each other. They enable Columbus OM Explorer on a PC to
communicate with a Columbus OM instance on a host computer, and a
Columbus OM instance to communicate with other Columbus OM instances.
For the network communications to work, you have to choose a port number that
Columbus OM uses, and you must use the same port number on every computer
within the Columbus OM system.

Queue maintenance
All the documents that you send to a Columbus OM instance are stored in a queue:

The pending queue contains documents that are waiting to be processed. When
you add an entry, it first goes in the pending queue.

The completed queue contains documents that have been processed (either
successfully or unsuccessfully). Columbus OM automatically moves the
documents from the pending queue to the completed queue when it has
processed them.

The archive queue contains documents that have been moved from the
completed queue and that you want to store for future reference.

Columbus OM
Explorer

Columbus OM
pending queue

Columbus OM
completed queue

Columbus OM
archive queue

Every instance has its own pending queue and a completed queue. The archive is
optional: after documents have been in the completed queue, you can either store
them in the archive or discard them. If you want to use the archive queue, you have
to create it yourself.
The initial size of the pending and completed queue are set when you install the
Columbus OM instance. To make sure that there is enough space to hold all the
documents that users want to add, you can either increase the size of the queues or
delete old entries. Both of these can be done either manually, or automatically
when needed.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 1

Introduction

Configuration functions

At regular intervals, you must also check the integrity of the queue, and fix it if
necessary. This can also be done either manually or automatically.

Configuring a print environment


This section describes the different print environments that you can set up. Most
installations use a combination of these environments.
Local printing
Local printing enables users to print documents on printers that are controlled by
the instance to which they are connected. The printer can be directly attached to
the host; on the network; attached to a PC that is running the Columbus OM PC
Printer Channel; or connected by a modem.

printers on
network

Columbus OM
Explorer

Columbus OM
print instance

Columbus OM
PC Printer
Channel

printers
attached to PC

printers
attached to host

accessed by
modem

To set up local printing, you have to provide information about how the printers
are connected.
Local printing is controlled by one of Columbus OMs servers called
printmaster. The printmaster server is configured for you when you install

Columbus OM. However, you might need to change its configuration to meet the
requirements of your site.
Distributed printing
Distributed printing enables users to print document on printers that are controlled
by Columbus OM instances other than the one to which they are connected. These
printers are known as remote printers.

Columbus OM
Explorer

COLUMBUS OM INSTALLATION AND CONFIGURATION

HOST A
Columbus OM

HOST B
Columbus OM

printer

19

20

CHAPTER 1

Introduction

Configuration functions

In this example, the printer is controlled by the Columbus OM print instance that
is on Host B. The printer is in Host Bs local printing environment. On Host A, the
same printer is set up as a remote printer. This enables users who can connect only
to Host A to use the printer.
To set up a distributed print environment, you need to create a list of the remote
printers that you want users to have access to. Distributed printing is controlled by
the netmaster server. Like printmaster, netmaster is configured for you when
you install Columbus OM.
Converting lp requests into Columbus OM requests
Columbus OM can intercept print requests that users make using the standard
UNIX lp command, and add those requests to its own queue.
Transferring documents from other hosts to Columbus OM
Users who do not have direct access to a Columbus OM instance can still add
entries to its queue, if they can transfer files to the host that the instance is on.

Setting up printers
For each printer that you want to use with Columbus OM, you have to set up a
printer server to control it. Setting up a printer server includes specifying the
connection to the printer (for example, whether it is connected to the host, by the
network or by a modem) and its type (for example, PCL or PostScript).
Document processing
Additional features enable documents to be processed before they are printed. For
example, banner pages can be added to ensure consistent output, and documents
can be converted into different formats (for example, from PCL to PostScript),
enabling you to make better use of the printers available.

Configuring a fax environment


Within Columbus OM, a fax environment works in a similar way to a print
environment. It receives documents from users PCs and puts them into its pending
queue which is monitored by fax servers. You have to set up one fax server for each
fax modem that you want to use with Columbus OM. When a fax server finds an
entry in the queue that it can process, it sends the document to the fax modem that
it controls.
Additional features such as coversheets and overlays help to maintain the corporate
image, and for security or archiving, confirmation copies of all documents sent can
be automatically printed.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 1

Introduction

Configuration functions

System security
Essential to every Columbus OM system is maintaining security: ensuring that
users can modify, view and delete only the documents that are appropriate to their
responsibilities, and also ensuring that only authorized users have access to the
Columbus OM configuration functions.

Access to documents in the queue is controlled by user groups and printer


groups. To modify, view or delete the documents that belong to someone else,
you have to be in the same user group. To use a specific printer, you must have
access to the printer group that it is in. As part of the configuration of
Columbus OM, you have to create user groups and printer groups and add
users to them.

Access to the configuration functions is also controlled by user groups, three of


which are already set up for you. Each group has access to a different set of
functions, representing different levels of responsibilities, from only the
day-to-day configuration functions, to all the functions. You have to decide
which users need access to which configuration functions and then add them to
the appropriate group. For more flexibility, you can create more groups and
choose which configuration functions members of those groups can access.

Setting up for end users


When the output management environment has been set up, Columbus OM is
available for users to print documents and send faxes. These tasks can be
performed with any of the interfaces that Columbus OM provides:

For PC users, Columbus OM Explorer provides a familiar Windows interface


for easy access to document management commands to add entries to the
queue and to track and monitor their progress. Users can find everything that
they need to know about Columbus OM Explorer.

Advanced users and administrators might prefer the command line interface to
Columbus OM, available for both Windows and UNIX.

Just before users are given access to these interfaces, the administrator might want
to customize how they work. For example, there are several default values that can
be set in advance to make it faster and easier for users to add entries.

Monitoring the system


Columbus OM includes extensive features for monitoring its use. Both users and
administrators can check the status of printers and fax servers and the progress of
documents through the system. (Security features can be set up to ensure that users
can only see documents that are relevant to themselves.) Administrators also have
access to the extensive and customizable audit trails and log files for checking the
progress of documents, and the use of printers, servers and queue maintenance
functions.

Integration with other systems


Columbus OM can be integrated with other systems, including Columbus DW
(Macro 4s document warehousing application), ColumbusZ (Macro 4s output
management system for mainframes), and SAP R/3.

COLUMBUS OM INSTALLATION AND CONFIGURATION

21

22

CHAPTER 1

Introduction

Configuration functions

COLUMBUS OM INSTALLATION AND CONFIGURATION

23

CHAPTER 2

Chapter 2

Installing Columbus OM

This section describes how to install Columbus OM.


For information about

See

what to do before installing


Columbus OM

Preparing to install Columbus OM on


page 24

installing Columbus OM

Installing Columbus OM (Windows)


on page 35 or Installing Columbus OM
(UNIX) on page 41

installing a Columbus OM IOP


deployment

Installing a Columbus Intelligent Office


Printing (IOP) deployment on page 37

what to do after installing


Columbus OM

Configuring Columbus OM on
page 42

starting Columbus OM

Starting Columbus OM on page 48

using Columbus OM in a VMWare


environment

Using Columbus OM in a VMWare


environment on page 50

upgrading Columbus OM

Upgrading Columbus OM on page 51

uninstalling Columbus OM

Uninstalling Columbus OM on
page 52

COLUMBUS OM INSTALLATION AND CONFIGURATION

24

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Preparing to install Columbus OM


This section describes what to do before installing Columbus OM. Use this section
with the Checklist on page 33.
Step

Description

See

Make sure that your license information for Columbus OM is


accessible

page 24

Check the port numbers that Columbus OM uses

page 26

Create an operating system user (and on UNIX, a user group) to page 27


own and control the Columbus OM programs

Choose the folder in which you want to install Columbus OM

(UNIX only.) If you are installing two or more instances on the page 29
same computer, and you want the instances to share some of the
Columbus OM programs, choose a common directory

(UNIX only.) Make sure that the X-Server with Virtual Frames
Buffer is installed

page 28

page 29

Licensing
Columbus OM is licensed by Macro 4 to run on a specified computer for a
specified period of time. A license is provided either in a license file or as a set of
license keys.

Using a license
file

If you have a license file, see Using a license file below.

If you have a set of license keys, see Using a set of license keys on page 25.

If your license is in the form of a license file, it is validated by the Columbus


License Manager program. The License Manager is installed when you install
Columbus OM itself. The License Manager must be running whenever
Columbus OM is running.
Installing the license file

Copy the license file to anywhere on the computer on which you want to install
Columbus OM; when you install Columbus OM, it will ask you for the
location of the license file, and then move it to where it needs to be.)
If you copy the file by using FTP, make sure that the file is transferred in binary
mode.

Updating the license file


If you receive a new license file, do the following:
1

Stop the License Manager service.


See Starting and stopping License Manager below.

Copy the new license file into the folder in which the License Manager is
installed.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Start the License Manager service.

Starting and stopping License Manager


Windows

Use the Services icon in the Window Control Panel. The License Manager
service is called M4 License Manager.

UNIX
1

Change to the directory in which License Manager is installed.

Do one of the following:


To

Type

start License Manager

./cr_lrm.opsys start

stop License Manager

./cr_lrm.opsys stop

For example, to start License Manager on Solaris, type:


./cr_lrm.sol start

To start License Manager on AIX, type:


./cr_lrm.aix start

Columbus OM on a shared disk


If you install a Columbus OM instance on a shared disk, each host computer that
accesses the disk must have a license file. Each host computer must: be the same
type; be from the same manufacturer; and run the same version of the operating
system. This ensures that the locking mechanism (used for maintaining update
integrity) works correctly, and that queues are managed in the same manner:
different systems organize data in different ways and this can cause queue
corruption.

Using a set of
license keys

If you license is in the form of a set of license keys, you enter the keys when you run
the installation program.
Updating the license keys
If you need to update your license keys, use the keyset command.
Before running the keyset command, make sure that the %UNIQDIR% environment
variable contains the path of the Columbus OM instance whose license you are
updating.
To display your license information

Type:
keyset -q

To update your license keys


1

Log on as the user id which you specified during installation as the


Columbus OM owner, and then change to the installation folder.

COLUMBUS OM INSTALLATION AND CONFIGURATION

25

26

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Type:
keyset
System name: MyHost

Make sure that the name is the same name that you supplied to Macro 4 when
you requested the license.
Enter key 1:

Type the license keys in order. After each license key, press Enter.
After the last license key, press Enter twice.
License name

Type a name to identify the license, for example, the name of your company.
The license name will be displayed when you run a Columbus OM command.
License number:

Type the license number that has been supplied by Macro 4.


Columbus OM updates the license information.

Network connectivity
Columbus OM components that are installed on different computers communicate
by using the TCP/IP protocol and some network services. You must make sure that
all the computers use the port numbers for the services.
Columbus OM services
The basic Columbus OM network services are:
Service

Port number

Used for

uniqcs

2006 (suggested)

General communication (between


Columbus OM instances; and between a
instance and Columbus OM Explorer)

printer

515 (standard)

Columbus OM print LPD/LPR communication

2001 (suggested)

Columbus OM PC Printer Channel


communication

You can use different port numbers from those suggested above; but you must use
the same port number for any given service on all computers (hosts and PCs) in the
Columbus OM network.
If required, you can create two or more independent Columbus OM networks by
running each network on different port numbers.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Setting the port numbers

(Windows.) The installation program sets the port numbers for you. Check that
the port number is not already being used by looking in the computers services
file.
(UNIX.) You must add the uniqcs service and port number to the services file,
after you have installed Columbus OM.

The location of the services file is as follows:


System

File location

UNIX

/etc/services

Microsoft
Windows 95/98

\windows\services

Microsoft
Windows NT, 2000,
XP and later

%SystemRoot%\system32\drivers\etc\services

Novell NetWare

\etc\services

Creating a Columbus OM user


Before installing Columbus OM, you must create a operating system user (and, on
UNIX, a user group) under whom the Columbus OM services will be started. You
are recommended to create a user who is used for only this task. The
recommended user name is uniq.
See:

Creating a user
(Windows 2000
and later)

Creating a user (Windows 2000 and later) below

Creating a user and user group (UNIX) on page 28.

To create a user account


1

Select Start

Double-click the Users and Passwords icon.

Select the Advanced tab, and then click the Advanced button.

In the Local Users and Groups window, click Users in the left-hand pane.

On the Action menu, click New User to display the New User dialog box.

Type a user name and password.

Settings

Control Panel.

The recommended username is: uniq.

The password is case-sensitive.

Clear User Must Change Password at Next Logon and select Password
Never Expires.

Click Create, then click Close.

To configure the user rights policies


1

Select Start

Settings

COLUMBUS OM INSTALLATION AND CONFIGURATION

Control Panel.

27

28

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Double-click Administrative Tools, and then double-click the Local


Security Policy icon.

In the Local Security Settings windows, click + (plus sign) next to Local Policy
in the left-hand pane, then click its sub-entry User Rights Assignments.

Double-click Act as part of the operating system.

Click Add to display the Select Users or Groups dialog box.

Click the username of the new account (uniq) in the Names list.

Click Add to display the PC\username combination in the Add Names list.

Click OK to close the Select Users or Groups dialog box, and then click OK
again to close the Local Security Policy Setting window.

Double-click Log on as a service.

10 Repeat steps 6 through 10.

If you are using Windows 2003:

Creating a user
and user group
(UNIX)

Make sure that the uniq user is not a restricted user.


Enable the uniq user to access the folders in which Columbus OM is installed
by adding uniq as a user of the folder hierarchy with Full control.

You must create a UNIX user and user group:

The user will own the Columbus OM directories and files.

The user group will have the appropriate access rights to the directories and
files.

You are recommended to create a user called uniq, and a user group called
uniqgrp, and use them only for Columbus OM.
If you install two or more Columbus OM instances, use the same user and user
group for all the instances.
Note

Some Columbus OM programs, for example lpdserver and statserver,


must be owned by root (and have the s bit set) in order to operate
properly. The installation process handles this automatically.

Selecting an installation folder


The installation program asks you which folder you want to install Columbus OM.
If the folder does not exist, the installation program creates it for you.
To install multiple instances on the same computer, install them in subfolders of a
main Columbus OM folder, for example:
Main Columbus OM folder
Installation folder for Fax instance 1
Installation folder for Fax instance 2
Installation folder for Print instance 1
Installation folder for Print instance 2

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Folder names

(Windows only.) The path for the installation folders must not include any
space characters. Other than this restriction, standard Windows naming
conventions apply.

(UNIX only.) The recommended location for the main Columbus OM folder is
/usr/uniq.

The name of the folder does not relate to the name of the instance; you specify
that name later in the installation process.

Selecting a commands directory (UNIX only)


If you install two or more Columbus OM instances on the same computer, you can
install some of their programs in a common directory so that they are shared. The
programs that can be shared are the commands that are usually installed in the
Columbus OM programs/commands directory.
For example, to keep all the Columbus OM programs together, but separate from
other UNIX commands, you could create a directory called /usr/UniQ/bin. To
keep the programs somewhere that is commonly included in users $PATH
environment variable, you could put them in the /usr/local/bin directory.
If you use this feature, you must:

create the folder before installing Columbus OM

make sure that the folder can be accessed by all the instances, typically by
setting its owner to uniq and its access group to uniqgrp.

upgrade all instances which share files at the same time to make sure that they
are compatible.

Installing X-Server with Virtual Frames Buffer (UNIX only)


Columbus OM handles some image and document formats by using X-Server with
Virtual Frames Buffer. You must check that this is installed on your computer. For
more information, see:

X-Server and virtual frames buffer (AIX) below

X-Server and virtual frame buffer (HP-UX, Linux and Solaris) on page 30

X-Server and virtual frames buffer (AIX)


To check if X-Server is already installed

At the command prompt, type:


lslpp -l | grep vfb

If the reply includes these lines, it indicates that X-Server is installed.


OpenGL.OpenGL_X.dev.vfb
X11.vfb

4.3.3.75
4.3.3.50

COMMITTED
COMMITTED

OpenGL Virtual Frame Buffer


Virtual Frame Buffer Software

If the reply is blank, it indicates that X-Server is not installed; you must install
the X11.vfb module by following the instructions below.

COLUMBUS OM INSTALLATION AND CONFIGURATION

29

30

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

To install the X11.vfb module

The X11.vfb module is available from the AIX V4.3.3 installation CD-ROMs and
from the AIX Version 4 Update CD-ROM.
1

Put the CD-ROM in the AIX computers CD-ROM drive.

Login as root.

At the command prompt, type:


smit

The smit utility starts.


4

Navigate to Software Installation and Maintenance Install and Update


Software Install and Update from LATEST Available Software
INPUT device/directory for software.

Press F4, and then select the CD-ROM drive (for example, /dev/cd0).

In Install and Update from LATEST Available Software, set SOFTWARE to


install to X11.vfb.
To do this, either type X11.vfb, or press F4 to display a list of options and then
select X11.vfb.

Set PREVIEW only? (install operation will NOT occur) to yes.

Press ENTER.
The preview installation starts.

If the preview completes successfully, set PREVIEW only? (install operation


will NOT occur) to no, and then press ENTER to complete the installation.

See also Starting the virtual frame buffers on page 30.


X-Server and virtual frame buffer (HP-UX, Linux and Solaris)
1

Check whether Xvfb is installed (for example, in /usr/bin/X11/Xvfb).

If it is not installed, install it by following the operating systems instructions.

See also Starting the virtual frame buffers on page 30.

Starting the
virtual frame
buffers

To start the virtual frame buffers


1

Login as root.

At the command prompt, type:


AIX:
X -vfb :n > logfile &

HP-UX:
nohup Xvfb :n -screen 0 1x1x24 -cc 4

Linux:
Xvfb :n -screen 0 1600x1200x24 &

Solaris:
/usr/X11R6/bin/Xvfb :n -screen 0 1x1x24 -cc 4 2>>logfile &

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Replace:

n with the screen number, usually 1.


logfile with the name of a file to be used by the buffer for recording
information.

Configuring Microsoft Internet Information Services (IIS)


If you are using the Columbus IOP web interface with Microsoft Internet
Information Services (IIS) 7, you must configure IIS manually, as described below.
You must do this before installing Columbus OM.
If you are using IIS 6, the Columbus OM installation program configures it for you.
Adding the roles services
1

In IIS Server Manager, navigate to Roles

In the Role services section, click Add Role Services.

Web Server (IIS).

The Select Roles Services dialog box appears.


3

Select these items:

ISAPI Extensions

ISAPI Filters

Basic Authentication

Windows Authentication

IIS Management Scripts and Tools

IIS 6 Management Compatibility, and all items under it.

Click Next.

Click Install.

When the items have been installed, click Close, and then close IIS Server
Manager.

Changing the port number for the default website


1

In IIS Manager, navigate to Sites

Right-click Default Web Site, and then click Edit bindings.

Default Web Site.

The Site Bindings dialog box appears.


3

Click Edit.

Change the port number to something other than 80 (for example, 81), and
then click OK. (80 is used by the Columbus IOP web interface, so the default
website must use a different number.)

Enabling 32-bit applications


If you are installing the Columbus IOP web interface on a 64-bit operating system,
you must also enable IIS to run 32-bit applications.
1

In IIS Manager, navigate to Application pools.

COLUMBUS OM INSTALLATION AND CONFIGURATION

31

32

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Right-click DefaultAppPool, and then click Advanced settings.


The Advanced Settings dialog box appears.

Set Enable 32-bit Applications to True.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

Checklist
License format
License information (set of keys or
file) available
Using a license file
Location of license file
Choose one of:

Install Columbus License


Manager

Use an existing Columbus


License Manager

To use an existing License Manager, you need this information:

MAC address of the computer


that the License Manager is on
(12 numbers or letters; exclude
any punctuation symbols)

Port number

Installation folder

Operating system
Port number for Columbus OM
uniqcs service (for example, 2006)
Columbus OM username (for
example, uniq). On Windows,
include the PC name or domain
name
(UNIX only) Columbus OM user
group created (for example, uniqgrp)
Installation folder
(UNIX only) Commands directory
name
(UNIX only) X-Server with VFB is
installed
To use Columbus OM WebChannel:
Web server installed
Columbus IOP deployments
Web browser is installed
Web server is installed

COLUMBUS OM INSTALLATION AND CONFIGURATION

33

34

CHAPTER 2

Installing Columbus OM

Preparing to install Columbus OM

PHP is installed, or the PHP


installation program is available
If you are using Microsoft Internet
Information Services 7: IIS has been
configured (see page 31)
For Columbus Accounting: The database
application is installed

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Installing Columbus OM (Windows)

Installing Columbus OM (Windows)


1

Log on with Administrator access rights.

Complete the steps that are described in Preparing to install Columbus OM


on page 24.

Check that you have the information that the installation program needs. For
more information, see Checklist on page 33.

Using Windows Explorer, navigate to the folder that contains the


Columbus OM installation program, and then double-click the setup.exe file.

Follow the onscreen instructions.

Installing Columbus OM without user interaction (Windows)


If you are installing multiple copies of Columbus OM with the same or similar
values, you can make the process faster by putting the values that you would
usually put in the dialog boxes in the installation program in a responses file. You
can then run the installation program and tell it to read all the values from the
responses file instead of displaying the dialog boxes.
To create a responses file

The easiest way to create a responses file is to install Columbus OM by using the
installation program as usual, and record the values that you enter.
1

Set up the environment as described in Preparing to install Columbus OM on


page 24.

Start the installation program by typing:


setup.exe -r

Complete the dialog boxes, and run the installation program to completion.
The installation program records the values that you put in the dialog boxes in
a responses file called setup.iss. The file is in the Windows folder.

To use the responses file


1

On the computer on which you want to install another copy of Columbus OM,
set up the environment as described in Preparing to install Columbus OM on
page 24.

If required, edit the responses file to make the values appropriate for this copy
of Columbus OM.

Start the installation program by typing:


setup -s -f1folder\setup.iss

Replace folder with the path of the folder that the responses file is in, for
example: setup -s f1c:\windows\setup.iss.
The installation program installs Columbus OM, using the values that are in
the responses file; no dialog boxes appear.
4

When the installation program has finished, check the setup.log file that is in
the same folder as the responses file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

35

36

CHAPTER 2

Installing Columbus OM

Installing Columbus OM (Windows)

If the ReturnCode value is zero, it indicates that the installation was


successful. To complete the installation, see Configuring Columbus OM
on page 42.
If the ReturnCode value is not zero, identify the error by using this list:

Return code

Description

Success

-1

General error

-2

Invalid mode

-3

Required data not found in the responses file

-4

Not enough memory available

-5

File does not exist

-6

Cannot write to the responses file

-7

Unable to write to the log file

-8

Invalid path to the responses file

-9

Not a valid list type (string or number)

-10

Data type is invalid

-11

Unknown error during setup

-12

Dialog boxes are out of order

-51

Cannot create the specified folder

-52

Cannot access the specified file or folder

-53

Invalid option selected

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Installing a Columbus Intelligent Office Printing (IOP) deployment

Installing a Columbus Intelligent Office Printing


(IOP) deployment
1

Complete the steps that are described in Preparing to install Columbus OM


on page 24 and Support applications for Columbus IOP deployments on
page 37.

Install the support applications that a Columbus IOP deployment uses. For
more information, see Support applications for Columbus IOP deployments
on page 37.

Check that you have the information that the installation program needs. For
more information, see Checklist on page 33.

Using Windows Explorer, navigate to the folder that contains the


Columbus IOP installation program, and then double-click the setup.exe file.

Support applications for Columbus IOP deployments


If you are installing a Columbus IOP deployment, you must install the following
support applications. These applications are used by the Columbus IOP web
interface and Columbus Accounting.
Application

Installation instructions

a web browser

Follow the manufacturers instructions.

PHP

Download the PHP installation program from


www.php.net, and then do one of the following:

web server: Apache or


Microsoft Internet
Information Services

Run the PHP installation program. Use the


default options.

If you want the Columbus IOP installation


program to install PHP, copy the installation
program to the same folder as the Columbus IOP
installation program, and then rename it to
php.msi.

Install the web server by using its installation program.


Use the default options.
The Columbus installation program will configure the
web server to support the IOP web interface.

Only for Columbus Accounting:


a database application (for Follow the manufacturers instructions. You must also
example, MySQL)
install an administration program for the database,
and then create a database, as described in the
Columbus Accounting manual.
For more information about the versions of these applications that are supported,
see the Columbus OM Release Notes.
You do not need to create a user for Columbus Accounting or the IOP services,
because the Columbus IOP installation program can create one for you.

COLUMBUS OM INSTALLATION AND CONFIGURATION

37

38

CHAPTER 2

Installing Columbus OM

Installing a Columbus Intelligent Office Printing (IOP) deployment

Using the installation program


In the installation program, select these options:
Step

Option

IOP Installer

Select Standalone installation.

Columbus Accounting

Destination Folder

Select the folder in which you want to install


Columbus Accounting.

Instance Name

This is usually set to Accounting.

License Details

Type your license keys in the Keys box, one by one.


After each key, click Add. After the last key, click Add,
and then click Next.

Create User

Type a name and password for a user to control the


Columbus Accounting service.

Accounting Service Use the default values (that is, 0.0.0.0 and 8084).
Create Accounting
Database

Type the User and Password to enable access to the


database application.

MAGIK and SMTP Set Magik Host to localhost.


Set the host and domain of your SMTP server as
appropriate.
Create Shortcuts

Select the options that you want.

Columbus OM

Setup Type

Select Zone Server.

Choose Destination Select the folder in which you want to install


Location
Columbus OM.
Create Instance

Type a name to identify the instance, for example IOP, and


the port for the uniqcs service (see Columbus OM
services on page 26).

Service Logon

Type the name and password of the user that you want to
control the Columbus OM service.

When the installation program asks if you want to configure the Accounting server, click
Yes.
IOP Install (Details Use the default values (that is, localhost and 8084).
of the Accounting
server)
When the installation program asks if you want to configure the Zone server, click Yes.
IOP Install (Details Use the default values (that is, localhost, 8082, and the
of Zone server)
name of the instance as specified above).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Installing a Columbus Intelligent Office Printing (IOP) deployment

Step

Option

MAGIK and PHP

Choose Destination Select the folder in which you want to install MAGIK.
Folder
PHP Location

Select the folder in which you installed PHP.

Web server

Select the web server that you want to use: either IIS or
Apache.

Desktop Shortcut
Selection

Select all the options.

Completing the installation


1

Install Columbus OM IOP Messenger. For more information about how to do


this, see IOP Messenger on page 70.

Open the Windows Control Panel, and then navigate to Administrative


Tools Local Security Policy Local Policies User Rights Assignment.

Make sure that the following policies include the uniq user:

Act as part of the operating system

Log on as a batch job

Log on locally.

Make sure that the uniq user has full Administrator authority over the folder in
which Columbus Accounting is installed:

In Windows Explorer, right-click the folder, and then click Properties.


Click the Security tab, and then click the uniq user. Make sure that all the
Permissions are set to Allow.

Open this file in a text editor (for example, Notepad):


c:\ColumbusAccounting\Security\implementors

Make sure that the file contains an entry for the Columbus IOP instance and
Columbus Accounting, like this:
#
# Name
-----------IOP
Accounting

Same
Path
type?
----------------------- ----C:\ColumbusOM
Yes
C:\ColumbusAccounting
Yes

Product
------Print
Batch

If the file does not contain either of these entries, add them.
7

Open this file in a text editor:


c:\ColumbusAccounting\system.tab

COLUMBUS OM INSTALLATION AND CONFIGURATION

39

40

CHAPTER 2

Installing Columbus OM

Installing a Columbus Intelligent Office Printing (IOP) deployment

Make sure that the file contains an entry for Columbus Accounting, like this:
#
# Name
Path
------------ ----------------------Accounting
C:\ColumbusAccounting\

Same
type? Product
----- ------Yes
Batch

Stop the Columbus OM service, and then start it again.

Configuring the IOP interface


1

In Windows Explorer, navigate to the magik\application\config folder,


and then open the magik.ini file in a text editor.

Set the parameters that are described below.

Parameters in the magik.ini file


[application]
;authAdapter = Magik_Auth_Adapter_Dummy
authAdapter = Macro4_Auth_Adapter_Om
;authAdapter = Magik_Auth_Adapter_Ldap

Specify how users names and passwords are to be validated. (Delete the
semicolon that is in front of the method that you want to use; insert a semicolon
at the front of the methods that you do not want to use.)
To

Use

check the user id in Columbus OM

Macro4_Auth_Adapter_Om

You must also configure the xmlserver


section.
check the user id in another program
(for example, Microsoft Active
Directory or OpenLDAP)

Magik_Auth_Adapter_Ldap

You must also configure the xmlserver


section (see [xmlserver] below.

not validate the user id (use this option Magik_Auth_Adapter_Dummy


only for testing)
[xmlserver]
xmlserverHost = text
xmlserverPort = number

The name or IP address of the computer that xmlserver is on, and the port
number on which it listens. If xmlserver and the IOP interface are on the same
computer, you can set xmlserverHost to localhost.
xmlserverInstance = text

The name of the Columbus OM instance that controls the xmlserver.


xmlserverPlatform = Windows

If xmlserver is running on Microsoft Windows, delete the semicolon (if any)


from the start of this line.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Installing Columbus OM (UNIX)

Installing Columbus OM (UNIX)


1

Log on as root.

Create a temporary directory to hold the Columbus OM distribution file, and


then copy the distribution file from the distribution medium to the temporary
directory.
The name of the distribution file indicates the operating system that it is for, for
example, ColumbusOM490.aix.tar.zip is for AIX (IBM RS6000).

Restore the installation files by using the tar command.


This creates a directory with a name like UniQ4900x.aix (that is, the name
indicates the version number and the operating system).

Change to the new directory.

Run the installation script by typing:


sh ./install
Welcome to the Columbus OM 4.x installation/upgrade process.
Before proceeding, you will need the following:
1. To be logged on as root.
2. A userid and a groupid to use as the Columbus OM "owner".
3. To know where to install/upgrade the Columbus OM product (80+Mb required).
4. Installations only. Columbus OM 4.2 and above supports two licensing
technologies. You will need EITHER:
A set of license keys authorising use of this product
OR
A valid license file authorising use of this product.
5. To shut down any active Columbus OM 4.x servers (upgrades only).
6. To shut down any locally running Columbus OM License Manager (upgrade
only).
Ok to proceed? [N]

Follow the onscreen instructions.


To answer the questions about how you want to configure Columbus OM, you
can either:

accept the default answer, shown in brackets [...], by pressing Return, or

type your answer, and then press Return.

When the installation program has finished, review the contents of the
warnings file. To do this, change to the installation directory, and then type:
more warnings

If you see a warning about SAP R/3 not being available on this platform, a
small number of integration capabilities, for example the use of the
csulin_sap validation program by uqserver, cannot be used.
8

Delete the installation files from the temporary directory.

COLUMBUS OM INSTALLATION AND CONFIGURATION

41

42

CHAPTER 2

Installing Columbus OM

Configuring Columbus OM

Configuring Columbus OM
This section describes how to configure Columbus OM and the operating system
after you have installed Columbus OM.
These steps enable the Columbus OM program to work. After you have completed
these steps, additional steps will be necessary to configure it for your environment,
for example, to control printers and enable users to print documents.
Step

Description

See

(UNIX only.) Add the Columbus OM uniqcs service to


the services file

below

If you have two or more Columbus OM instances installed


on the same computer that you want to use together, you
must:

make each instance aware of the others

below

make sure that only one instance runs the


Columbus OM communications server, uqserver

page 44

(Windows only.) Make sure that authorized users can


access Columbus OM

(UNIX only) Set the Columbus OM environment variables page 45

page 45

Updating the services file (UNIX only)


Add an entry to the services file for Columbus OM uniqcs service. For more
information, see Network connectivity on page 26.

Enabling instances to work together


If you have two or more Columbus OM instances installed on the same computer
and you want the instances to work together, add the other instances to each
instances systems.tab file.

If you have only one Columbus OM instance, you have to update this file only
if you want to change the instance name. For example, if you might add other
instances later, you could change PRINT to PRINT1.

Occasionally, some sites require that instances are not aware of each other;
however, in most cases, it is easier to administer and use Columbus OM if all
the instances on a host are aware of each other.

systems.tab file location


The systems.tab file for an instance is in the folder in which the instance was
installed (that is, %UNIQDIR%).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Configuring Columbus OM

systems.tab file format


#
# Name
# ---------Print1
Print2

Path
-------------------------------------------------C:\Columbus OM\print1
C:\Columbus OM\print2

Same
type?
----Yes
Yes

Product
------PRINT
PRINT

The first line describes the instance that the file belongs to.
The other lines describe the other instances on the host that you want to use with it.
Fields
Name

A name to identify the instance.


Each instance on the host must have a unique name. The name can include
letters and numbers. It cannot include spaces. The maximum length is 10
characters.
Path

The full path of the folder in which the instance is installed, for example:
"C:\Columbus OM\print1" or /usr/uniq/print1. If the path include
spaces, enclose it in quotation marks.
Same type?

If the instance is the same type (that is, Print, Fax or Dispatch) as the instance
that to which the file belongs, specify Yes.
If they are different types, specify NO.
Product

One of: DISPATCH, FAX, PRINT.


Examples
If you install two Columbus OM instances, the systems.tab file for the first print
instance might look like this:
#
# Name
# ---------P1
P2

Path
-------------------------------------------------"C:\Columbus OM\print1"
"C:\Columbus OM\print2"

Same
type?
----Yes
Yes

Product
-------PRINT
PRINT

The systems.tab file for the second print instance might look like this:
#
# Name
# ---------P2
P1

Path
-------------------------------------------------"C:\Columbus OM\print2"
"C:\Columbus OM\print1"

Same
type?
----Yes
Yes

Product
-------PRINT
PRINT

If you then install a Columbus OM fax instance, the systems.tab files might
become:

COLUMBUS OM INSTALLATION AND CONFIGURATION

43

44

CHAPTER 2

Installing Columbus OM

Configuring Columbus OM

For the first print instance:


#
# Name
# ---------P1
P2
F1

Path
-------------------------------------------------"C:\Columbus OM\print1"
"C:\Columbus OM\print2"
"C:\Columbus OM\fax1"

Same
type?
----Yes
Yes
No

Product
-------PRINT
PRINT
FAX

Same
type?
----Yes
Yes
No

Product
-------PRINT
PRINT
FAX

Same
type?
----Yes
No
No

Product
-------FAX
PRINT
PRINT

For the second print instance:


#
# Name
# ---------P2
P1
F1

Path
-------------------------------------------------"C:\Columbus OM\print2"
"C:\Columbus OM\print1"
"C:\Columbus OM\fax1"

For the fax instance:


#
# Name
# ---------F1
P1
P2

Path
-------------------------------------------------"C:\Columbus OM\fax1"
"C:\Columbus OM\print1"
"C:\Columbus OM\print2"

Enabling the uqserver program


If there are two or more Columbus OM instances on the host, you must make sure
that only one of them runs the uqserver program. (uqserver enables instances on
different hosts to communicate with each other, and for Columbus OM Explorer to
communicate with the instance.)
If the instances use different versions of Columbus OM, choose the most recent
version as the instance to run uqserver. In the other instances, you must disable
uqserver.
To disable uqserver
1

In the instance that you do not want to run uqserver, edit the
servers\servers.tab file. This file lists all the servers that the instance runs.

Look for an entry for uqserver.


# Name
# ---. . .
uqserver
. . .

Id
--

Program
-------

AI?
---

AT?
---

AS?
---

Master?
-------

uqserver

Yes

Yes

Yes

Yes

Inserting a hash symbol (#) at the start of the line for uqserver.
# Name
# ---. . .
# uqserver
. . .

Id
-2

Program
-------

AI?
---

AT?
---

AS?
---

Master?
-------

uqserver

Yes

Yes

Yes

Yes

Notes

If there is only one Columbus OM instance on the host, you do not have to edit
this file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Configuring Columbus OM

There might be site-specific circumstances in which multiple instances on the


same host should use separate copies of uqserver, and you should then
interpret these instructions accordingly. In most cases, however, you will find it
easier to administer and use your Columbus OM installation if only one of the
instances on a host runs uqserver.

Granting access to local and remote users (Windows only)


You must ensure that Columbus OM is accessible by authorized users. You have
separate control over access by:

local users: those running Columbus OM Explorer on the PC where you have
installed Columbus OM

remote users: those running Columbus OM Explorer on another PC elsewhere


in the network.

To grant appropriate rights to users


1

Select Start

Double-click the Administrative Tools icon, and then double-click the Local
Security Policy icon.

In the Local Security Settings windows, click the + next to Local Policy in the
left-hand pane, then click its sub-entry User Rights Assignments.

For a local user, double-click Log on locally. For a remote user, double-click
Access this computer from network.

Click Add to display the Select Users or Groups dialog box.

Click the username of the new account (uniq) in the Names list.

Click Add to display the PC\username combination in the Add Names list.

Click OK to close the Select Users or Groups dialog box, and then click OK to
close the Local Security Policy Setting window.

Settings

Control Panel.

The post-installation configuration steps for Windows are now complete, and you
can start the new instance. See Starting Columbus OM on page 48.

Setting Columbus OM environment variables (UNIX only)


Columbus OM uses these environment variables:
Variable

Description

$UNIQDIR

The directory in which the instance has been installed.

$PATH

The standard UNIX variable defining a command search path,


extended to include a reference to the directory in which the
instances binaries have been installed (for example
$UNIQDIR/programs/commands).

$UNIQ_GROUP

Only if Group Security is in use: The printer group to which the user
belongs. If undefined, Columbus OM searches
$UNIQDIR/security/groupsec.tab to determine the users
group membership and thus the available actions.

COLUMBUS OM INSTALLATION AND CONFIGURATION

45

46

CHAPTER 2

Installing Columbus OM

Configuring Columbus OM

Variable

Description

$WOPQ_GROUP

Only if Group Security is in use: The printer group to which the user
belongs for the purpose of the Printer Operations display. If
undefined, Columbus OM searches
$UNIQDIR/security/groupsec.tab to determine the users
group membership and thus the displayable printers.

$UNIQTERM

Used in preference to $TERM to identify the users terminal type.


If undefined, the $TERM value is used.

With the exception of $TERM and $UNIQTERM, the variables are specific to each
Columbus OM instance, and must be properly defined for all users requiring access
to that instance. For example, if you have installed two Columbus OM instances,
users wanting to use the first instance might set $UNIQDIR to /usr/UniQ/print1
(and the other variables accordingly), while users of the second instance might set it
to /usr/UniQ/print2.
To initialize the variables, see:

Setting variables (Bourne and Korn shells) below

Setting variables (C shell) on page 46.

Setting variables To set the variables statically, add these lines to each users .profile file:
(Bourne and
UNIQDIR=installation_directory
export UNIQDIR
Korn shells)
UF_HOME=$UNIQDIR/uniform
export UF_HOME
PATH=$PATH:bin_directory
UNIQ_GROUP=printer_group
WOPQ_GROUP=printer_group
UNIQTERM=terminal_type

export
export
export
export

PATH
UNIQ_GROUP
WOPQ_GROUP
UNIQTERM

# if needed
# if needed
# if needed

Alternatively, run a Columbus OM script to set the first three values dynamically
by adding these lines to each .profile file:
. installation_directory/setup
UNIQ_GROUP=printer_group
WOPQ_GROUP=printer_group
UNIQTERM=terminal_type

export UNIQ_GROUP
export WOPQ_GROUP
export UNIQTERM

# if needed
# if needed
# if needed

Setting variables To set the variables statically, add these lines to each users .login file:
(C shell)
setenv
setenv
set
setenv
setenv
setenv

UNIQDIR
UF_HOME
PATH
UNIQ_GROUP
WOPQ_GROUP
UNIQTERM

installation_directory
$UNIQDIR/uniform
( $PATH bin_directory )
group
# if needed
group
# if needed
terminal_type
# if needed

Alternatively, run a script to set the first three values dynamically by adding these
lines to each .login file:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

source
setenv
setenv
setenv

Environment
variables for
multiple
instances

Installing Columbus OM

Configuring Columbus OM

installation_directory/csetup
UNIQ_GROUP
group
# if needed
WOPQ_GROUP
group
# if needed
UNIQTERM
terminal_type
# if needed

If you have two or more Columbus OM instances on the same host, you can make
all of the instances available to users. There are two ways of doing this.
Method 1: Environment switching

Create a series of shell scripts, one for each instance, which set $UNIQDIR,
$UF_HOME and $PATH to refer to that instance. A user can run the appropriate script
prior to typing the uq command in order to invoke the appropriate menu interface.
Method 2: Queue switching
1

Make sure that are all the instances are at the same release level.

Set $UNIQDIR and $UF_HOME to refer to one instance, which will be the default
instance.

Extend $PATH to refer to all of the bin directories.


$PATH must refer to only one of the bin directories for each type. For example,

if you have two Columbus OM fax instances and three Columbus OM print
instances, $PATH must include only one of the Columbus OM fax command
directories and one of the Columbus OM print command directories. If you
have installed all the Columbus OM binaries in a single directory, $PATH need
refer only to that directory.
To

Do this

access the default instance

Type uq

access the other instances

Type uq -qn instance, where


instance is the name of the instance.
See Enabling instances to work
together on page 42).

COLUMBUS OM INSTALLATION AND CONFIGURATION

47

48

CHAPTER 2

Installing Columbus OM

Starting Columbus OM

Starting Columbus OM
Starting Columbus OM (Windows)
Columbus OM is installed as Windows service which starts automatically
whenever the computer starts. You can also start the service manually.
To start the Columbus OM service manually
1

Select Start

Double-click the Administrative Tools icon.

Double-click the Services icon to display the Services window.

Right-click the appropriate name in the right-hand pane to display the shortcut
menu.

Click Start or Stop.

Settings

Control Panel.

Starting Columbus OM (UNIX)


To use a Columbus OM instance, its servers (sometimes known as daemons) must
be running. To start an instances servers manually, use the command line interface
or Columbus OM Explorer. You can also start the servers automatically when the
host reboots.
To start Columbus OM manually
1

Log on as uniq.

If you are using the Columbus License Manager, start it. (See Starting and
stopping License Manager on page 25.)

Change to the Columbus OM installation directory, and then initialize the


environment variables by typing:
cd installation_directory
. ./setup

Type:
syq -ai

To start Columbus OM servers automatically


1

Log on as root.

Add these lines to a startup script which is appropriate for your UNIX system.
UNIQDIR=installation_directory
export UNIQDIR
$UNIQDIR/programs/commands/syq -ai

If you installed the Columbus OM commands in a different directory (see


Selecting a commands directory (UNIX only) on page 29), change the last line
accordingly.
3

Repeat the lines for each instance on the host.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Starting Columbus OM

Alternative procedures for starting and stopping Columbus OM


Columbus OM is started and stopped by starting and stopping the Columbus OM
service.

When you start the Columbus OM service, it runs a Columbus syq -ai
command to start the servers.
When you stop the Columbus OM service, it runs an syq -atnw command to
stop the servers. The syq -atnw command waits for the servers to stop cleanly.
When all the servers have stopped cleanly, the Columbus OM service itself
stops.

You can specify alternative commands for the Columbus OM service to use when
it stops and starts. For example, you can stop Columbus OM more quickly by using
the uqshutdown command instead of syq -atnw. The uqshutdown command tries
to stop each server; if a server does not stop within a short period, the command
kills it.
To specify an alternative start command

Put the start command in this batch file:


%UNIQDIR%\programs\commands\start.bat.

To specify an alternative stop command

Put the stop command in this batch file:


%UNIQDIR%\programs\commands\stop.bat.

To kill all the Columbus OM processes immediately

Killing all the Columbus OM processes immediately might be useful when


Columbus OM is running in a cluster environment. To do this, delete the
stop.bat file.
To shutdown services automatically

The uniqservice program can monitor the other Columbus OM services, and
shut them down if a process has stopped. To enable this feature, do the following:
1

Create a file called uniqservice.tab in the %UNIQDIR% folder.

In the file, put these parameters:


Initial_Delay n

Number of seconds between uniqservice starting itself, and when it starts


monitoring the processes.
Scan_Interval n

The interval (measured in seconds) at which uniqservice checks the


processes.
Max_Downtime_Cycle_Count n

The number of scans before uniqservice stops the Columbus OM service


after it detects a process has failed (as reported by the operating system).

COLUMBUS OM INSTALLATION AND CONFIGURATION

49

50

CHAPTER 2

Installing Columbus OM

Using Columbus OM in a VMWare environment

Using Columbus OM in a VMWare environment


You can use Columbus OM in a VMWare ESX 3.5 (or above) environment
hosting Microsoft Windows Server 2003 R2 (or above).
Before doing so, you should be aware that a virtual environment can be slower than
a native environment for these reasons:

Architecture: VMWare ESX 3.5 supports a maximum of four virtual CPUs for
each virtual machine. Columbus programs use all available CPUs; if future
versions of VMWare support more CPUs, performance should improve.
Columbus programs can be installed across two or more virtual machines;
however, this might cause management overheads and delays in
communications between services.

Virtualization overheads: Using a virtual environment creates overheads on


some aspects of the system. You might be able to improve the performance by
using faster hardware for the virtual environment, especially when moving a
system from older hardware.

Requirements

Before using the virtual environment, compare the advantages of using it


against the limitations that are described above. For low-usage systems that are
already meet the needs of SLAs and so on, the advantages might outweigh the
limitations.

Set up Resource Reservations in the ESX Server to give Columbus programs


exclusive access to the resources that it needs. For the memory, reserve the full
amount that is allocated to the virtual machine. For the CPU resources, reserve
resources according to the number of virtual CPUs (that is, CPU clock speed x
number of virtual CPUs).

Install Columbus programs on a new virtual machine with a new installation of


the operating system. Do not use an existing machine image.

Power off the system by shutting down Windows in the usual way. Do not use
the ESX Servers Suspend/Resume Virtual Machine feature.

For more information about improving the performance of ESX Server, see the
VMWare document, Performance Tuning Best Practices for ESX Server 3
(available from http://www.vmware.com). Macro 4 does not support systems in
which the requirements that are described above have not been met. Even if the
system is optimally configured, there might still be performance overheads which
are outside the control of Macro 4.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Upgrading Columbus OM

Upgrading Columbus OM
This section describes how to upgrade an existing Columbus OM instance to a new
version.
To upgrade a Columbus OM instance (Windows)

The upgrade process automatically stops any Columbus OM services that are
running.
1

Log on with Administrator access rights.

Using Windows Explorer, navigate to the folder that contains the


Columbus OM installation files, and then double-click the setup.exe file.

Follow the onscreen instructions.

To upgrade a Columbus OM instance (UNIX)


1

Stop all of the instances servers by typing:


syq -atnw

Download the installation files, and then run the installation script in the same
way as for installing Columbus OM.
For more information about how to do this, see Installing Columbus OM
(UNIX) on page 41.

COLUMBUS OM INSTALLATION AND CONFIGURATION

51

52

CHAPTER 2

Installing Columbus OM

Uninstalling Columbus OM

Uninstalling Columbus OM
Windows
Use the Add/Remove Programs icon in the Windows Control Panel.
UNIX
1

Delete the directory in which Columbus OM is installed.

Delete references to the instance from the operating system startup script.

If there are other Columbus OM instances on the same computer, delete


references to the deleted instance from their systems.tab files.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 2

Installing Columbus OM

Reference

Reference
License management

The following parameters can be set in the system defaults file (default.tab):

Action_On_LicenseFail command

A command to be run if the license file appears to be invalid: this could happen
if the Columbus License Manager that validates the license file is not available.
For example, the command could send an email message to the administrator.
The command can include the %MESSAGE substitution variable, which contains
either Forced shutdown in n hours or Forced shutdown NOW, as
appropriate.
Columbus OM continues to operate for 24 hours after the license validation
fails, giving you time to restart the License Manager.
LicenseManagerPort number

The port number on which the License Manager listens.


The default value is 7500.
LicenseManagerHost name

The name of the host computer on which the License Manager runs.
The default value is localhost.
MacAddress address

The MAC address of the host computer on which the License Manager runs.

COLUMBUS OM INSTALLATION AND CONFIGURATION

53

54

CHAPTER 2

Installing Columbus OM

Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

55

CHAPTER 3

Chapter 3

Columbus OM utilities

Program

See

Columbus OM Explorer

page 56

The Windows interface for configuring, administering and using


Columbus OM.
IOP Universal Driver

page 57

General-purpose printer driver that produces PCL 5 or PCL 6 output


which is compatible with most printers.
Columbus Windows Gateway

page 63

Enables Windows applications to print direct to a Columbus OM


system.
IOP Messenger

page 70

A Windows program for sending and receiving messages on other


computers.
All IOP desktop components

page 78

Columbus Windows Gateway, IOP Universal Driver and


IOP Messenger.
Columbus OM PC Printer Channel

page 83

Enables Columbus OM to send output to a printer that is directly


connected to a Windows computer.
Columbus OM Novell Gateway
Enables Columbus OM to send output to NetWare queue-based or
NDPS printers, and output from NetWare print queues to be sent to
Columbus OM.

COLUMBUS OM INSTALLATION AND CONFIGURATION

page 86

56

CHAPTER 3

Columbus OM utilities

Columbus OM Explorer

Columbus OM Explorer
Columbus OM Explorer enables you to access Columbus OM instances (on both
Windows and UNIX) from a PC running Windows.
To install Columbus OM Explorer
1

Using Windows Explorer, navigate to the folder that contains the


Columbus OM Explorer installation files, and then double-click the
setup.exe file.
The Setup window and Welcome dialog box appear.

Follow the onscreen instructions.

When the installation program has finished, check that the services file includes
an entry for the uniqcs network service. See Network connectivity on
page 26 for more information.

To upgrade Columbus OM Explorer

Follow the procedures for a new installation (see above).

To uninstall Columbus OM Explorer

Use the Add/Remove Programs icon in the Windows Control Panel.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP Universal Driver

IOP Universal Driver


The IOP Universal Driver is a general-purpose printer driver that produces PCL 5
or PCL 6 output which is compatible with most printers. It is usually used in IOP
deployments.
Using the IOP Universal Driver
1

You install the IOP Universal Driver, and then add a printer to Windows
which uses it. For more information about how to do this, see below.

You print a document to the printer. The printer driver sends the document to
Columbus OM.

If you are using the zone printing feature, Columbus OM analyzes the content
of the document, and then selects an appropriate printer on which to print it.

You might need to convert the codes that the printer driver puts in the print files
that it creates to codes that are specific to the printer that you use. For more
information about printer code mapping, see Printer code mapping on page 529.

Installing the IOP Universal Driver


The IOP Universal Driver can be installed in several ways:

by using the dialog boxes in the installation program

if you know the information that you want to put in the dialog boxes, in silent
mode. This mode is particularly suitable when you have to install IOP
Messenger on several computers.

at the same time as the other IOP desktop components: IOP Messenger and
the Windows Gateway. For more information about how to do this, see IOP
desktop components on page 78.

To install the IOP Universal Driver by using the dialog boxes

In Windows Explorer, double-click the IOP Universal Driver installation program,


and then follow the onscreen instructions.
To install the IOP Universal Driver in silent mode

To install the IOP Universal Driver in silent mode (that is, without any dialog
boxes appearing), change to the folder that the installation program is in, and then
type at the command line:
filename /s /v"/qn INSTALLDIR=folder LOCAL_LANG=language
ONCALL_PRINTER=Yes|No"
Parameters
filename

The name of the installation program, for example:


ColumbusOMPCL6Driver-10001.msi
INSTALLDIR=folder

The path and name of the folder in which you want to install the driver, for
example: C:\Program Files\Macro 4\IOP Universal Driver

COLUMBUS OM INSTALLATION AND CONFIGURATION

57

58

CHAPTER 3

Columbus OM utilities

IOP Universal Driver

LOCAL_LANG=language

The language to be used in the drivers dialog boxes, one of:


English
French
German
Spanish
ONCALL_PRINTER=Yes|No

To make the printer that is used with the driver an on-call printer for use with
a IOP deployment, specify Yes.
The default value is No.
To install the IOP Universal Driver and other desktop components

To install the IOP Universal Driver at the same time as the other IOP desktop
components: Columbus OM Messenger and the Windows Gateway. For more
information about how to do this, see IOP desktop components on page 78.

Adding a printer that uses the IOP Universal Driver


1

From the Windows Desktop, click Start


then click Add a Printer.

Settings

Printers and Faxes, and

The Add Printer Wizard appears.

Follow the onscreen instructions until you reach the Install Printer Software
step.

Select Have Disk.


The Install From Disk dialog box appears.

Click Browse.
The Locate File dialog box appears.

Navigate to the folder in which the printer driver is installed (for example,
c:\Program Files\Macro 4\Columbus OM PCL Driver).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP Universal Driver

Do one of the following:


If you have installed

Do this

the PCL 5 program

Click the OMPCL.INF file, and then


click Open.

the PCL 6 program

Click the OMPCL6.INF file, and then


click Open.

In the Install From Disk dialog box, click OK.


The Install Printer Software dialog box appears.

Check that the IOP Universal Driver is shown in the Printers box, and then
click Next.

If the Use Existing Driver dialog box appears, select Replace existing driver,
and then click Next.

10 Follow the rest of the onscreen instructions.


11 If a Hardware Installation dialog box appears, telling you that the software has

not passed Windows Logo testing, click Continue Anyway.

Configuring the IOP Universal Driver


You can customize the printers Properties dialog box. You can:

control which options are available

change the text that is displayed next to the options and controls

replace the Macro 4 logo with another image.

COLUMBUS OM INSTALLATION AND CONFIGURATION

59

60

CHAPTER 3

Columbus OM utilities

IOP Universal Driver

To change which options are available


1

Edit the printers configuration file in a text editor:


C:\Windows\system32\spool\drivers\w32x86\3\ompcl.cfg

The file looks like this:


# ColumbusOM PCL Driver - Configuration file
#
#
Display
Enable
#
Show\Hide
Yes\No
Copies
Yes
Punch
No
Save_Toner
Yes
Collate
Yes
Pin
Yes
SecureTab
Yes
Oncall
Yes
Watermark
No
Urgency
Yes
Cost_Centre
Yes
Jobticket
Yes
Delivery_Method Yes
Multi_Tray_Selection Yes
Save_Toner
Yes
Hide_Attributes
No
Staple_Type
Yes
NONE
None
STAPLE
Normal
SADDLE_STAPLE
Saddle
...

Count

No

12

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP Universal Driver

To control which options are available in the Properties dialog box, do the
following:
To

Do this

make a control available

Set the value in the Display


Show/Hide column to Yes.

make a control unavailable (that is, it is Set the value in the Display
visible, but greyed-out)
Show/Hide column to No, and set the
value for the Hide_attributes
property to No.
hide a control (that is, make it
invisible)

Set the value in the Display


Show/Hide column to No, and set the
value for the Hide_attributes
property to Yes.

hide the Security tab completely

Set the value in the Display


Show/Hide column for SecureTab to
No.

select the OnCall printer option by


default

Set the value in the Enable Yes/No


column for the OnCall property to
Yes.

clear the OnCall printer option by


default

Set the value in the Enable Yes/No


column for the OnCall property to No.

Do not change any other values (for example, the Count value) or the items
in the lists (for example, NONE, STAPLE, and SADDLE_STAPLE in the example
above).
3

Save the file.

To change the text that is displayed in the Properties dialog box


1

Navigate to the folder in which the printer driver is installed (for example,
c:\Program Files\Macro 4\Columbus OM PCL Driver).

Copy the ompcl_text.cfg file to this folder:


C:\Windows\system32\spool\drivers\w32x86\3

Open the ompcl_text.cfg file in a text editor.


The file contains two columns, like this:
COLUMBUS_TAB
URGENCY_TITLE
URGENCY_IMMEDIATE
URGENCY_10MINS
URGENCY_30MINS
URGENCY_HOUR
URGENCY_AMPM
URGENCY_TODAY
...

Columbus Options
Urgency
Immediate
Within 10 minutes
Within 30 minutes
Within 1 hour
This AM/PM
Today

The left column contains the identifiers of the controls; the right column
contains the text that is displayed for each control.

COLUMBUS OM INSTALLATION AND CONFIGURATION

61

62

CHAPTER 3

Columbus OM utilities

IOP Universal Driver

Change the text that is in the right column as required.


Do not change the text that is in the left column.

Save the file.

To replace the logo


1

Create an icon file version of the logo. The image must be 32 x 32 pixels.

Call the icon file m4driver_icon.ico.

Put the icon file in this folder:


Windows\system32\spool\drivers\w32x86\3

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus Windows Gateway

Columbus Windows Gateway


The Columbus Windows Gateway enables Windows applications to print direct to
a Columbus OM system.
Overview of the Columbus Windows Gateway environment
The Windows Gateway is installed on a PC from which you want to print
documents. When you install it, it creates a new printer port that is called
Columbus OM Port.
You configure the port to refer to a printer that is controlled by Columbus OM,
and then you add a printer (by using the Windows Add Printer facility), and
configure it use the new port.
You can use the Print command in any Windows application, selecting the new
printer. Windows sends the output to the Columbus OM Port; the port sends it to
Columbus OM; and then Columbus OM sends it the printer.
You can specify alternative Columbus OM instances to be used if the main instance
is unavailable.
The printer (and the Windows Gateway functionality) can be made available to
other users by making it a shared printer under Windows.
The Windows Gateway must be installed on a Windows computer. The Windows
Gateway is available for Windows 2000 and later.
For information about where to install the Windows Gateway in a IOP
deployment, see Static and roaming users (desktops and laptops) on page 498.

Installing the Columbus Windows Gateway


Before starting
The Windows Gateway installation program asks for this information:

the computer that the Columbus OM instance is on: you need either its name
or IP address. For an IOP deployment, you need the name or IP address of the
computer that the zone server is on.

the port number that the instance listens on


To find this out, look in the uqserver configuration file for the value that the
Service parameter is set to (usually uniqcs). Then look for this service in the
Windows services file (\windows\services\winnt\system32\drivers\
etc\services), and note the port number that it uses.

the name of the printer in the instance to be used.

Installation options
The Windows Gateway can be installed:

by using the dialog boxes in the installation program

at the same time as the other IOP desktop components: IOP Messenger and
the IOP Universal Driver. For more information about how to do this, see IOP
desktop components on page 78.

COLUMBUS OM INSTALLATION AND CONFIGURATION

63

64

CHAPTER 3

Columbus OM utilities

Columbus Windows Gateway

on a cluster. For more information about how to do this, see Installing the
Windows Gateway on a cluster on page 64.

To install the Windows Gateway on Windows


1

Log on with Administrator access rights.

If you are using Windows in any language other than English, stop the
Windows Print Spooler.

Navigate to the folder that the Windows Gateway installation program is in,
and then double-click the setup.exe file.

Follow the onscreen instructions.

When the installation program has finished, you can add a printer to use the
Windows Gateway: see Adding printers to use the Windows Gateway on
page 65.

Installing the Windows Gateway on a cluster


This section describes how to install the Windows Gateway on a Windows 2000 or
Windows 2003 cluster.
Before starting
Configure the cluster print spooler by following the instructions that are provided
by Microsoft.
Installing the Windows Gateway
The first step is to install the Windows Gateway on all the nodes in the cluster:
1

Stop the cluster print spoolers.

When you install the Windows Gateway, the installation program has to stop
the local print spooler. Usually, stopping the local print spooler triggers a
failover to the cluster print spoolers; stopping these print spoolers before you
install the Windows Gateway prevents this failover from happening.

Install the Windows Gateway on the active node in the cluster by following the
instructions above.
Install the program at the main console for the node; do not use a remote
desktop session.

Install the Windows Gateway on all the other nodes that are in the cluster.
Again, install the Windows Gateway at the main console for each node; do not
use a remote desktop session.

Start the cluster print spooler.

Creating a shared printer


The next step is to create a printer that all the nodes can access.
1

From the Windows Desktop on one of the nodes, click Start

Run.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus Windows Gateway

In the Run dialog box, type \\ (two backslash characters), and then either the
name of the cluster or its IP address, for example:
\\mycluster

Click OK.

Double-click Printers and Faxes, and then double-click Add Printer.

Using the Add Printer wizard, create a shared printer. This printer is the
shared clustered printer.

On all of the other nodes, add a printer. Set the printer type to Network
Printer, and then connect to the shared cluster printer by typing the IP address
of the cluster and the name that you gave it above.
You can now use the Windows Gateway in the clustered environment.

Adding printers to use the Windows Gateway


To set up the Windows Gateway, you must define a printer which uses the
Columbus OM port.
To add a printer to use the Columbus OM port
1

From the Windows Desktop, click Start


double-click Add Printer.

Settings

Printers, and then

The Add Printer dialog box appears.


2

Select Local Printer, and then click Create a new port.

Select Columbus OM Port from the list of port types, and then click Next.
The Columbus Port dialog box appears.

Set the properties as required: see Windows Gateway properties below.

Click OK.

COLUMBUS OM INSTALLATION AND CONFIGURATION

65

66

CHAPTER 3

Columbus OM utilities

Columbus Windows Gateway

In the Install Printer Software step, make sure that Manufacturer is set to
Macro 4, and Printers is set to Columbus OM PCL Driver, and then click
Next.

In the Use Existing Driver step, make sure that Keep existing driver is
selected, and then click Next.

In the Name Your Printer step, specify the name that the printer has in
Columbus OM to identify it, and then click Next.

Complete the rest of the Add Printer Wizard.


When you have finished, you can use the printer from the Print dialog box of
any Windows application.

Windows Gateway properties


Property

Description

Name

A name to identify the port.


For a basic Columbus OM system, use the same name that the
printer has in Columbus OM.
For an IOP deployment, use the name of the IOP port (for
example, IOP).

Zone Server

For a basic Columbus OM system, make sure that this option


is not selected.
For an IOP deployment, select this option.

Host

The name or IP address of the host computer on which


Columbus OM is installed.

Port No

The port number that Columbus OM uniqcs server uses.


There must be an entry for this number in the services file on
both the current computer and the computer that
Columbus OM is on.

Instance

The name of the Columbus OM instance. For an IOP


deployment, specify the name of the zone server instance.

Printer

The name of the printer that has been set up in


Columbus OM.

Medium

The name of the Columbus OM medium that is to be applied


to documents that are sent to the printer.
For a basic Columbus OM system, this is usually print.
For an IOP deployment, specify dispatch.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus Windows Gateway

Property

Description

Ticket

For a basic Columbus OM system, leave blank.


For an IOP deployment, specify IOP (in UPPERCASE).

Delete print job


on completion

Select this option if you want documents to be deleted from


Columbus OM as soon as they have been processed; that is,
you do not want them to move to the completed queue.
To enable a user to use this feature, you must add them to the
aeq_pc security file.

Encrypting documents
To encrypt the document, set either or both of the During Transfer and On Disk
properties.

During Transfer controls whether the document is encrypted while it is


transferred from the current computer to Columbus OM.

On Disk controls whether the document is encrypted when it is on the


Columbus OM queues.

To

Use this value

use 128-bit encryption keys

AES128

use 192-bit encryption keys

AES192

use 256-bit encryption keys

AES256

not encrypt the documents

NONE

To use this feature, do not select either Send accounting information only to
server? or Enable Local Port.
For more information about encrypting documents, see Encrypting documents on
page 374.
Using Columbus OM Accounting
If you are using Columbus OM Accounting, set these properties:
Property

Description

Send accounting
To send only a summary of the document (instead of the
information only to document itself) to Columbus OM, select this option. The
server?
summary includes the documents name, the owner, the
page count, and so on. To enable the Accounting module
to process the information, set the Accounting medium to
the medium that is used by the module.
Enable Local Port

To print the document on a local printer port (for example,


if you want to send only the summary to Columbus OM),
select this option. Specify the port in the Local Port box.

PJL?

(For PJL-enabled devices only.) Sends extra status


information to Columbus OM Accounting.

COLUMBUS OM INSTALLATION AND CONFIGURATION

67

68

CHAPTER 3

Columbus OM utilities

Columbus Windows Gateway

Specifying alternative Columbus OM instances


To specify alternative Columbus OM instances to which the document can be sent
if the first instance is not available, click the Backup 1 tab and optionally, the
Backup 2 tab, and then specify the details of the instances.

Troubleshooting the Windows Gateway


If a document does not print, check the Windows Gateway logfile.
The logfiles are called daynn_name.log, where nn is the day of the month, and
name is the name of the Windows port. They are in the folder that you specify
when you when you install the Windows Gateway. The logfiles are replaced after
one month.

Creating multiple Columbus OM ports


To add multiple Columbus OM ports, you can create a file that contains the
information about the port that you want to create, and then use the mk_portmon
command.
Port definition file format
The port definition file is a text file. It can have any name and it can be in any
location. It contains the following parameters. The parameters correspond to the
properties in the Windows Printer Setup dialog box (see Adding printers to use the
Windows Gateway on page 65).
Primary host parameters (mandatory)
NAME=name_of_port,
HOST=hostname,
PORTNO=TCP/IP port_number,
INSTANCE=Columbus_OM_instance,
PRINTER=Columbus_OM_printer,
MEDIUM=medium,
MIRRORENABLE= N|{Y, LOCALPORT=local_printer_port},
SUMMARYONLY=N|{Y, ACCOUNTING=accounting_medium},
ZONESERVER=N|Y,
TICKET=job_ticket,
ENCRYPTION=none|128|192|256,
ENCRYPT_DISK=none|128|192|256,
USERONLY=N|Y
Fail-over host 1 parameters (optional)
HOST1=hostname,
PORTNO1=TCP/IP_port_number,
INSTANCE1=Columbus_OM_instance,
PRINTER1=Columbus_OM_printer,
MEDIUM1=medium,
TICKET1=job_ticket

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus Windows Gateway

Fail-over host 2 parameters (optional)


HOST2=hostname,
PORTNO2=TCP/IP_port_number,
INSTANCE2=Columbus_OM_instance,
PRINTER2=Columbus_OM_printer,
MEDIUM2=medium,
TICKET2=job_ticket

mk_portmon command syntax


mk_portmon -f file

Replace file with the path and name of the port definition file.

Deleting Columbus OM ports


To delete a single Columbus OM port
1

From the Windows Desktop, click Start

In the Printers window, delete all printers that use the Columbus OM port.

Select any of the remaining printers, and then display its properties.

On the Details tab, click Delete Port.

Select the Columbus OM port, and then click OK.

Close the Printer Properties dialog box.

Settings

Printers.

To delete multiple Columbus OM ports

To delete multiple Columbus OM ports, you can create a list of the ports, and then
use the rm_portmon command.
1

Create a text file that lists the ports that you want to delete. The file can have
any name. Put each port on a separate line, for example:
MyPort1
MyPort2
MyPort3

On the command line, type:


rm_portmon -f file

Replace file with the path and name of the list of ports file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

69

70

CHAPTER 3

Columbus OM utilities

IOP Messenger

IOP Messenger
IOP Messenger enables you to send messages to other users. The messages
automatically appear on the users screen. In an IOP deployment, Columbus OM
can send messages to users to tell them when their document has been printed, and
which printer was used.
You can:

control how long the message stays on screen

control whether the message closes automatically

display a list of recently received messages

check which zone you are registered in, and change it.

IOP Messenger must be installed on each computer to which you want to send
messages.
To

See

install IOP Messenger on a users


computer

Installing IOP Messenger below

enable Columbus OM to send messages Configuring Columbus OM to send


to IOP Messenger
messages on page 72.
send messages to IOP Messenger

Sending messages using IOP


Messenger on page 72.

receive messages by using


IOP Messenger

Receiving messages with


IOP Messenger on page 75.

control what the IOP Messenger


window looks like

Customizing IOP Messenger on


page 77.

Installing IOP Messenger


You must install IOP Messenger on each computer to which you want to sent
messages.
IOP Messenger can be installed:

by using the dialog boxes in the installation program

if you know the information that you want to put in the dialog boxes, in silent
mode. This mode is particularly suitable when you have to install IOP
Messenger on several computers.

at the same time as the other IOP desktop components: Columbus Printer
Driver and the Windows Gateway. For more information about how to do this,
see IOP desktop components on page 78.

Installing IOP Messenger by using the dialog boxes


1

Navigate to the folder that contains the IOP Messenger installation program.

Double-click the installation program file, and then follow the onscreen
instructions.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP Messenger

During the installation program, it asks for this information:


Property

Value

Zone Server

Type the name of the computer on which


Columbus OM is installed.

Zone Number

Type the port number that the uqserver uses, usually


2006. The installation program also asks for information
about backup instances, that is instances to be contacted
if the first one is not available. This information is
optional.

Use domain/user

To validate the user by their domain and username,


select this option. If your environment does not use
domains, clear this option.

Restrict user

To prevent the user from accessing the Columbus OM


configuration commands (that is, Settings, Quick
Switch, Launch Website, and Exit), select this option.

Installing IOP Messenger in silent mode


To install IOP Messenger in silent mode, that is without any dialog boxes
appearing, change to the folder that the installation program is in, and then type the
following command:
Syntax
filename "/qn ZONE_SERVER=server_name ZONE_PORT=number
MENU_STRING=\"string>\"
INSTALLDIR=folder
ZONE_SERVER1=server ZONE_PORT1=port
ZONE_SERVER2=server ZONE_PORT2=port
USE_DOMAIN=0|1"
Parameters
filename

The name of the installation program, for example:


ColumbusOM.Messenger5000.exe.
ZONE_SERVER=server_name

The name of the computer that the zone server is on. The default value is
LocalHost.
ZONE_PORT=number

The number of the TCP/IP port that the zone server uses. The default value is
2006.
MENU_STRING=\"string\"

The text of the option on the settings menu for which the default value is
Launch Website.

COLUMBUS OM INSTALLATION AND CONFIGURATION

71

72

CHAPTER 3

Columbus OM utilities

IOP Messenger

INSTALLDIR=folder

The folder in which you want to install IOP Messenger. The default value is
C:\Program Files\Macro 4\ColumbusOM Messenger.
ZONE_SERVER1=server
ZONE_PORT1=port
ZONE_SERVER2=server
ZONE_PORT2=port

The name and port numbers of any failover servers to be used. The default
value for the names is blank. The default value for the port numbers is 2006.
USE_DOMAIN=0|1

To validate the user by their domain and username, specify 1.


If your environment does not use domains, specify 0.

Configuring Columbus OM to send messages


You can:

change the communications port, if the default one (2009) is already used by
another program

specify the location of the IOP interface, enabling users to access it from the
IOP Messenger menu.

To set the port on which messages are sent


1

On the computer on which Columbus OM is installed, set the Message_Port


parameter in the system defaults file (config\default.tab ) to the port
number to be used.

On each computer on which IOP Messenger is installed, click the Start button
on the Windows Desktop, and then navigate to Programs Columbus OM.

Right-click Start Messenger, and then click Properties.

In the Target box, add the port number to the end of the command, for
example:
"C:\Program Files\Macro 4\ColumbusOM Messenger\uqmesser.exe" 2007

Click OK.

To specify the location of the IOP interface

To enable users to access the IOP interface from IOP Messenger, set the IOP_URL
parameter in the system defaults file (default.tab) to the interfaces URL.

Sending messages using IOP Messenger


To send messages to another computer by using IOP Messenger, use the xmessage
command on the computer on which Columbus OM is installed. You can:

type the command on the command line

use the command in a batch file or shell script

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP Messenger

use the command in a Columbus OM Action_On command or a dispatch


Command action.

Syntax
xmessage destination text
[UNIQ_MESSAGE|UNIQYESNO|NET_SEND|UNIXWRITE|EMAIL]

Parameters
destination

The destination of the message, one of:

a users operating system id

the IP address of a computer

(to send an email message) the email address.

text

The text of the message. If the text includes spaces, enclose it in quotation
marks.
To split a message over two or more lines, separate the lines with %%NL, for
example: "Your document has been printed on%%NLthe colour
printer".
To include a URL, start it with http:// or www.
UNIQ_MESSAGE|UNIQYESNO|NET_SEND|UNIXWRITE|EMAIL

The method by which you want to send the message:


To

Specify

use IOP Messenger

UNIQ_MESSAGE or UM

use IOP Messenger, and display the


message with Yes and No buttons

UNIQYESNO [uid] or UY [uid]

use a Windows netsend command

NET_SEND or NS

use a UNIX write command

UNIXWRITE or UW

send an email message (see also


Sending email messages below)

EMAIL or EM

uid is the number of an entry that is in the pending queue of the instance that
you are using to send the message.

When the user clicks a button, Columbus OM puts a value in the entrys
Server Info property.
If the user clicks

Server Info value

Yes

YESNO=Y

No

YESNO=O

To specify a default method, see Specifying a default method on page 74.

COLUMBUS OM INSTALLATION AND CONFIGURATION

73

74

CHAPTER 3

Columbus OM utilities

IOP Messenger

Sending email messages


To specify the email system by which the email messages are to be sent, set these
parameters in the system defaults file (default.tab):
Parameter

Value

SMTP_Domain text

The domain, for example, mycompany.com.

SMTP_Sender text

The email address from which the messages are sent, for
example, john@mycompany.com.

SMTP_Server text

The name of the computer that the mail system is on.

Specifying a default method


You can omit the method from the xmessage command, and use the default
method. The default method can be set in several places:
To specify a default
method for

Do this

all users

Set the Message_Type parameter in the system defaults


file (default.tab).

an individual user

Set the MessageType parameter in their user file:

Windows:
%UNIQDIR%\media\users\domain\userid.tab

UNIX:
%UNIQDIR%/media/users/userid.tab

Set the Message_Type parameter to one of:


UNIQ_MESSAGE
UNIQYESNO
NET_SEND
UNIXWRITE
EMAIL
UNIQ_WEB

Example
To send a message to a computer called MyPC01, use a command like this:
xmessage MyPC01 "Colour printer available again" UM

The message is displayed on MyPC01 like this:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP Messenger

Receiving messages with IOP Messenger


Starting IOP Messenger
IOP Messenger starts automatically when you start your computer. It appears as an
icon in the system tray.
If you have just installed IOP Messenger, you can start it manually: click the Start
button on the Windows Desktop, and then navigate to Programs Columbus
OM Start Messenger.
Displaying messages
Messages appear on your screen
automatically.
To change how long they stay on screen, see
Configuring IOP Messenger on page 76.
Displaying previous messages
To display previous messages, right-click the
IOP Messenger icon in the system tray, and
then click Recent messages.
Managing your print jobs
To

Do this

display a list of your


pending print jobs

Right-click the IOP Messenger icon, and then click


My Print Jobs.

delete a pending job from Right-click the IOP Messenger icon, and then click
the list
My Print Jobs. Right-click the job, and then click
Remove Job.
Using IOP features with IOP Messenger
These features are available if you are using IOP Messenger with a IOP
deployment.

Right-click the IOP Messenger icon in the system tray, and then do one of the
following:
To

Do this

display your current IOP zone

Click Current Location.

change to a different zone

Point to Quick Switch, and then click


a zone.

open the IOP interface

Click Launch Website.

COLUMBUS OM INSTALLATION AND CONFIGURATION

75

76

CHAPTER 3

Columbus OM utilities

IOP Messenger

Configuring IOP Messenger


1

Right-click the IOP Messenger icon in the system tray, and then click Settings.

Set the following properties for each instance. (The Primary tab is for the main
Columbus OM instance that you use; the Backup 1 and Backup 2 tabs are for
alternative instances that might be used if the primary instance is not available.)
Property

Description

Auto Acknowledge Closes the message window automatically after the


interval set by the Display Time property. If you do not
select this property, the message window displays until
you click OK.
Refresh Favourites

(Used with IOP deployments.) Updates the list of zones


that are displayed in the Quick Switch list. Use this if
you have changed the list of favourite zones.

Zone Server

The name of the computer on which Columbus OM is


installed.

ZonePort

The number of the port on which Columbus OM


listens.

Display Time

If you have selected Auto Acknowledge: The time for


which a message is displayed when it first appears.

Stopping IOP Messenger

If you do not want to receive any messages from IOP Messenger, right-click the
IOP Messenger icon in the system tray, and then click Exit.

Using the features


Some features of IOP Messenger are available only if you are logged in as the same
user who installed it.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP Messenger

Customizing IOP Messenger


Changing the appearance
You can change what IOP Messenger looks like: the windows, the buttons and the
system tray icon. To do this, replace the following bitmaps and icon files.
Put the files in the same folder as the IOP Messenger program file, uqmesser.exe.
Its default location is: C:\Program Files\Macro 4\ColumbusOM Messenger.
General message window

Filename

message_skin.bmp

Size

410 184 pixels

Transparency colour

vibrant pink (255, 0, 255)

Recent messages window

Filename

recent_skin.bmp

Size

410 256 pixels

Transparency colour

vibrant pink (255, 0, 255)

Buttons

OK button filenames

Yes button filenames

No button filenames

Size

unpressed

OK_button_up.bmp

mouse-over

OK_button_hover.bmp

pressed

OK_button_hover.bmp

unpressed

Yes_button_up.bmp

mouse-over

Yes_button_hover.bmp

pressed

Yes_button_hover.bmp

unpressed

No_button_up.bmp

mouse-over

No_button_hover.bmp

pressed

No_button_hover.bmp

Each button is 90 25 pixels.

System tray icon

Filename

messenger_icon.ico

Size

32 32 pixels

Changing the language


To translate the text that appears in messages and onscreen, edit this file:
OMMessenger_Translations.cfg

COLUMBUS OM INSTALLATION AND CONFIGURATION

77

78

CHAPTER 3

Columbus OM utilities

IOP desktop components

IOP desktop components


This section describes how to install all the IOP desktop components at once. The
IOP desktop components are: Columbus Windows Gateway, IOP Messenger and
the IOP Universal Driver.
The installation program runs in silent mode; that is, no dialog boxes appear.
You put the values would usually put in the dialog boxes in some configuration
files. The configuration files can be stored on a different computer from the one on
which you install the desktop component. This means that the same values can be
used for every installation, if required.
To install all the desktop components at once
1

Specify the values that you want to use for the desktop components by setting
the parameters in the configuration files:
Component

Configuration file

the installation program itself, and IOPSolutionConfig.cfg


the IOP Universal Driver

See

page 79

Windows Gateway

GatewayConfig.cfg

page 80

IOP Messenger

MessengerConfig.cfg

page 81

Copy the installation program to the computer on which you want to install the
desktop components.

Put the configuration files where they can be accessed from the computer on
which you want to install the desktop components.

On the computer, typing this command on the command line:


IOPSolutionPackage.msi /qn CONFIG_FILE_DIR=path

Replace path with the name of the folder in which you have put the
configuration files. Include the computer name, if appropriate, for example:
\\mycomputer2\myfiles.
While the installation program runs, ignore any dialog boxes about Unsigned
driver that appear. The installation programs handles these dialog boxes
automatically.
If there are any errors in configuration files, the installation program stops. It
reports the errors in log file called Solution_Install_Log.txt.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

IOP desktop components

Configuring the installation program: IOPSolutionConfig.cfg


Filename
IOPSolutionConfig.cfg

Parameters
You must include all these parameters in the file.
DESTINATION_DIR=folder

The main folder in which you want to install the desktop components. The
installation program puts each component in a separate subfolder of this main
folder.
Specify the full path of the folder, for example: c:\Program Files\Macro 4.
Do not include a slashmark at the end.
INSTALL_SOFTWARE_ONLY=TRUE|FALSE

To only install the software, specify TRUE.


INSTALL_AND_CONFIG=TRUE

To install and configure the software, specify TRUE.


GENERAL_FILES_LOCATION=folder

The path and name of the folder that the configuration files
(GatewayConfig.cfg, MessengerConfig.cfg, ompcl.cfg, ompcl.gdp,
ompcl.txt, and OMMessenger_Translations.cfg) are in. The files can be
on a different computer: if so, specify the path as \\computername\path.
UPDATE_GDP_FILE=TRUE|FALSE

To use your own version of the IOP Universal Drivers ompcl.gdp file, specify
TRUE. Put the file in the folder that is specified by the
GENERAL_FILES_LOCATION parameter.
To use the default ompcl.gdp file, specify FALSE.
UPDATE_CFG_FILE=TRUE|FALSE

To use your own version of the IOP Universal Drivers ompcl.cfg file, specify
TRUE. Put the file in the folder that is specified by the
GENERAL_FILES_LOCATION parameter.
To use the default ompcl.gdp file, specify FALSE.
UPDATE_DRIVER_LANG_FILE=TRUE|FALSE

To use your own version of the IOP Universal Drivers language file
(ompcl_txt.cfg), specify TRUE. Put the file in the folder that is specified by
the GENERAL_FILES_LOCATION parameter.
To use the default language file, specify FALSE.
UPDATE_LANG_FILE=TRUE|FALSE

To use your own version of the IOP Messenger language file


(OMMessenger_Translations.cfg), specify TRUE. Put the file in the folder
that is specified by the GENERAL_FILES_LOCATION parameter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

79

80

CHAPTER 3

Columbus OM utilities

IOP desktop components

To use the default IOP Messenger language file, specify FALSE.


LOG_LOCATION=folder

The folder in which Columbus OM Gateway puts its log files (for example,
c:\logs).
ACCOUNTING_FILE=filename

The file that Columbus OM Gateway uses for Columbus Accounting (for
example, ACCOUNTING.txt).
SPOOLER_NAME=text

The name of the Windows Print Spooler service (for example, Print
Spooler).
PRINTER_NAME=text

The name of the default IOP printer. The default name is IOP.
PORT_NAME=text

The name of the Columbus OM port to create.


START_MESSENGER=YES|NO
YES starts Columbus OM Messenger after it has been installed.

Configuring the Gateway: GatewayConfig.cfg


Filename
GatewayConfig.cfg

Parameters
INSTANCE=text

The name of the Columbus OM instance that the Gateway will send
documents to.
For an IOP deployment, specify the name of the zone server instance.
HOST=text

The name of the computer that the instance is on.


PORTNO=text

The port number that the instance uses.


MEDIUM=text

The name of the Columbus OM medium that is to be applied to documents


that are sent to the instance.
PRINTER=text

The name of the printer to be used.


TICKET=text

For a basic Columbus OM system, leave blank.


For an IOP deployment, specify IOP (in UPPERCASE).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

INSTANCE1=text
HOST1=text
PORTNO1=number
MEDIUM1=text
PRINTER1=text
TICKET1=text

Columbus OM utilities

IOP desktop components

INSTANCE2=text
HOST2=text
PORTNO2=number
MEDIUM2=text
PRINTER2=text
TICKET2=text

The properties for the first and second failover instances.


LOCALPORT=text

The name of the port to be used if you are printing locally (for example, LPT1).
MIRRORENABLE=Yes|No

Yes enables the local port.


MIRRORPJL=Yes|No

If the printer can return PJL information, set to Yes.


SUMMARYONLY=Yes|No

To send the document to Columbus OM, specify No.


To send only the summary information to Columbus OM, specify Yes.
ZONESERVER=Yes|No

If the instance is the zone server for the IOP deployment, specify Yes.
ACCOUNTING=text

The name of the accounting medium.


RETAINDAYS=Yes|No

To delete the file after it has been completed, specify Yes.


USERONLY=Yes|No

To validate against both the domain and the name part of a username (for
example, mydomain\john), specify No.
To validate against only the name part, and ignore the domain, specify Yes.
ENCRYPTION=None|128|192|256
ENCRYPT_DISK=None|128|192|256

See Encrypting documents on page 67.

Configuring Columbus OM Messenger (MessengerConfig.cfg)


Filename
MessengerConfig.cfg

Parameters
ZONE_SERVER=text
ZONE_PORT=number

The name of the computer that the zone server is on, and the port number that
it uses.

COLUMBUS OM INSTALLATION AND CONFIGURATION

81

82

CHAPTER 3

Columbus OM utilities

IOP desktop components

ZONE_SERVER1=text
ZONE_PORT1=number

The name of the server that the first back-up instance is on, and the port
number that it uses.
ZONE_SERVER2=text
ZONE_PORT2=number

The name of the server that the second back-up instance is on, and the port
number that it uses.
MENU_STRING=text

Text to replace the Launch website menu command.


USE_DOMAIN=YES|NO

If the IOP deployment does not use the domain, specify NO.
RESTRICT_USER=YES|NO

If you do not want users to be able to configure Columbus OM Messenger or


change their zone, specify YES.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus OM PC Printer Channel

Columbus OM PC Printer Channel


The Columbus OM PC Printer Channel enables Columbus OM to send output to
a printer that is directly connected to a Windows PC.
The PC Printer Channel is installed on the PC. It listens for requests sent by
Columbus OM, and then prints them on a local printer.

Installing the Columbus OM PC Printer Channel


1

Windows NT/2000: Log on with Administrator access rights.

In Windows Explorer, navigate to the folder that the PC Printer Channel


installation program is in, and then double-click the setup.exe file.

Follow the onscreen instructions.

To upgrade the PC Printer Channel

Follow the instructions for installing the PC Printer Channel (see above).

Configuring the PC Printer Channel


This section describes how to configure the PC Printer Channel so that
Columbus OM can connect to it, and so that the PC Printer Channel can connect
to the printers that are on the PC.
On the PC running the PC Printer Channel
1

Click the Windows Start button, and then click Programs


Channel.

On the Server menu, click Configure.

Select Auto Start.

COLUMBUS OM INSTALLATION AND CONFIGURATION

PC Printer

83

84

CHAPTER 3

Columbus OM utilities

Columbus OM PC Printer Channel

Do one of the following:


To

Do this

use TCP/IP access

Click TCP/IP, and then click Configure.


Specify the port on which the PC Printer Channel
listens for print requests from Columbus OM (for
example 2001: see Network connectivity on
page 26), and then select the printer that it is to use
for those requests.

use LPD/LPR access

Click LPD/LPR, and then click Configure.


Click Add, and then specify a name for the queue,
and select the printer that it is to use for requests sent
to that queue.

If you want the documents to be sent from Columbus OM in compressed


format, you must enable the PC Print Channel to uncompress the documents
before it prints them.
To do this, select Decompression Enabled, and then type the command to
uncompress the documents. For example, if Columbus OM uses gzip -c to
compress the documents, the command to uncompress the documents is
gzip -c -d.

Click OK.

In the Configuration dialog box, click Save.


The Save As dialog appears.

Type a name for the configuration file, and then click Save.

Starting the PC Printer Channel


1

On the Server menu, click Start.

Click the Minimize (not Close) button.

To make the PC Printer Channel start automatically when the PC is started,


add the shortcut from the PC Printer Channel section to the Windows Startup
menu. This shortcut includes a reference to the saved configuration file
uqwinvts.uwv.

To enable Columbus OM to send requests to the PC Printer Channel, see


Configuring Columbus OM to use the PC Printer Channel on page 85.

Connecting to multiple printers


To connect to multiple local printers on the PC:

If you are using TCP/IP: Create a separate port and configuration file for each
printer, and start multiple instances of the PC Printer Channel, each
referencing one of the configuration files see Using the PC Printer Channel
configuration files below.

If you are using LPD/LPR: Create a separate queue for each printer. You need
only one instance of the PC Printer Channel (which always listens on the
LPD/LPR port 515).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus OM PC Printer Channel

Using the PC Printer Channel configuration files


To specify the configuration file that an instance of the PC Printer Channel is to
use, add these parameters command line:
-dir: path

The full path of the folder that the configuration file is in. The default value is
the folder that the PC Printer Channel application is in.
-file: file

The name of the configuration file.

Configuring Columbus OM to use the PC Printer Channel


To configure Columbus OM to send requests to the PC Printer Channel, do the
following:
On the host running Columbus OM
1

In Columbus OM, create a printer server. Use a name which relates to the
PC/printer combination.

Set the servers device to:


NETWORK host port

where host is the PC running the PC Printer Channel and port is the port
defined on that PC. If you are using LPD/LPR, the port number is 515.
3

Set the servers driver to one of the following


If you are using

Set the driver to

TCP/IP

printout

LPD/LPR

lprout %UID queuename

where queuename is the corresponding queue defined


on the PC.
4

If you want the documents to be sent to the PC Printer Channel in compressed


format, set the printer servers Input_Filter parameter to the compression
command, for example: gzip -c.

If there are multiple printers on the PC, define multiple printer servers, each
using a different port or queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

85

86

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

Columbus OM Novell Gateway


The Columbus OM Novell Gateway enables:

Columbus OM to send output to NetWare queue-based or NDPS printers

output from NetWare print queues to be sent to Columbus OM.

The Columbus OM Novell Gateway runs on a Novell NetWare platform.

Installing the Columbus OM Novell Gateway


Preparing to install
Check your environment before running the installation program:

The NetWare host must be running Novell NetWare version 5.1 (Support Pack
Revision 04) or higher, with NDPS patch ndp21p4.exe.

The NetWare host must be running TCP/IP in addition to IPX/SPX. Make


sure that TCP/IP is loaded and configured before attempting to install the
Columbus OM Novell Gateway.

The NetWare host must have been updated with the latest Novell patches.
See http://support.novell.com/misc/patlst.htm for more information.

Hosts sending print requests to the Columbus OM Novell Gateway must be


running a Columbus OM print installation version 4.105 or higher.

Running the installation program


1

Log on to the NetWare domain as the administrative user admin.

Insert the CD-ROM. NetWare usually mounts the CD-ROM automatically. if


it does not, type cdrom on the NetWare console.

Type:
load nwconfig.

Select Product options

To specify the CD-ROMs Columbus OM Novell Gateway directory, press


Escape, and then press F3.

Type the path in the format volume:\directory., and then press Return.

Install a product not listed, and then press Return.

The volume is usually MACRO4 and directory must be given in 8 character


DOS format.
7

On the Columbus OM Novell Gateway Main menu, select Install for version
5.x of NetWare, and then press Return. Wait for the Installed successfully
message.

Next, see Post-installation setup on page 87.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

Installed files
The following files are installed on the NetWare host:
File

Description

\macro4\config.tab

Configuration file for the Columbus OM Novell


Gateway host. See Setting configuration values on
page 88.

\macro4\nqueue.tab

Sample NetWare queue definitions. See Defining the


connection to Columbus OM on page 90.

\macro4\history2

Temporary data file to hold details of outstanding


print requests.
If you are upgrading from UniQ LanCom to the
Columbus OM Novell Gateway, allow UniQ
LanCom to continue running until its version of the
history file (\macro4\history) is empty. If you do not
allow the file to be emptied, any entries in the file will
not be acknowledged and will remain in the transfer
state on the originating system.

\macro4\dayDD.log

Columbus OM Novell Gateway writes a daily log file,


where DD is the day of the month (0131). The same
file is reused on the same day each month; any existing
contents are lost.

\system\uqlc.nlm

Columbus OM Novell Gateway administration utility.

\system\m4cngate.nlm

Columbus OM Novell Gateway server.

Post-installation setup
Updating the hosts file
On the NetWare host, edit the file \etc\hosts to include an entry for the
NetWare host itself:
ip_address

nw_host

Parameter

Value

ip_address

The IP address of the NetWare host (for example 137.46.57.221).

nw_host

The name of the NetWare host.

Updating the services file


On the NetWare host, edit the file \etc\services to include an entry for the
uniqcs network service:
service

port/tcp

COLUMBUS OM INSTALLATION AND CONFIGURATION

87

88

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

Parameter

Value

service

The network service name should generally be set to uniqcs, and


must match the entry in \macro4\config.tab see Setting
configuration values on page 88.

port

The port number should generally be set to 2006, and must match
the value specified on the Columbus OM hosts see Network
connectivity on page 26.

The Columbus OM Novell Gateway replaces UniQ LanCom, some versions of


which used a service of uqnet, with a typical port number of 2005. Any such entry
can be deleted from \etc\services.
Setting configuration values
Edit the \macro4\config.tab file to define the configuration parameters.
Parameter

Value

Hostname

The name of the NetWare host.

NetWare

Set to 5.

NWDS

Must be set to YES to use the NetWare Directory Services.

Novell_Username

Username for NDS logon; usually admin. See Specifying


the NDS logon on page 89.

Novell_User_
Password

Encrypted password for NDS log on. See Specifying the


NDS logon on page 89.

Server

Set to print.

Service

Network service for NetWare/Columbus OM


communications; should usually be set to uniqcs. See
Updating the services file on page 87.

Owner

Username for Columbus OM log on; usually uniq.

Process_Held_
Entries

YES to transfer queue entries from NetWare to a

Banners

Columbus OM print instance even if their status is Held, NO


to retain such entries in the NetWare queue.
YES to print NetWare banners on jobs transferred from a
Columbus OM print instance to a queue-based printer, NO to

omit banners.
Scan_Interval

Frequency (in seconds) at which to check NetWare queues


for entries waiting to be transferred to a Columbus OM print
instance.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

Parameter

Value

Banner1, 2, 3

The first, second and third lines of the banner displayed at


the top of the statistics screen. The strings must be specified
inside quotes "...". If these parameters are omitted, a
default banner is produced which uses line drawing
characters (for example, box corners). Include the Bannerx
parameters only if your terminal supports line drawing
characters.

Normal_Attr

Display attributes. The default value is 31 (bits 00011111)


brilliant white text on a blue background. See Display
attributes below.

Display attributes

The value of the Normal_attr parameter is an integer in the range 0-255, used as a
bit-mask.

Bit

Decimal

Effect if set

128

Makes the text blink.

64

Adds RED to the background colour.

32

Adds GREEN to the background colour.

16

Adds BLUE to the background colour.

Increases the text brilliance.

Adds RED to the text (foreground) colour.

Adds GREEN to the text colour.

Adds BLUE to the text colour.

Specifying the NDS logon


You must define the username and password used to log on to NDS (NetWare
Directory Services).
1

On the NetWare console, type load uqlc.

On the Columbus OM Novell Gateway menu, select Configure


Change NDS password; you are prompted to enter a username and
password:
Username: username
Password: password

Enter appropriate values: press Return after each field. The password is not
echoed.

COLUMBUS OM INSTALLATION AND CONFIGURATION

89

90

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

Press ESC, and then save the data. The values that you enter here are written to
the file \macro4\config.tab.

Checking the host name


The name of the NetWare host is held in several locations; the name must be the
same in all of them.
1

On the NetWare console, type load uqlc.

On the Columbus OM Novell Gateway menu, select


Configure Check host name. The four values shown must be identical
(upper/lowercase differences do not matter).

Press ESC to exit.

Defining the connection to Columbus OM


To provide TCP/IP access between the Columbus OM system and your Novell
NetWare PC, perform these steps.
On the PC running Novell NetWare
1

Edit the \etc\hosts file (again) to include an entry for the Columbus OM
host:
ip_address

cd_host

Parameter

Value

ip_address

The IP address of the Columbus OM host (for example


137.46.57.44).

cd_host

The name of the Columbus OM host.

This step enables M4CNGATE to send ACKs back to the originating system.
2

If you want to send print jobs from selected NetWare queues to


Columbus OM, do the following:

Create a dummy NetWare print queue, but do not associate a print server
with it.
Edit the \macro4\nqueue.tab file to reference the dummy print queue.
Add an entry of the form:

local_queue

cd_host

cd_instance

cd_printer

Parameter

Value

local_queue

The name of the NetWare print queue from which print


jobs are to be sent to Columbus OM. This is the queue
created in step n.

cd_host

The name of the Columbus OM host.

cd_instance

The identification of the print queue on cd_host.

cd_printer

The name of the Columbus OM printer that will print


transferred jobs.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

On the host running Columbus OM


1

Edit the file %SystemRoot%\system32\drivers\etc\hosts (Windows) or


/etc/hosts (UNIX) to include an entry for the NetWare host:
ip_address

nw_host

Parameter

Value

ip_address

The IP address of the NetWare host (for example


137.46.57.221).

nw_host

The name of the NetWare host.

Edit the file %SystemRoot%\system32\drivers\etc\services (Windows)


or /etc/services (UNIX) to include an entry for the uniqcs network service
(this entry will probably already exist).
service

port/tcp

Parameter

Value

service

The network service name should generally be set to


uniqcs.

port

The port number should generally be set to 2006, and


must match the value specified for client communication
on the NetWare host. See Network connectivity on
page 26.

Edit the file %UNIQDIR%\config\remote.tab (Windows) or


$UNIQDIR/config/remote.tab (UNIX) to add an entry of one of these forms:
local_printer
local_printer
local_printer

nw_host:nw_queue
nw_host:nw_queue/nw_server
nw_host:ndps_printer

Parameter

Value

local_printer

The name by which the remote NetWare printer is to be


known to Columbus OM users.

nw_host

The name of the NetWare host.

nw_queue

If you are using queue-based printers on Novell, this is the


identification of the print queue on nw_host.

nw_server

If there is more than one print server servicing the


nw_queue, you can optionally specify which to use here.

ndps_printer

If you are using Novell NDPS printers, the identification of


the printer on nw_host.

COLUMBUS OM INSTALLATION AND CONFIGURATION

91

92

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

Starting and stopping the Columbus OM Novell Gateway


Starting the Columbus OM Novell Gateway from the command
line
On the NetWare console:
1

If you are using NDPS, ensure that you have started the NDPS Broker and
started the NDPS Manager for your NDPS printers.

To start the Columbus OM Novell Gateway manually, type:


load m4cngate

Details of current activity are shown on the Columbus OM Novell Gateway


statistics display:
Connection Info

Request Info

Current Status

Total Active threads


:
Total Connections serviced:
Current connections
:

1
0
0

Outstanding (history)
:
Successful
:
Failed
:
Transferred to Columbus OM:

0
0
0
0

Waiting for next request

Field

Description

Total Active threads The number of run lines (including one for this

display).
Total Connections
serviced

The number of requests handled this session (reset


to zero whenever M4cngate is loaded).

Current connections

The number of connections currently being


serviced.

Outstanding
(history)

The number of print jobs transferred from the


Columbus OM print facility which are waiting to be
dealt with by NetWare.

Successful

The number of successful requests handled by the


Columbus OM Novell Gateway.

Failed

The number of unsuccessful requests handled by


the Columbus OM Novell Gateway.

Transferred to
Columbus OM

The number of print jobs that have been transferred


from NetWare to the Columbus OM print facility.

Current Status

The current status of m4cngate.

Press ALT+ESC to switch to another display.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

Starting the Columbus OM Novell Gateway automatically


To start the server automatically, add this line near the end of file \autoexec.ncf
(or \system\autoexec.ncf):
load m4cngate

Stopping the Columbus OM Novell Gateway


To stop the server, type the following command on the server console:
unload m4cngate

The keyboard might remain locked for a short while, and then the server process
terminates.

Maintaining the Columbus OM Novell Gateway


To upgrade Columbus OM Novell Gateway
1

At the command prompt, type:


unload m4cngate

Type:
load nwconfig

From the menu, select Product Options, and then select Install a product
not listed.

Specify the directory from which to install.

At the main menu, select Upgrade for version 5.x of Netware.

To delete Columbus OM Novell Gateway


1

At the command prompt, type:


unload m4cngate

Type:
load nwconfig

From the main menu, select Deinstall for version 5.x of Netware.

COLUMBUS OM INSTALLATION AND CONFIGURATION

93

94

CHAPTER 3

Columbus OM utilities

Columbus OM Novell Gateway

COLUMBUS OM INSTALLATION AND CONFIGURATION

95

CHAPTER 4

Chapter 4

Managing servers

Columbus OM features are controlled by programs called servers. For example,


the printing feature is controlled by a server called printmaster. To use a feature,
you must configure the server that controls it.
The servers that provide the main features of Columbus OM are created and
configured when you install Columbus OM itself. The servers that provide the less
commonly-used features must be created and configured manually. To change the
way that a server works, you can change its configuration. For more information,
see Adding servers on page 98 and Configuring servers on page 99.
For a server to provide its functionality, it must be running. Servers can be
configured to start automatically or manually. To start a server, see Starting
servers on page 101.
To check whether a server is running, see Monitoring servers on page 103.

COLUMBUS OM INSTALLATION AND CONFIGURATION

96

CHAPTER 4

Managing servers

Server types

Server types
Columbus OMs features are provided by the following servers. For more
information about how to use and configure each server, see the appropriate
section.
Core features
Feature

Server

See

Print job sequencing

printmaster

page 125

Printing documents

printer

page 129

Enhanced printing

xprinter

page 188

Monitoring printer status

statserver

page 439

Caching status feedback

uqsfcache

page 441

Control processing

dispatch

page 320

Feature

Server

See

Integration with Columbus Accounting

accserver

page 572

Integration with Columbus DW

crserver

page 344

Integration with other archive applications

aspserver

page 348

Integration with formatter applications

dcsserver

page 580

Integration with network management applications

evserver

page 438

Caching SAP callbacks

uqsapcache

page 552

Communication with other programs

xmlserver

page 598

Feature

Server

See

Faxbox modems

faxbox

page 483

Managing fax entries

faxmaster

page 485

Ascom Hasler modems

haslerfx

page 486

Connecting to fax modems

pfax

page 490

Printing fax documents

haslerpr

page 489

Feature

Server

See

Connecting with Columbus OM instances on other


computers

netmaster

page 114

Integration with other programs

Sending and receiving faxed documents

Managing multiple instances

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 4

Managing servers

Server types

Feature

Server

See

Copying files between instances

repmaster

page 401

Communication between hosts

uqserver

page 403

Feature

Server

See

Processing files from scanned folders

filein

page 234

Handling data/command files from other computers

ftserver

page 232

Replace the UNIX lp daemon

lpdserver

page 227

Handling incoming mail messages

mailin

page 459

Feature

Server

See

Send documents by email

mailer

page 458

Feature

Server

See

Synchronize IOP users with LDAP

ldapserver

page 516

Using SecureJet devices

SecureJet

page 528

Input channels

Output channels

IOP features

COLUMBUS OM INSTALLATION AND CONFIGURATION

97

98

CHAPTER 4

Managing servers

Adding servers

Adding servers
1

In Columbus OM Explorer, navigate to: Advanced tab


Columbus OM Servers Servers menu New.

Set the properties:


Property

instance icon

Value

Server name A name to identify the server. The name can include letters,
numbers, and underscore characters. It cannot include spaces.
Attributes

To change the value of an attribute, click its name, and then


type the value. For more information about the attributes, see
page 96.

Autostart

Starts the server automatically when Columbus OM starts.

Autostop

Stops the server automatically when Columbus OM stops.

Display at
command
prompt

Includes the server in the list when you use an syq command;
for more information, see Command line on page 103.

Click OK.

To enable the server so that it can be used, click it, and then click the Enable
Server toolbar button.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 4

Managing servers

Configuring servers

Configuring servers
Command line
Navigate to the servers folder: %UNIQDIR%\servers\servername, and then edit
the config.tab file.
Columbus OM Explorer
Navigate to: Advanced tab
Modify.

Columbus OM Servers

server

Servers menu

Refreshing the server

If your system is set up to refresh servers automatically when you change their
configuration, the change takes place immediately. See Refreshing servers
automatically below.

If your system is set up to refresh servers only when they start, you must stop
the server and then restart it. See Starting servers on page 101.

Refreshing servers automatically


To change when Columbus OM refreshes servers, use the Auto_Refresh
parameter in the system defaults file (default.tab).
To

Set this parameter to

load the changes immediately

Yes

load the changes when you restart the server

No

This parameter affects these servers:


dcs, dispatch, filein, lpdserver, netmaster, printer, printmaster,
statserver, uqserver, uqsfcache, xmlserver, xprinter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

99

100

CHAPTER 4

Managing servers

Configuring servers

dcs server: If you change the Outgoing or StatusCheck parameters for the
dcs server, the server does not reload its configuration, because these

parameters are fundamental to how it operates. To see the effect of changing


these parameters, you must stop the server and then restart it as usual.

xprinter also monitors the blockact.tab file, and reloads it if it changes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 4

Managing servers

Starting servers

Starting servers
Starting servers manually
Columbus OM Explorer
Advanced tab instance icon
Server
toolbar button.

Columbus OM Servers

server icon

Start

Command line
To

Use

start a server

syq -INITIATE|-i server

start selected servers

syq -ALL_INITIATE|-ai

To include a server when you use this command, set its


AI? property to YES in the servers.tab file (see
servers.tab: List of servers on page 104).

Starting servers automatically


Microsoft Windows
When you install Columbus OM, the servers are set up as services that
automatically start when Microsoft Windows starts.
UNIX
1

Add an syq command to the startup file (see Stopping servers below).

Make sure that root has:

the Columbus OM environment variable $UNIQDIR set

the $UNIQDIR/programs/commands directory in its PATH.

If you are using a command to start or stop selected servers, specify which
servers to include by following the rest of these steps:
3

In Columbus OM Explorer, click the icon for the instance.

On the Maintenance menu, click Servers.

Click a server, and then click either (or both of) Autostart and Autostop.

Click OK.

COLUMBUS OM INSTALLATION AND CONFIGURATION

101

102

CHAPTER 4

Managing servers

Stopping servers

Stopping servers
Columbus OM Explorer
Navigate to: Advanced tab instance icon
icon Stop Server
toolbar button.

Columbus OM Servers

server

Command line
To

Use

stop a server

syq -TERMINATE|-tn server

stop a server, but wait before


continuing

syq -TERMINATE_WAIT|-tnw server [time]


time specifies how long Columbus OM waits:
freq/count Check server status every freq
seconds. Continue after count

checks, or when server has


terminated.

stop selected servers

freq

Check server status every freq


seconds. Continue only when
server has terminated.

/count

Check server status every ten


seconds. Continue after count
checks, or when server has
terminated.

(if time is
omitted)

Check server status every ten


seconds. Continue only when
server has terminated.

syq -ALL_TERMINATE|-atn

To include a server when you use this


command, set its AT? property to YES in the
servers.tab file (see servers.tab: List of
servers on page 104).
stop selected servers, but wait
before continuing

syq -ALL_TERMINATE_WAIT|-atnw [time]

cleanly stop a specific server

uqstop

cleanly stop all servers

uqshutdown See uqstop and uqshutdown

To include a server when you use this


command, set its AT? property to YES in the
servers.tab file (see servers.tab: List of
servers on page 104).
See uqstop and uqshutdown
commands on page 106.
commands on page 106.

stop a specified Columbus OM uqkill


server or printer driver

See uqkill command: Stopping


servers and printer drivers on
page 105

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 4

Managing servers

Monitoring servers

Monitoring servers
Displaying the status of servers
Columbus OM Explorer
Navigate to: Advanced tab

instance icon

Columbus OM Servers.

A green icon indicates that the server is running.

A red icon indicates that the server is not running.

Command line
To

Use

display the status of a server

syq -STATUS|-s server

display the status of selected servers

syq -ALL_STATUS|-as

display the status of selected active


servers

syq -ALL_ACTIVE|-aa

To include a server when you use this command, set its AS? property to YES in the
servers.tab file (see servers.tab: List of servers on page 104).

Server log files


File

Location and description

General processing
activity

%UNIQDIR%\servers\server\dayDD.log
DD is the day of the month that the log file covers
(day01.log, day02.log, and so on, up to day31.log).

Each days log file is retained for one month.


Standard output
messages

%UNIQDIR%\servers\server\activity.log

The file contains messages that have occurred since the


server was last started.

Standard error stream error.log


messages
The file contains messages that have occurred since the
server was last started.

COLUMBUS OM INSTALLATION AND CONFIGURATION

103

104

CHAPTER 4

Managing servers

Reference

Reference
servers.tab: List of servers
The servers.tab file contains information about all the servers in an
Columbus OM instance, including:

the name and type of server


whether it starts and stops when you use the syq command with an ALL
option.

File location and name


%UNIQDIR%\servers\servers.tab

Content
The file contains one line for each server, with these fields:
Field

Description

Name

The name of the server.

Id

An internal number that indicates the type of server:

Program

The program that the server uses.

AI?

YES|NO
YES starts the server when you use an syq -ALL_INITIATE
command.

AT?

YES|NO
YES stops the servers when you use an syq -ALL_TERMINATE
command.

AS?

YES|NO
YES includes the server when you use an syq -ALL_STATUS.

Master?

YES|NO
YES if it is a process server; NO if it is a printer server.

Example
# Name
# --------------#
printmaster
statserver
ftserver
lpdserver
netmaster
uqserver

Id Program
AI? AT? AS? Master?
-- ------------- --- --- --- ------10
12
3
4
11
2

printmaster
statserver
ftserver
lpdserver
netmaster
uqserver

Yes
Yes
No
No
Yes
Yes

Yes
Yes
Yes
Yes
Yes
Yes

Yes
Yes
No
No
Yes
Yes

Yes
Yes
Yes
Yes
Yes
Yes

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 4

Managing servers

Reference

Server numbers
Number

Server type

netserver

uqserver

ftserver

lpdserver

batchmaster

faxmaster

telexmaster

faxprint

10

printmaster

11

netmaster

12

statserver

17

dispatch

18

dcs

19

asp

21

uqsfcache

22

uqsapcache

uqkill command: Stopping servers and printer drivers


The uqkill command stops a specified Columbus OM server or printer driver.
Syntax
uqkill servername ["SERVER"|"DRIVER"]
[-DISABLE] [-GROUP] [-REPORT]
[-NO_BANNER] [-NO_WARNING] [-QUEUE_NAME instance]
[-SET_USER username] [-SILENT] [-VERBOSE]

Parameters and options


servername

The name of the server or driver to be stopped.


"SERVER"|"DRIVER"

To stop a server such as netmaster, use SERVER.


To stop a printer server such as printout, use DRIVER.
The default is SERVER.
-DISABLE|d

Disables the server before stopping it.

COLUMBUS OM INSTALLATION AND CONFIGURATION

105

106

CHAPTER 4

Managing servers

Reference

-GROUP|g

(UNIX only.) Also stops any operating system child processes that are
associated with the server.
-REPORT|r

Displays the servers process id, but does not stop it.
-NO_BANNER
-NO_WARNING
-QUEUE_NAME instance
-SET_USER username
-SILENT
-VERBOSE

See Common parameters on page 602.

uqstop and uqshutdown commands


To stop servers cleanly (that is, wait for them to finish processing, and then stop
them), use these commands:
Syntax
To

Use

stop a server

uqstop [-su user] server

stop all servers (including printer


servers)

uqshutdown [-su user]


[option...]

If the command has no effect, it indicates that you are not authorized to use it; try
again, including the -su user option, replacing user with user name of a
Columbus OM implementor or administrator.
To use this form of the command, your user name must be in the su_opt file.
Options
-NO_BANNER|-nb
-NO_WARNING|-nw
-QUEUE_NAME|-qn instance
-SET_USER user
-SILENT|-si

See Common parameters on page 602.

COLUMBUS OM INSTALLATION AND CONFIGURATION

107

CHAPTER 5

Chapter 5

Configuring a
Columbus OM printing
environment
Columbus OM supports several types of print environment: most installations use
a combination of the different types.
Local printing
Local printing enables users to print documents on printers that are controlled by
the instance to which they are connected.
Users add entries to the Columbus OM pending queue, which is monitored by the
printmaster server. It looks for requests that are to be printed on local printers.
When it finds one, it sends the document to the printer. When the printer has
finished processing the document, printmaster moves it out of the pending queue
and into the completed queue.

Columbus OM
Explorer

Columbus OM
pending queue
printmaster

printer

completed queue

The printmaster server is configured for you when you install the Columbus OM
print instance. However, you might need to change the configuration to meet the
your requirements: see Configuration for local printing on page 111.
Distributed printing
Distributed printing enables users to print documents on printers that are
controlled by Columbus OM print instances other than the one to which they are
connected. These printers are known as remote printers.

COLUMBUS OM INSTALLATION AND CONFIGURATION

108

CHAPTER 5

Configuring a Columbus OM printing environment

Users add entries to the Columbus OM pending queue, which is monitored by the
netmaster server. It looks for requests that are to be printed on remote printers.
When it finds one, it sends the request to the instance that controls the printer. The
request is added to that instances pending queue, and then that instances local
printing environment processes the document. The printmaster server sends it to
the printer. When the document has finished, the remote printer sends a message
back to netmaster, and then netmaster moves the document out of the pending
queue and into the completed queue.

Columbus OM
Explorer

HOST A
pending queue

HOST B
pending queue
printmaster

completed
queue

printer

completed
queue

To set up a distributed print environment, you must create a list of the remote
printers that you want users to have access to. netmaster is configured for you
when you install the Columbus OM print instance, but you might need to change
its configuration to meet your requirements. See Configuration for distributed
printing on page 113.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Combining local and distributed printing


Many installations use a combination of local and distributed printing. For
example, some use one instance only for distributing print requests, and all the other
instances for actually printing them.

Columbus OM
Explorer

HOST A
Columbus OM

HOST B
Columbus OM

printers

HOST C
Columbus OM

printers

HOST D
Columbus OM

printers

To create an environment like this, you set up a distributed printing environment


on Host A, and local printing environments on Host B, Host C and Host D.
Intercepting remote lp print requests
Columbus OM can intercept print requests that users make using the standard
UNIX lp command, and add those requests to its own queue.
See Converting lpr/lpd requests to Columbus OM print entries on page 227.
Transferring documents from hosts that do not have the
Columbus OM print facility installed
See Transferring documents from other hosts into Columbus OM on page 232.

COLUMBUS OM INSTALLATION AND CONFIGURATION

109

110

CHAPTER 5

Configuring a Columbus OM printing environment

Setting parameters

Setting parameters
To configure Columbus OM, you must set parameters to values.

Some parameters affect the entire Columbus OM instance. To set these


parameters, see Setting system default parameters below.

Some parameters belong to individual programs (called servers) and affect only
that server. For more information, see Configuring servers on page 99.

Some parameters can be set at both instance level and server level. In this case,
the parameter at server level overrides the same parameter set at instance level.
This means that you can set a value that is suitable for most servers at instance
level, and then configure an individual server to use a different value if
required.

Setting system default parameters


Command line
Edit this file in a text editor:
%UNIQDIR%\config\default.tab

Columbus OM Explorer
1

Navigate to: Advanced tab


Defaults tab Advanced.

Click

instance icon

View menu

Options

(plus sign) next to the group that the parameter is in.

The name of a parameter indicates which group it is in. For example, the
AEQ_Default and AEQ_Index parameters are in the AEQ group.
3

Click the parameter, and then set the value you want.

Click OK.

Example default.tab
# Parameter
# ---------------------Address
Medium
Monitoring
AEQ_Default
AEQ_Index
Print_Index
APQ_Val_Attribs
APQ_Val_Dest
Auto_Purge
Auto_Archive
Auto_Extend
Highest_UID
...

Value
-------------------------------SalesPr1
print
ON
stdin
No
No
No
No
0
0
0
99999

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for local printing

Configuration for local printing


Local printing enables users to print documents on printers that are controlled by
the instance to which they are connected. It is managed by the printmaster
server.
Configuring printmaster
printmaster is created and configured when you install Columbus OM. The

parameter that you are most like to change controls how often it scans the queue for
new entries:
Parameter

Value

Scan_Interval

The interval between scans (a number of seconds).


The default interval is every 5 seconds.

For information about the other parameters, see page 125.


For information about how to set the configuration parameters, see Configuring
servers on page 99.

Processing entries with multiple servers


You can process entries with more than one server: for example, after printing an
entry (by using the printer server), you could then archive it (by using the archive
server). To do this, you can change what happens when an entry completes.
Usually when an entry completes, Columbus OM moves it to the completed
queue. You can change this so that Columbus OM leaves the entry in the pending
queue, changes its status back to New, and also changes its medium so that it gets
processed by a different server.
To enable this feature, set the Completion_Medium parameter in the system
defaults file (default.tab).

To process an entry with two servers (for example, to print an entry, and then
archive it), all that you have to do is set this parameter. For more information,
see Example: Processing an entry with two servers below.

To process an entry with multiple servers (for example, to print an entry, fax it,
and then archive it), set this parameter, and use it with the dispatch features.
For more information, see Dispatch example: Processing with multiple servers
on page 313.

How the Completion_Medium parameter affects processing


If the Completion_Medium parameter is set, when an entry completes
Columbus OM sets the entrys status to New, leaves it in the pending queue, and
then changes its medium to the value that is specified. The entry will then be
processed by the server that uses that medium.
Entries that are added with their medium already set to the one specified by this
parameter are not affected; when they complete, Columbus OM sets their status to
Completed, and then moves them to the completed queue, as usual.

COLUMBUS OM INSTALLATION AND CONFIGURATION

111

112

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for local printing

This parameter affects all servers. It does not affect the syq -uc and syq -uf
commands. (syq -uc sets an entrys status to Completed; syq -uf sets an entrys
status to Failed.)
Example: Processing an entry with two servers
This example describes how to archive all entries after they have been printed.
1

Set the Completion_Medium parameter to archive.

Add an entry to the queue with its medium set to print.


The entry is processed by the printmaster server.

When the entry completes, the printmaster server checks the


Completion_Medium parameter, and then changes the entrys medium to
archive.
The entry stays in the pending queue, and its status changes to New. This
time, the archive server picks up the entry, and then processes it.

When the archive server has processed the entry, its status changes to
Completed. Because the entry is now Completed, and its medium matches
the Completion_Medium, Columbus OM moves it to the completed queue.

Sequential printing
Documents usually are processed in the order that you add them, but is possible, if
you add a large document and then a small document, for Columbus OM to
complete processing the small document and send it to the printer before it
completes processing the large document.
To ensure that Columbus OM always processes documents in the order that you
add them, do the following:
To

Do this

affect all servers and printers

Set the UID_order parameter in the


default.tab file to YES.

affect a specific printer

Set the UID_order parameter in


printers configuration file
(config.tab) to YES.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Configuration for distributed printing


Distributed printing enables users who are connected to one Columbus OM print
instance to use printers that are controlled by another Columbus OM print
instance. Distributed printing is controlled by the netmaster server.
Example
In this example, there are two hosts, A and B, each with an instance of
Columbus OM. The Print2 instance controls a printer.
If you can connect to the Print1 instance, you can use the printer that is on Host B.
To do this:
1

In the Print2 instance, define the printer as a local printer.

In the Print1 instance, define Host B as a remote host, and the printer as a remote
printer.

You can then use the remote printer in the same way as you use a local printer.

Columbus OM
Explorer

Host A
Columbus OM
Print1 instance

HOST B
Columbus OM
Print2 instance

printer

Overview of setting up distributed printing


This section provides an overview of what you have to set up for distributing
printing. The steps are described in more detail below.
Most of the steps are done on the instance which will distribute the print requests
(Print1 in the picture above). The last two steps are done on the remote instances
themselves (Print2 in the picture above).
Step

See

Set up the list of remote printers.

page 114

Set the parameters for netmaster to configure how it connects to page 114
the remote hosts.

The parameters that you set for netmaster affect every remote
host to which it connects. If necessary, change the connection for
individual hosts.

Set up netmaster so that it can handle the status information


page 118
returned by the remote hosts when they complete a print request.

COLUMBUS OM INSTALLATION AND CONFIGURATION

page 116

113

114

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Step

See

Set up netmaster to handle requests for printers that it does not


recognize.

page 120

Specify an alternative host to try if a remote host becomes


unavailable.

page 121

Specify the remote hosts and users who are authorized to use the
printers that are controlled by the current instance.

page 377

Setting up the remote printers


On the Columbus OM print instance that will distribute print requests to printers
that are controlled by other instances, you have to create a remote printer for each
printer.
To create the remote printers
1

Do one of the following:


Command line: Edit this file: %UNIQDIR%\config\remote.tab
Columbus OM Explorer: Navigate to Advanced tab instance icon
Remote Printers Remote Printers menu Create.

Add one line for each printer, using the entry format below.

Entry format
printer

location

Field

Value

printer

The name of the printer, as it is defined on the remote instance.


You can use * as a wildcard, for example: dev* means all printers
that start with dev, and * on its own means all printers that are not
defined elsewhere (either as local printers or remote printers).

location

The name of the host computer that the Columbus OM instance


is on, and the name of the instance, separated by a colon, for
example:
myHost:instanceA

Configuring the connection to the remote hosts


In the Columbus OM print instance that will distribute the print requests to other
hosts, you can set the following configuration parameters for netmaster. All the
parameters have default values: check the default values and change them if
necessary to the requirements of your installation.
To configure netmaster
1

Do one of the following:


Command line: Edit this file: %UNIQDIR%\servers\netmaster\config.tab

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Columbus OM Explorer: See Configuring servers on page 99.


2

To enable netmaster to login to the remote host that it is transferring the file
to, set this parameter:
Parameter

Value

Remote_User

A user on the remote host. This user must have


implementor privileges. The default value is uniq.

To control what happens if netmaster cannot send the entry to the remote
host the first time that it tries, set these parameters:
Parameter

Value

Timeout

The maximum time (in seconds) that netmaster will


wait to make the connection.

Attempts_Limit

The maximum number of times that you want


netmaster to attempt to send the print request. If it
cannot send the print request after this number, it sets
the print requests status to Failed and moves it to the
completed queue. If you do not want to set a limit, set
this parameter to 0.

Postpone_Time

The intervals (in seconds) at which you want


netmaster to try. The default value is 300 seconds (5
minutes).

Action_On_
Postponement

An operating system command to run, for example, to


send a message to a user.

If you send more entries to the same host while it is still unavailable,
netmaster postpones processing them. It sets their Next_Attempt time to now
plus the value of the Host_Recheck parameter (in the config.tab file). It does
not change the entrys status to Postponed, and it does not run the
Action_On_Postponement command.
4

To control the traffic over the network when netmaster transfers the entries to
the remote hosts, set these parameters:
Parameter

Value

Delivery_Rate

The maximum delivery rate (in characters per second).


To set no maximum, set this parameter to 0 or leave it
blank.

COLUMBUS OM INSTALLATION AND CONFIGURATION

115

116

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Parameter

Value

Floor and Ceiling

The minimum and maximum size of documents that


netmaster will accept. The size can be measured in
characters or pages. For example, to reject documents
of less than 10 characters, set Floor to 10C. To reject
documents of more than 200 pages, set Ceiling to
200P.

File_Compress and
File_UnCompress

To compress the documents before netmaster sends


them to the remote system, set File_Compress
parameter to a command that can compress files, and
File_UnCompress parameter to a command that can
uncompress files. For example, on Windows you can
use gzip. On UNIX, you can use compress or gzip.

The same value for Delivery_Rate, File_Compress and File_UnCompress


is used for all hosts. To set different values for specific hosts, see Configuring
individual remote hosts below.

Configuring individual remote hosts


The Delivery_Rate, File_Compress and File_UnCompress parameters for
netmaster parameters affect how Columbus OM communicates with all remote
hosts. To change how it communicates with individual remote hosts, edit the
netmaster hosts file.
To edit the netmaster hosts file
1

Do one of the following:


Command line: Edit the %UNIQDIR%\config\nmhosts.tab file.
Columbus OM Explorer: Navigate to Advanced tab
Servers Servers menu Update nmhosts file.

Columbus OM

Add an entry for each host. using the format shown below.

Entry format
For each remote host, add an entry like this (all on one line):
host "[ delivery_rate ],[ compress_command ],
[ uncompress_command ],[failover_host ],[service]"

See the parameters below, and also Example netmaster hosts file (nmhosts.tab) on
page 117.
Parameters
host

The host name or IP address of the remote host.


Specify the following parameters in a list separated by commas, and enclose the list
in quotation marks.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

delivery_rate

To control the rate at which netmaster transfers the data to the remote host,
you can specify a maximum delivery rate (in characters per second).
To

Specify

set a limit of n characters per second

use the default rate, as set by the Delivery_Rate


parameter for netmaster

- (dash)

set no maximum rate

0 (or leave blank)

compress_command, uncompress_command

To reduce network traffic, you can tell netmaster to compress the files before
sending them and then uncompress them when they reach the remote host.
If you use this feature, you must specify both a command to compress files and
a command to uncompress the files. For example, on Windows, you can use
gzip. On UNIX, you can use compress or gzip.
To

Do this

compress the files

Specify the commands


to be used

Specify - (dash) for


use the default commands, as specified by the
File_Compress and File_Uncompress parameters both commands
for netmaster
transfer the files without compressing them

Leave both commands


blank

failover_host

For information about the failover_host parameter, see Specifying


alternative hosts (failover mode) on page 121.
service

The name of the service by which Columbus OM communicates with the


remote host. Columbus OM usually communicates by using the uniqcs
service. The default service for this value is set by the UQ_Service parameter
in the default.tab file.
Example netmaster hosts file (nmhosts.tab)
mars
venus
saturn
jupiter

"0, compress, uncompress -cf, jupiter"


"9600,,, jupiter, columbusservice"
"-, gzip -c, gzip -cd,"
",,,mars"

COLUMBUS OM INSTALLATION AND CONFIGURATION

117

118

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Getting status information from the remote host


Status information about a job that has been transferred to a remote host can be
returns to the user on the original host in several ways:

provide the current status of the job every time that it changes

provide only the final status of the job (either Completed or Failed)

ignore the status (that is, set the status to Completed as soon as the job has
been transferred to the remote host).

Update the status every time it changes (status feedback


mechanism)
Status feedback is returned to the originating host every time the status of the job
changes. The user kept fully informed as to the progress of their job. However,
there is a significant increase in network traffic. To handle this, the uqsfcache
server can be used. Its reduces network traffic by combining status information for
a host into a single call.
To configure this feature set these parameters:
Server/file

Parameter

netmaster (at the sending end)

Complete_On_Transfer NO

system default (default.tab) at Status_Feedback


receiving end

Value

5 (seconds) or more.

Provide only final status (ACK/NAK mechanism)


An ACK is returned on success, a NAK for failure. It gives the user final status
about their job, without raising network traffic significantly. The user is not
informed about the progress of the job, only its final state.
To configure this feature, set these parameters:
Server/file

Parameter

netmaster (at the sending end)

Complete_On_Transfer NO

system default (default.tab) at Status_Feedback


the receiving end
ACK_Command

Value

0 (zero)
CSUNIQ

This can optionally


be configured on a
per-printer basis.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Ignore status
This will cause transferred entries to complete immediately. This option minimizes
network traffic by removing returned status information. However, the user has to
check on the remote server to check the progress of their job. This option is most
suitable for automated environments.
To configure this, set these parameters:
Server/file

Parameter

netmaster (at the sending end)

Complete_On_Transfer YES

system default (default.tab) at Status_Feedback


the receiving end.
ACK_Command

Value

0
NO

This can optionally


be configured on a
per-printer basis.

Copying the list of remote printers to other instances


You can automatically copy the list of remote printers from one instance to all the
other instances. Furthermore, when you change the list on one instance,
Columbus OM makes the same changes to the lists on all the other instances. To
use this feature, you must choose one instance as the one on which you will always
make the changes to the list (called the master instance), and always make changes to
the list on that instance.
To use this feature, the master instance must be able to connect to the other
instances directly. If it can only connect to one or more of the other instances
indirectly (for example, to get from hostA to hostC, it has to go by hostB), you can
set up a routes table (routes.tab) (see route.tab: Routes to remote devices on
page 126.
To use a common list of remote printers
1

On the master instance where you will maintain the list of remote printers, set
these parameters for netmaster:
Parameter

Value

Get_Remote_Tab

NO

Unknown_Dest

IGNORE or FAIL

Use_Routing

NO

COLUMBUS OM INSTALLATION AND CONFIGURATION

119

120

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

On all the other instances, set these parameters for netmaster:


Parameter

Value

Get_Remote_Tab

Either n or ONCE.
To update the remote printers table every n seconds,
set it to n. The recommended minimum value is 900
(that is, every 15 minutes).
To update the table only when netmaster starts, set it
to ONCE.

Name_Server

host:instance (that is, the host and name of the


master instance where you will maintain the remote
printers table).

Unknown_Dest

IGNORE or FAIL

Use_Routing

NO

Handling unknown printers


If the printer specified for a request is not one that Columbus OM recognizes (that
is, it is not a local printer or a remote printer), specify what you want netmaster to
do with the request by setting its Unknown_Dest parameter.
To

Set Unknown_Dest to

ignore the request

IGNORE

set the requests status to Failed and move it to the


completed queue

FAIL

transfer the request to the name server

FORWARD

poll the peer systems to see if they know the printer (see POLL
also Polling the remote systems below).
The default value is IGNORE.
Polling the remote systems
If an entry is sent to a printer that Columbus OM does not know about, you can tell
Columbus OM to poll the peer systems to see if they know the destination by
setting these parameters for netmaster:
Parameter

Value

Unknown_Dest

POLL

Peers

The instances that you want netmaster to poll. Specify


each system as host:instance. Separate the systems by
using a comma, for example mars:print,
jupiter:print1, venus:accts.

If one of these hosts knows about the printer, netmaster transfers the entry to it. If
none of the hosts knows about the printer, Columbus OM sets the requests status to
Failed and moves it to the completed queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Specifying alternative hosts (failover mode)


This section describes how to configure Columbus OM to handle situations where
the host or instance you want use is unavailable or busy.

Handling
unavailable
hosts

To specify an alternative host to use if the first host cannot be used (for
example, because its network connection is unavailable), see Handling
unavailable hosts below.

To specify an alternative instance to use if the first instance is busy (that is, its
pending queue already contains a maximum number of entries), see Handling
busy systems on page 123.

You can specify an instance on an alternative host to try if the first host is
unavailable. This alternative host is called the failover host. netmaster transfers the
documents to the failover host, but it keeps checking if the first host becomes
available again. When it does, netmaster reverts to using that one.
You can use any host that has a Columbus OM print instance with the same name as
the first instance that was tried. It could be either an instance on a different host, or
an instance on the originating host.
Example
In this example, there are three hosts (mars, jupiter and saturn), and each host
has two Columbus OM print instances.
In the Print1 instance on mars, you can define the Print2 instance on jupiter as
a remote host. This enables someone using Columbus OM Explorer on the PC that
is connected to Print1 on mars to use a printer that is controlled by Print2 on
jupiter.

Columbus OM
Explorer

Host mars

Host jupiter

Host saturn

Print1

Print2

Print2

Print2

Print3

Print4

In case jupiter becomes unavailable, you can set up a failover host to use instead.
You can use any instance with the same name as the first instance tried. In this
example you could use either:

the Print2 instance on another host, saturn

COLUMBUS OM INSTALLATION AND CONFIGURATION

121

122

CHAPTER 5

Configuring a Columbus OM printing environment

Columbus OM
Explorer

Configuration for distributed printing

Host mars

Host jupiter

Host saturn

Print1

Print2

Print2

Print2

Print3

Print4

or the Print2 instance on the originating host, mars.

Columbus OM
Explorer

Host mars

Host jupiter

Host saturn

Print1

Print2

Print2

Print2

Print3

Print4

To set up a failover host


1

In the %UNIQDIR%\config\nmhosts.tab file, find the entry for the remote


host that might become available.
If there is no entry for it, you can add one: see Configuring individual remote
hosts on page 116.

Change the last (fourth) parameter to the name of the failover host to be used.

Set these configuration parameters for netmaster:


Parameter

Specify

Postpone_Time

How often (in seconds) you want netmaster to try to


connect to the remote host.

Max_Hosts_Tries

How many times you want netmaster to try to


connect to the remote host before it tries to connect to
the failover host instead. The default is 2.

Host_Recheck

How often (in seconds) you want netmaster to check


if the first host is available again. The default is 1800
seconds (that is, 30 minutes)

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

How the failover operation works


1

netmaster tries to transfer the document to one or more remote hosts.

If a particular remote host is not available, the document status is set to


Postponed and netmaster retries after the period specified by the
Postpone_Time parameter.
During this period, netmaster does not try to pass any other documents to the
remote host: they remain in the queue with their status set to New.

When the period is over, netmaster tries again to access the remote host.
It keeps trying, up to the maximum number of attempts that is specified by the
Max_Host_Tries parameter.

If netmaster still cannot access the remote host, then it looks in the hosts table
to see if a failover host has been specified, and then tries to transfer the
document to the failover host instead.

While it is using the failover host, netmaster keeps checking the original host,
at periods that are specified by the Host_Recheck parameter.
If the original host becomes available again, netmaster stops using the remote
host, and uses the original host instead.

Handling busy
systems

You can specify a maximum number of entries that can be held in an instances
pending queue, and an alternative instance to transfer extra entries to if that
maximum number is exceeded.
To do this, use the nmbusy.tab file.
If you do not specify an alternative remote instance, the entries stay in the local
pending queue until the remote instance is no longer busy.
File location and name
%UNIQDIR%\config\nmbusy.tab

Entry Format
Add one entry for each remote host and instance. Each entry has this format:
host1:instance1[:limit] host2:instance2
Field

Value

1 host1:instance1

The remote host and instance for which the failover if


busy feature is to be enabled.

COLUMBUS OM INSTALLATION AND CONFIGURATION

123

124

CHAPTER 5

Configuring a Columbus OM printing environment

Configuration for distributed printing

Field

Value

2 limit

The maximum number of entries that host1:instance1


can handle. If the instances pending queue contains more
than this number of entries when netmaster tries to
transfer an entry to it, it transfers the entry to the
host2:instance2 instance instead. If you omit this
value, Columbus OM uses the Max_Remote_Entries
value that is specified in the netmaster configuration
table.

3 host2:instance2

The host and instance to which the entries are to be


transferred if host1:instance1 is busy. The host can be
the same as the original host or a different one.

Example entries
MyHostA:MyInstance1:2000

MyHostB:MyInstance2

When netmaster has an entry to be transferred to MyInstance1 on MyHostA, it


checks the number of entries in the pending queue. If there are more than 2000
entries, it transfers the extra entries to MyInstance2 on MyHostB.
When the number of entries in the pending queue falls back below 2000,
netmaster starts using that instance again.
MyHostA:MyInstance1:2000
MyHostB:MyInstance2:3000

MyHostB:MyInstance2
MyHostC:MyInstance3

This example starts the same as the previous example: if the number of entries
in the pending queue for MyInstance1 exceeds 2000, netmaster transfers the
extra entries to MyInstance2. If or when the number of entries in
MyInstance2s pending queue exceeds 3000, netmaster does one of the
following:

If the number of entries in MyInstance1s pending queue has fallen back


below 2000, netmaster starts using that instance again.
If the number of entries in MyInstance1s pending queue is still above
2000, netmaster transfers the new entries to MyInstance3.

MyHostA:MyInstance1:2000
MyHostB:MyInstance2:3000
MyHostC:MyInstance3:1000

MyHostB:MyInstance2
MyHostC:MyInstance3
MyHostA:MyInstance1

In this example, there is a loop of failover instances. If all the instances are
busy, entries stay in the local pending queue until one is no longer busy.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Reference

Reference
printmaster servers: Handling print documents
The printmaster server monitors the queue for entries with a medium of PRINT,
and passes them to an appropriate local printer server.
Configuration file
%UNIQDIR%\servers\printmaster\config.tab

Configuration parameters
Action_On_Blocked command

An operating system command which is executed when a queue entry is


blocked because the wrong paper type is mounted. For more information, see
Operating system actions during processing on page 417.
Auto_Complete_Compress number
Auto_Pending_Compress number
Compress_Time hh:mm[,hh:mm]

See Compressing the queues automatically on page 268.


Auto_Complete_Purge number
Auto_Pending_Purge number
Purge_Time hh:mm, hh:mm...

See Deleting old entries automatically on page 262


Fix_Interval number|OFF

See Fixing queues automatically on page 270.


Medium PRINT

The medium name which marks a queue entry as suitable for processing by this
server.
Port_Hold YES|NO
YES to hold directly-connected devices open whenever the scheduler is
running; NO (the default) to allow them to revert to idle when their respective

server is shut down.


Scan_Interval number

The interval in seconds between successive scans of the queue. The default is
10.
Server server

The name of the server, which must be the same as the name of the folder that
the configuration file is in.

COLUMBUS OM INSTALLATION AND CONFIGURATION

125

126

CHAPTER 5

Configuring a Columbus OM printing environment

Reference

route.tab: Routes to remote devices


The route.tab file defines routes to remote devices.
File location and name
%UNIQDIR%\config\route.tab

Content
The file contains any number of ROUTE statements, optionally preceded by any
number of DEFINE statements. Each statement occupies one line, with three spaceseparated fields.
DEFINE statements
A DEFINE statement provides a shorthand definition of a sequence of instances.
DEFINE route host:instance[/host:instance]...
Field

Value

route

A user-specified name for the sequence of instances.

instance_list

A slash-separated list of instances, each specified as


host:instance.

ROUTE statements
A ROUTE statement contains an ordered sequence of instances used to reach a given
destination.
ROUTE destination host:instance[/host:instance]...
Field

Value

destination

A destination which maps to a remote Columbus OM


instance.

host:instance

A slash-separated list of the instances (each specified as


host:instance) and routes through which a document
must be transferred in order to reach the destination.

Setting the language


New language files may be supplied by Macro 4 when they are available. To use a
a language file, you must compile it, and then set Columbus OM to use it.
To compile the language files
1

Copy the language files to %UNIQDIR%\lang folder.

If this folder does not exist, you can create it.

The filename extension indicates the language that the file is for. For
example, lang.deu contains the German language text.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 5

Configuring a Columbus OM printing environment

Reference

At the command line, change to the %UNIQDIR%\lang folder, and then do one
of the following:
To

Do this

compile the language file for the first


time

Type:
langtab code -b filename

compile a new version of the language Type:


file, overwriting an old version

langtab code -f filename

Replace code with the filename extension, and filename with the name of the
language file.
For example, to compile the German language file, lang.deu, type:
langtab deu -b lang.deu
To set the language

To control the language in which Columbus OM displays, set the Language


parameter in the system defaults file (default.tab) to the code that is used in the
name of the language file. For example, to display the text in German, set the
Language parameter to deu.
Access to this feature
To use the langtab command, your username must be in the
%UNIQDIR%\security\lang_b file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

127

128

CHAPTER 5

Configuring a Columbus OM printing environment

Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

129

CHAPTER 6

Chapter 6

Setting up printers

For each printer that you want to use with Columbus OM, you add a printer server.
The printer server tells Columbus OM how to connect to the printer, and how you
want to use it (for example, the font to use by default and whether you want it to
print banner pages in front of each document).
For more information, see Adding printers on page 130.
An important part of configuring a printer is selecting its printer type. A printer type
defines some basic characteristics of printers (for example, the fonts available, the
paper orientation and finishing commands). The printer types that you are most
likely to need are already set up for you. You can also create your own printer
types. See Defining printer types on page 152.
To make printing more efficient, you can get Columbus OM Explorer to choose
the most suitable printer from a group of similar ones. You do this by creating
printer classes. See Creating printer classes on page 157.
To make it easier for users to find the printers that have been set up specifically for
their use, you can create printer groups. See Creating printer groups on page 158

COLUMBUS OM INSTALLATION AND CONFIGURATION

130

CHAPTER 6

Setting up printers

Adding printers

Adding printers
To

See

search for printers that on the network

Searching for printers on the network


on page 130

create multiple printers from values in a p_mk.tab: Multiple printer creation on


file
page 159
add and configure individual printers

Adding printers using Columbus OM


Explorer on page 134

Searching for printers on the network


Columbus OM can search for printers that are on your network and find out some
of the basic configuration information that is required to add them to
Columbus OM.
Requirements
Columbus OM can find printers that are:

able to respond to SNMP requests

directly connected to the network

turned on.

Overview
This feature uses the xsearch command.
Step

See

Create a configuration file for the xsearch command.

below

Run the xsearch command that covers the range of IP addresses, and page 131
includes the option to create a configuration file.
Run the p_mk command using the configuration file to add the printers page 133
to Columbus OM.

Configuring the
xsearch
command

To enable Columbus OM to assign the appropriate language and channel type to


the printers that it finds, the xsearch command uses a configuration file. The
configuration file is called xsearch.tab, and it is in the Columbus OM config
folder.
The xsearch command asks a printer for its description and port number. It refers
to this file to get the languages and channel type.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Adding printers

The default xsearch.tab file looks like this:


Key string
---------------------------------"Xerox Document Centre 440"
"Laserjet"
"Laserjet"
"LEXMARK"
"LEXMARK"
"EPSON"
"Phaser"

Language
-------ALL
ALL
ALL
ALL
ALL
ALL
ALL

Port
------515
9100
515
9100
515
9100
9100

Channel_Type
-----------SNMP
RAW
LPD
RAW
LPD
RAW
RAW

You can add other entries to this file as required.

Running the
xsearch
command

Syntax
xsearch start_address end_address [file]
[-a] [-c] [-f] [-p number] [-s|-sx email_address] [-si|-v]
[-t number] [-x]

Parameters
start_address end_address

The range of IP addresses in which you want to search for printers.


file

The path and name of the file in which the configuration information is to be
put. You can then use the file with the p_mk command. See also Configuring
the xsearch command on page 130.
The default file name is xsearch.mk.
-a

Produces a report (in PCL format) with information about the printers found.
The report file is called xsearch.PCL.
-c

Adds an entry for each device found to the accounting database.


-f

Some devices cannot be distinguished between printers and computers. Using


this parameters includes all devices found; to find out more information about
them, you can then use the xcaps command (see xcaps command: Finding the
features of a printer on page 160).
-p number

Searches only devices on the port number specified.


-s|sx email_address

Prints a one-page audit report on the printer found; -s includes all printers; -sx
includes only printers that have not been found before.
The report includes your email address to indicate who is running the audit.

COLUMBUS OM INSTALLATION AND CONFIGURATION

131

132

CHAPTER 6

Setting up printers

Adding printers

-si

Silent mode: no output is displayed onscreen.


-t number

Timeout interval, measured in tenths of a second.


-x

Excludes printers that have already been set up in Columbus OM; in other
words, includes only new printers.
-v

Verbose mode: displays more information while the command runs.


Example
xsearch 10.0.20.0 10.0.20.255 MyPrinterFile

This command searches for printers whose IP address is between 10.0.20.0 and
10.0.20.255, and then adds their configuration information to a file called
MyPrinterFile.
xsearch 10.0.20.0 10.0.20.255 -p 9100

This command searches for printers that are on only port number 9100, and
then adds their configuration information to a file called xsearch.mk.
xsearch 10.0.20.0 10.0.20.255 MyPrinterFile -si -x

This command searches for new printers. You could use this in a dispatch rule,
for example:
COMMAND "xsearch 10.0.20.0 10.0.20.255 MyPrinterFile -si -x"
COMMAND "p_mk -f MyPrinterFile"

Configuration file created by xsearch


The configuration file that xsearch creates contains the following items for each
printer that it finds:

the name of the printer. If Columbus OM cannot get the name from the
printer, it sets the name to printern

the IP address and port number of the printer (for example,


"NETWORK 10.0.20.1 9100")

the description of the printer (for example, "HP Color LaserJet 8500")

the channel type (for example, RAW or LPD)

whether the printer supports PostScript (either Yes or No).

The configuration file also contains a comment that tells the p_mk command to set
the driver to xprinter.
You can change or add to these values before using the file with the p_mk
command.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Adding printers
with the p_mk
command

Setting up printers

Adding printers

The p_mk command creates one or more printers.


To use a configuration file that has been created by the xsearch command, use the
version of the command shown in Creating multiple printers below.
Creating a single printer
Syntax
p_mk [-x] name parameter... [-QUEUE_NAME instance]
Parameters
-x

Creates a printer that uses the xprinter driver.


name

The name of the printer to be created, a string of up to 16 alphanumeric


characters.
parameter

Any number of entries of the form:


keyword=value

where keyword is a printer parameter and value is a valid setting for that
parameter, enclosed in quotation marks "..." if it contains spaces.
To assign multiple paper types to a printer, use:
PAPER="papertype[,papertype][...]".
-QUEUE_NAME|-qn instance

The name of the Columbus OM instance to which the printer is to be added.


Example

This command creates a printer called MyPrinter, and assigns three paper types
to it:
p_mk MyPrinter Device="NETWORK 10.0.20.0 9100"
Paper="A4,Letter,B5"

Creating multiple printers


Syntax
p_mk -f file [-QUEUE_NAME instance]
Parameters
-f file

The name of the file that defines the printers to be created.


The file can contain any number of lines. Each line contains a list of the
parameter values to be applied to each print server. Separate the values by
using a comma. If a value contains spaces, enclose it in quotation marks "...".
server,value1,value2,value3,...

COLUMBUS OM INSTALLATION AND CONFIGURATION

133

134

CHAPTER 6

Setting up printers

Adding printers

Which parameters these values are for is specified by the


%UNIQDIR%\menus\p_mk.tab file. (This file is not used if the file has been
created by using the xsearch command.) For more information about the
format of this file, see p_mk.tab: Multiple printer creation on page 159
-QUEUE_NAME|-qn instance

The name of the Columbus OM instance in which the printers are to be


created.
Example

This command creates a printer called MyPrinter, and assigns three paper types
to it:
p_mk MyPrinter Device="NETWORK 10.0.20.0 9100"
Paper="A4,Letter,B5"

If %UNIQDIR%\menus\p_mk.tab contains this line:


Server,Printer_ID,Device,Printer_Type

and myservers.def contains these lines:


P1,"My first printer","NETWORK 233.143.76.11 9100",POSTSCRIPT
P2,"My second printer","NETWORK 233.143.76.12 9100",POSTSCRIPT
P3,"My third printer","NETWORK 233.143.76.13 9100",HP_LASERJET

then you could create the printer servers by using this command:
p_mk -f myservers.def

Adding printers using Columbus OM Explorer


1

In Columbus OM Explorer, navigate to Advanced tab


Printers folder Printer menu Add Printer.

Set the properties as described below, and then click OK.

instance icon

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Adding printers

Columbus OM Explorer creates the new printer. To see the new printer in the
list, you might need to click the Refresh toolbar button
.
3

To make the printer available for printing documents, you must enable the
printer, if you have not already done so. See Managing printer servers below.

If you are using printer groups to maintain security, add the new printer to the
appropriate groups. See Access to printers on page 376.

To copy an existing printer

If you have already set up a printer server which has similar properties to the new
one, you can copy it and use it as the basis of the new one. To do this, click the
printer server and then click Duplicate on the Printer menu.
Printer tab
Printer
A name to identify the printer.
The name can include letter, numbers and underscore characters. It cannot contain
spaces. The maximum length is 16 characters.
Printer Id
(Optional) A description for the printer.
DeviceType
Specify how Columbus OM can connect to the printer by selecting one of these
options:
For a printer that

Select

is directly attached to a serial or parallel port on the host

Device

is on the network and can be connected to by specifying a host name TCP/IP


and a port number
is on the network and has extended features that you want to use (see XPrinter
Using the xprinter driver on page 185)
can be connected to only by using the lpr/lpd protocol

LPR/LPD

is connected by a dial-up modem

Modem

For information about Command, see Using a command instead of an actual


printer on page 143.

For information about Fax, see Redirecting documents from a print instance to
a fax instance on page 469.

Enable Printer
To enable the printer so that it can be used as soon as you have finished setting it
up, select this option.
To enable the printer later, see Managing printer servers on page 151.
Details tab
Specify the connection to the printer. For information about how to do this, see
page 146. The fields that are displayed depend on which Type you selected on the
Printer tab.

COLUMBUS OM INSTALLATION AND CONFIGURATION

135

136

CHAPTER 6

Setting up printers

Adding printers

Advanced Settings tab


Set the values of any parameters that you want to change. For more information
about the parameters, see Configuring the printer features on page 163.

Specifying the connection to the printer


Serial/parallel
printer

On the Details tab, set the Device/File name to the port specification, for
example: LPT1 (on a Windows host) or /dev/lp147 (on a UNIX host).
If the direct connection uses a serial line, you must also specify the line
characteristics.
To specify the line characteristics
1

Edit the %UNIQDIR%\servers\server\line.def file. (server is the name of


the printer server.)

Add an entry for each parameter, specifying the name of the parameter, and its
value, like this:
SPEED

19200

Example

This example shows the parameters and values that are suitable for almost all cases:
IgnoreDefinition
Speed
Csize
Stopb
Parity
Xin
Xout
Inlcr
Icrnl
Igncr
Ocrnl
Onlcr
Onlret
Min
Time

No
19200
8
1
Off
On
On
Off
Off
Off
Off
Off
Off
1
0

Parameters

The parameters applicable to a Columbus OM instance are listed in this file:


%UNIQDIR%\menus\def_linedef. The full set is:
Parameter

Values

Description

CSIZE

6|7|8

Bits per character.

ICRNL

OFF|ON

On input, map CR to NL.

IGNCR

OFF|ON

On input, ignore CR.

IgnoreDefinition

YES|NO

Ignore the definitions in this file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Adding printers

Parameter

Values

Description

INLCR

OFF|ON

On input, map NL to CR.

MIN

number

See the Note below.

OCRNL

OFF|ON

On output, map CR to NL.

ONLCR

OFF|ON

On output, map NL to CR+NL.

ONLRET

OFF|ON

On output, NL performs function of


CR.

PARITY

EVEN|ODD|NONE

Parity bit.

SPEED

number

Baud rate.

STOPB

number

Stop bits.

TIME

number

See the Note below.

XIN

OFF|ON

On input, use Xon/Xoff flow control.

XOUT

OFF|ON

On output, use Xon/Xoff flow control.

Notes
MIN and TIME can be set to the following values.

The unit for MIN is a character count, and for TIME is an interval measured in tenths
of a second. In most cases, the preferred setting for MIN is 1, and TIME is 0, so that
the receipt of a single character is sufficient to satisfy a read.
Case

Behaviour

MIN > 0
TIME > 07

TIME serves as an inter-character timer which is activated only


after the first character is received. The interaction between
MIN and TIME is as follows:

The read sleeps until the MIN and TIME mechanisms are
activated by the receipt of the first character. As soon as
one character is received, the timer is started.
If MIN characters are received before the timer expires,
the read is satisfied (note that the timer is reset upon
receipt of each character).
If the timer expires before MIN characters are received,
the characters received to that point are returned to the
user (note that at least one character will be returned
because otherwise the timer would not have been
enabled).

If the number of characters read is less than the number of


characters available, the timer is not reactivated and the
subsequent read is satisfied immediately.

COLUMBUS OM INSTALLATION AND CONFIGURATION

137

138

CHAPTER 6

Setting up printers

Adding printers

Case

Behaviour

MIN > 0
TIME = 0

The timer plays no role; only MIN is significant:

The read sleeps until MIN characters are received.

A program that uses this method to read record-based terminal


I/O might block indefinitely in the read operation.
MIN = 0
TIME > 0

MIN = 0
IME = 0

TIME now serves as a read timer:

The timer is activated immediately.

If a single character is received before the timer expires,


the read is satisfied and returns that character.

If the timer expires before a character is received, the


read is satisfied but no character is returned.

The number of characters currently available are returned


immediately without waiting for more characters to be input.

Using a printer that is connected to an IBM serial port


To use a printer that is connected to an IBM serial port, you must ensure that the
port is set up as a TTY and not as a printer. This is because of the incompatibility
between the serial line configuration assumptions on the printer port definition by
IBM and the requirements of Columbus OM.
Most manufacturers provide a number of device files in the /dev folder which
point to the same device, but which have different attributes. An example on IBM
is an lp0 and a tty1 port. These both point to the same serial port, but
Columbus OM is able to use only the tty1 port.
To find out if multiple device files are the same, run an ls -l command and
compare the major device numbers. If there is no alternative to lp0, you need to
create one using smit.
If this is not the case at your installation, follow these steps:
1

Logon as root.

Start smit.

Select Devices

Printer/Plotter

Select Devices

TTY

When you have selected a port, a message appears:

Remove printer.

Add a TTY

RS232

port.

enable program? respawn


6

Change respawn to off.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

TCP/IP
connection

Setting up printers

Adding printers

On the Details tab, set these properties:


Property

Description

Host Name

The host name or its IP address of the computer to which


the printer is connected.

Port Number

The port number to which the printer is connected.

Finding out the port number

The port number might have been set up by the user when configuring the printer.
On some hosts, this number is predefined: on many types, it is 2000 plus the
number of the connection.
If the printer uses a network card, the port number is often 9100.
The Columbus OM print instance includes a program called porttest that might
help find out the number.
Using the porttest program to find the port number
1

Make sure that the printer is idle.

Type:
porttest host [range]

where:

host is either the name of the printer or the printers IP address, as


specified in the etc/hosts file.
range is a range of port numbers to test: separate the numbers with a
space, for example 9001 9500. If you omit this range, Columbus OM tests

1 to 9999.
The results that the porttest command return are not guaranteed to be accurate.

lpr/lpd protocol

Use the lpr/lpd protocol only if there is no other way of connecting to the printer,
because it does not support all the printer control features. This might be necessary
for a printer that is:

connected to the network using a network card that supports only the lpr/lpd
protocol, or
on another host computer that is non-Open, but does support the lpr/lpd
protocol.

On the Details tab, set these properties:


Property

Description

Host Name

The name of the host on which lpd is running.

Port Number

515

COLUMBUS OM INSTALLATION AND CONFIGURATION

139

140

CHAPTER 6

Setting up printers

Adding printers

Property

Description

Queue Name

The name of the print queue that is used by the lp daemon.


On a network card, the queue name is often not obvious:
common names include printer, lp, lpt1 or the same as
the host name.
To check that you have the correct names, type at the
command line:
lprtest host queue

If the names are correct, then the text hello is printed.


Options

Any options you want to use, as described below.

Options for lprout


-b

Sends the data before the control information. Most lp daemons do not require
this option. If you use this option, you cannot also use the -z option.
-c class

Sets the printer to the specified class.


-f filetypes

Specifies a filetype (the default filetype is binary files, which works for most
systems). Different lp daemons support different filetypes, including:
f

Formatted file (that is, discard the HT, CR, FF, LF, and FF characters).

PostScript file.

File is printed with header, page numbers and pagination.

Fortran carriage control.

-i pid

(Windows only.) Defines the process id.


-L user

Defines the user id to be sent by the Receive Job subcommand L.


-n flag

Truncates the local hostname that is used in constructing control and data file
names. This option is required by some JetDirect cards. The flag can be:
"."

Truncate at the first period (dot) "."

"nnn"

Truncate after nnn characters.

".nnn"

Truncate after whichever comes first.

-p

Forces a 5-second pause before closing the connection.


-T title

Defines the title to be sent by the Receive Job subcommand T.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Adding printers

-z

Allows zero byte files. If you use this option, you cannot also use the -b option.
Attaching the lprout properties (UNIX only)
The lprout driver program uses the privileged socket 515 to communicate with
the lp daemons. This means that the lprout program usually needs to have special
access rights.
To change the access rights
1

Logon as root.

Type:
cd $UNIQDIR/programs/servers
chown root lprout
chmod u+s lprout
ls -l lprout

The system displays a line like this:


-rwsrwxr-x root uniqgrp 1 nnnn lprout

Using reserved ports


To control whether lprout uses ports that are in the reserved range (1 1023) to
communicate with the printer or lp daemon, set this parameter in the system
defaults file (default.tab):
Use_Reserved_Ports Yes|No

Using reserved ports might be prevented by your firewall, because it is considered


a security risk. To use only standard ports for communication, set this parameter to
No.
You can also set this parameter in the configuration file for a specific printer. Any
value set in for a specific printer overrides the value in default.tab.
The default value is No.

Connecting to a
printer by a
modem

This section explains how to connect to a printer that is available by a dial-up


modem. If you have several modems that can be used interchangeably, see
Connecting to a printer by a group of modems on page 142.
To connect to a printer by a modem
1

On the Modem Details tab, set these properties:


For a modem that is

Select

directly connected to the host computer

Device

connected to a different host

Network

More fields appear, where you specify more details about the connection.

For a directly connected modem, specify the Device Name.

COLUMBUS OM INSTALLATION AND CONFIGURATION

141

142

CHAPTER 6

Setting up printers

Adding printers

For a modem connected to a different host, specify the Host Name and the
Port Number.

Set the following parameters (see Configuring the printer features on


page 163). For more information about the commands you can specify, refer to
the modems documentation.
Parameter

Specify

Dial_Command

The command that the modem uses to dial the


destination printer (for example: ATDP9W01234567890). This can also contain any last minute
instructions to the modem, for example, turning down
the volume.

Modem_Set

The command to be sent to the modem to prepare it for


use, before establishing the connection. This is usually
ATZ, but it can be any valid instruction (for example, ATL
OMOSO= O).

Connect_Text

The character string expected as a response when the


modem connects (for example: CONNECT 19200).

Timeout

The maximum time (in minutes) to wait for connecting


to the printer. The default is no timeout, that is, wait
forever.

Connect_Delay

The interval (in seconds) to pause between connecting


and sending the data.

Disconnect_Delay The interval (in seconds) to pause after sending the data

and before closing the connection.


Modem_Reset

The command that resets the modem at the end of a


connection. The command should leave the modem in
a state suitable for other users. This is usually ATZ, which
returns the modem to its configured default state.
There is also a special instruction CLOSE which can be
used if the modem is configured to hang-up and reset
when it detects that the DTR signal from the host
computer has dropped. This is a quick way of achieving
the desired result if the modem can be configured in this
fashion.

Connecting to a printer by a group of modems


If you have several modems which can be used to connect to a printer, you can
create a list of them and Columbus OM will use whichever one is available.
1

On the Modem tab for the printer, select File, and set it to:
%UNIQDIR%\servers\server\modems.tab

where server is the name of the printer server.


2

On the host, create a file called modems.tab in the


%UNIQDIR%\servers\server folder.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Adding printers

In modems.tab, create one line for each modem/printer connection, using the
entry format shown below.

Entry format
Field

Description

Device

The direct connection to a local modem, for example


/dev/ttyN.

Init

The sequence of control codes to initialize the modem prior to


establishing a connection (elsewhere known as Modem_Set).

Reset

The sequence of control codes to reset the modem at the end of


a connection (elsewhere known as Modem_Reset).

Dial

The sequence of control codes to cause the modem to dial a


connection to a specific destination (elsewhere known as
Dial_Command).

Connected The modem reply which indicates that a connection to the


service has been established, enclosed in quotes "..." if it
contains spaces (elsewhere known as Connect_Text).

Example
# Device
# -----------/dev/tty0
/dev/tty1

Using a
command
instead of an
actual printer

Init
----ATZ
ATZ

Reset
----ATZ
ATH0

Dial
-----------ATDT
ATS0=255DT

Connected
---------------CONNECT
"CONNECT 9600"

Documents can be redirected to an operating system command instead of printing


them. For example, documents could be written to a magnetic tape archive.
On the Command Details tab, type the operating system command in the
Command box.
The command can include substitution of operating system variables and
Columbus OM print variables %name.

Configuring the connection


To configure the connection to the printer, set these parameters. (See Configuring
the printer on page 164.)
To

Do this

keep the connection to the printer


between print requests

Set Hold_Connect to Yes.

shut down the printer server as soon as it Set Keepalive_Time to 0.


is idle
shut down the printer server after n
seconds of being idle

Set Keepalive_Time to n, and


Scan_Interval to the interval (in
seconds) at which to scan the queue.

set how long Columbus OM should wait Set Linger_Time to n (seconds). The
for the printer to confirm that it has
recommended number is 3600.
received all the data

COLUMBUS OM INSTALLATION AND CONFIGURATION

143

144

CHAPTER 6

Setting up printers

Adding printers

To

Do this

stop the network printer card from


Set Pause_Nulls to the number of null
timing out while it is paused, by sending characters to send, and Pause_Time to
null characters to the printer
the interval (in seconds) at which to send
them.
set a maximum rate of delivery

Set Delivery_Rate to n[, size],


where n is the number of characters per
second, and size is the packet size.
A suitable value for a 9600 baud line is
960,10.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Changing the properties of printers from the command line

Changing the properties of printers from the


command line
To change the properties of one or more printers in a Columbus OM instance, use
the p_mod command.
Syntax
p_mod printers [-x] keyword=value ... [-QUEUE_NAME instance]

Parameters and options


printers

The printers to be changed; one of:


Parameter

Description

printername

The name of a printer.


To change multiple printers, the name can include wildcard
characters (? and *).

class

All printers in the specified class.

-c class

All printers in the specified class.

-f list

All printers in the list.


Separate the names in the list by using a comma.

-a

All printers.

-a string

All printers whose name starts with string.

-x

If the printer uses the xprinter driver, include this parameter.


keyword=value
keyword is a printer parameter, and value is a value for the parameter. If the

value contains spaces, enclose it in quotation marks.


To delete a parameter, omit the value.
To set multiple properties, repeat this parameter.
To assign multiple paper types to a printer, use:
PAPER="papertype[,papertype][...]".
-QUEUE_NAME|-qn instance

The name of the Columbus OM instance on the current host that the printers
are in.
Example
p_mod MyPrinter -x Hard_Queue=Yes Delivery_Mode=Secure

This command changes the values of two properties of a printer that uses the
xprinter driver.

COLUMBUS OM INSTALLATION AND CONFIGURATION

145

146

CHAPTER 6

Setting up printers

Managing print servers from the command line

Managing print servers from the command line


Displaying and deleting printers
To

Use

list the names of print servers that are in p_ls [-QUEUE_NAME instance]
a Columbus OM instance
delete print servers from Columbus OM p_rm server[ server]...
[-QUEUE_NAME instance]

delete print servers that are listed in a file p_rm -f file

[-QUEUE_NAME instance]

Parameters and options


server

A print server to be removed. To remove two or more print servers, separate


their names by using a space.
A print server can be removed only if it is inactive.
-f file

The name of a file that contains a list of the print servers to be deleted. Put each
printer on a separate line.
-QUEUE_NAME|-qn instance

The name of the Columbus OM instance (which must be on the current host)
that the printer servers are in.

Controlling print servers


To control a print server and the job it is currently processing, use the opq
command.
Syntax
opq [server|-ALL] option [qualifier...]

Specifying the server


To

Do this

control a specific server

Specify its name, for example:


opq MyServer -QUERY

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Managing print servers from the command line

To

Do this

control all servers

Use -ALL, for example:


opq -ALL -QUERY

The options that you can use to control


all servers are: -ABORT, -CANCEL,
-DISABLE, -ENABLE, -KILL, -PAUSE,
-QUERY, and -RESUME.
specify a default printer to be controlled Set the Server parameter in the
%UNIQDIR%\config\default.tab file.
When you run this command, omit both
server and ALL, for example:
opq -QUERY

Managing the server


To manage printer servers, use the opq command with one of these options:
To

Use

enable the server

-ENABLE|-e

disable the server at the end of the


current jobs

-DISABLE|-d END

disable the server when it becomes idle -DISABLE|-d IDLE


disable the server immediately

-DISABLE|-d NOW

terminate the server, because it is not


responding

-KILL|-k

add the server to a printer class

-INSERT|-i class

remove the server from a printer class

-EXTRACT|-x class

mount a paper type on the server

-MOUNT|-m paper_type

unmount a paper type from the printer

-UNMOUNT|-u paper_type

Use this option with caution, because it


might leave Columbus OM in an
indeterminate state. Before using this
option, disable the server by using the
command with the -DISABLE NOW
option.

create a server as copy of the current one -COPY|-o new_name


set the servers device type

-DEVICE|-v device

display the servers configuration

-QUERY|-q

COLUMBUS OM INSTALLATION AND CONFIGURATION

147

148

CHAPTER 6

Setting up printers

Managing print servers from the command line

Managing the entries


To manage the entries that a printer server is processing, use the opq command
with one of these options:
To

Use

stop the current job, and leave the entry -ABORT|-a


in the pending queue
stop the current job, and move the entry -CANCEL|-c
to the completed queue, marked as
Cancelled
suspend the current job

-PAUSE|-p

suspend a different job

-PAUSE|-p -UID entry

resume the current job

-RESUME|-r position
position specifies where you want the

job to restart:
n

From page n.

+n

From n pages after the


current one.

-n

From n pages before the


current one.

From the current page.

-RESUME -UID entry position

resume a different job

position specifies where you want the

job to restart, as described above.


print some pages on a different printer

-SPLIT|-s number server2

Pages up to and including number


remain on the current server. The rest of
the pages are sent to server2.
print all remaining pages on a different
printer

-TRANSFER|-t server2

reprint n lines from start of the current


page

-LINEUP|-l n

The server stops at the end of the current


page. The rest of the pages are send to
server2.

Common parameters
-HELP|-h
-NO_BANNER|-nb
-NO_WARNING|-nw
-QUEUE_NAME|-qn instance
-SILENT|-si

See Common parameters on page 602.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Managing print servers from the command line

Displaying printer status


The lpstat command displays status information about printers and print jobs.
This is an enhanced version of the standard UNIX SVR3 lpstat command.
Syntax
lpstat [option]

or
uniqlpstat [options]

Parameters and options


For consistency with general UNIX practice (and unlike the other Columbus OM
commands), the option keywords for the Columbus OM version of lpstat are
case-sensitive.
The detailed syntax of this command varies according to the operating system
environment in which it is running. A typical list of options includes:
-a [list]

Display the print request acceptance status of all printers, or those in the list.
The list can be either:

items separated by commas: item1,item2,...,itemN


items separated by commas and/or spaces, and the entire list enclosed in
quotation marks: "item1, item2 ... itemN"

-c [list]

Display the members of all printer classes, or those in the list (see above).
-D -p [list]

Display the settings of all printers, or those in the list (see above), in a userfriendly format.
-d

Display the default destination for print requests.


-l -p [list]

Display the settings of all printers, or those in the list (see above), in a longer
format.
-o [list]

Display the status of all print requests, or those in the list (see above) of
printers, classes, and entry ids.
-P [list]

Display the paper types supported by all printers, or those in the list (see
above).
-p [list]

Display the status of all printers, or those in the list (see above).

COLUMBUS OM INSTALLATION AND CONFIGURATION

149

150

CHAPTER 6

Setting up printers

Managing print servers from the command line

-R [list]

Display the ranked status of requests on all printers, or those in the list (see
above).
-r

Display the status of the print request scheduler.


-s

Display a summary of printer status information.


-t

Display full printer status information.


-u [list]

Display the status of print requests on the default destination for all users, or
those in the list (see above).
-v [list]

Display the path names of the device drivers associated with all printers, or
those in the list (see above).
UNIX: Intercepting the operating systems lpstat command
UNIX only: To make sure that the Columbus OM version of lpstat is used instead
of the standard UNIX version, see Intercepting the lp and lpstat commands on
page 224.

Displaying printer information


The uqpinfo command displays status and configuration information for a
specified local or remote print server.
Syntax
uqpinfo server [host:instance]
Parameters and options
server

The print server to be reported on.


host:instance

If the printer is on a different computer: the hostname of the computer, and the
name of the Columbus OM instance that controls the printer.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Managing printer servers

Managing printer servers


To manage a printer server, do one of the following:

Click the printer server, and then click a command on the Printers menu.

Right-click the printer server, and then click a command on the shortcut menu.

To

Use this command

change the printer servers configuration

Modify

create a new printer server, based on the existing printer


servers configuration

Duplicate

enable the printer server so that it can be used for printing Enable
documents
prevent the printer server from being used temporarily

Disable

delete the printer server from the instance

Remove printer
from instance

COLUMBUS OM INSTALLATION AND CONFIGURATION

151

152

CHAPTER 6

Setting up printers

Defining printer types

Defining printer types


When you set up a printer server, you might need to specify its printer type. A
printer type defines some basic characteristics of printers (for example, the fonts
available, the paper orientation and finishing commands). Some commonly-used
printer types already set up for you: HP Laserjet and compatibles, PostScript,
and Canon8-A1.
To add any more printer types, follow the instructions below.
To add a printer type
1

In Columbus OM Explorer, navigate to Advanced tab


Printer Types Printer Types menu Create.

Type a name for the printer type.

Click Attribute Types, and then click one of the attributes on the pop-up
menu.

instance icon

For each attribute type you can specify one or more names and their values.
For example, to specify the fonts that are available, add a name for each font
(Times, Courier and so on), and for each of these, specify the value that
creates that font.
4

Set these properties:


Property

Description

Name

A description of the feature.

Value

The printer command that creates the feature. For example, on a


HP Laserjet printer, the command that creates an italic font is
\033(s1S.

Click Add.

Repeat steps 5 to 8 for any other attributes.

Click OK.

To assign a printer type to a printer server, set the printer servers


Printer_Type parameter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Defining paper types

Defining paper types


To control and manage stationery use, you can create and assign paper types to a
printer. A paper type defines the page length, font, pitch and so on: when you print
a document, you can select an appropriate paper type instead of having to set each
attribute separately.
When you have defined a set of paper types for one Columbus OM print instance,
you can distribute it to other networked instances, instead of having to set them
individually for each instance.
To add a paper type
1

In Columbus OM Explorer, navigate to Advanced tab


Paper Types Paper Types menu Create.

Set the properties as described below, and then click OK.

instance icon

Style properties
Property

Description

Name

A name for the paper type. The name can include letters and
numbers; it cannot include underscores.

Font

The font to be used when printing documents on this type of


paper.

Pitch

The pitch to be used when printing documents on this type of


paper.

Page Length

The length of a page of this type of paper. This setting is used


to format output and count pages if the document does not
contain any form feed characters.

Page Delay

An interval to wait between pages. This can be used to slow


down the rate at which data is delivered to the printer to match
the actual rate of printing.

COLUMBUS OM INSTALLATION AND CONFIGURATION

153

154

CHAPTER 6

Setting up printers

Defining paper types

Options properties
Property

Description

Hopper

Specify the input hopper that contains the paper to be used.

Output Hopper

Specify the output hopper into which the completed document


is to be put.

Commands

Specify any commands (using control codes) to perform any


other functions required.

Finishing

Specify finishing attributes which should contain control codes


to be sent to a printer after a document when using this paper
type.

Forms_Mode

Specify whether an overlay is to be applied. For more


information, see Applying overlays on page 168.
To print

Set Forms_Mode to

single-sided, with the data and the


overlay on the same side of the
paper

SIMPLEX

double-sided, with the data on both DUPLEX


sides of the paper, and the same
overlay on both sides of the paper
double-sided, with the data on both DUPLEX2
sides of the paper, and different
overlays on each side.
BOILERPLATE
double-sided, with the data on the
front side of the paper, and different
overlays on each side (for example,
an invoice on the front, with terms
and conditions on the back.)
NONE

no overlay
Orientation properties
Property

Description

Orientation

Either Portrait or Landscape.

Presentation

One of the following:


Option

Description

Simplex

Single sided.

Duplex (SE)

Double-sided, aligned to the shortest edge of


the page.

Duplex (LE)

Double-sided, aligned to the longest edge of


the paper.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Defining paper types

Option

Description

Simplex

Single sided.

Duplex (SE)

Double-sided, aligned to the shortest edge of the page.

Duplex (LE)

Double-sided, aligned to the longest edge of the paper.

Assigning paper types to a printer


1

In Columbus OM Explorer, right-click the icon for the printer, and then click
Mount/Unmount Paper.

In the Mount/Unmount Paper Types dialog box, select the paper types to
mount. You can select as many types as appropriate.

Click OK.

Do one of the following:


To

Do this

Set the printers Any_Paper parameter


process a print request only if the
paper type specified for it is one that is to No.
mounted on the printer
process print requests whatever paper Set the printers Any_Paper parameter
type is specified
to Yes.

Distributing paper types across a network


If you use several Columbus OM print instances, you can set Columbus OM so
that when you create or change the paper types in one instance, it automatically
makes the same changes to the paper types in the other instances.
To distribute the paper types
1

On one instance, create the paper types.


If you have already set up a Columbus OM print instance to distribute remote
printers across a network, create the paper types on the same instance as the
one that you use to configure the remote printers.

COLUMBUS OM INSTALLATION AND CONFIGURATION

155

156

CHAPTER 6

Setting up printers

Defining paper types

On the instances to which you want the paper types to be copied, set these
configuration parameters for netmaster:
Parameter

Set to

Get_Paper_Tabs

Yes

Name_Server

The host and instance on which you will maintain the


paper types, separated by a colon (for example
mars:print1)

To make the changes effective, stop and then restart the netmaster server on
all the instances.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Creating printer classes

Creating printer classes


More efficient printing can be achieved by creating collections of similar printers
called printer classes.: for example, all the printers in one office, or all the colour
printers. When users want to print a document, they choose the class which
contains the sort of printer that they want to use, and Columbus OM selects the
most appropriate printer within the class: usually one that is not currently busy.
Creating a class of printers
1

In Columbus OM Explorer, navigate to Advanced tab


Printer Classes Class menu Create.

In the Class field, type a name for the class.

In the Available Printers list, select the printers that you want to add to the
class.

instance icon

A printer can be in more than one class.


4

Click Add.
Columbus OM Explorer adds the printers to the Current Printers list.

When you have added all the required printers to the class, click OK.

Maintaining printer classes


To

Do this

change the printers


that are in a class

Navigate to: Advanced tab instance icon Printer


Classes. Right-click the printer class, and then click
Modify Class.

delete a class of
printers

Navigate to: Advanced tab instance icon Printer


Classes. Right-click a class, and then click Remove Class.

COLUMBUS OM INSTALLATION AND CONFIGURATION

157

158

CHAPTER 6

Setting up printers

Creating printer groups

Creating printer groups


To make it easier for users to find the printers that have been set up specifically for
their use, create printer groups.
For example, you could add all the printers that have been set up to print
double-sided copies to a printer group called Duplex. Then, any user wanting to
print double-sided documents would only have to open the Duplex folder to see all
the printers that had been set up for this purpose.
Creating a group of printers
1

In Columbus OM Explorer, navigate to Advanced tab


Printer Groups Groups menu Create.

In the Group field, type a name for the group.

Click a printer or class that you want to add, and then click Add.

instance icon

Columbus OM Explorer adds the printers to the Current Printers list.


4

When you have added all the required printers to the group, click OK.

Maintaining printer groups


To

Do this

change the printers


that are in a group

Navigate to: Advanced instance icon Printer Groups.


Right-click the group that you want to change, and then
click Modify Group.

delete a group of
printers

Navigate to: Advanced instance icon Printer Groups.


Right-click the group that you want to delete, and then
click Remove Group.

File location
Printer groups are stored in files in the %UNIQDIR%\media\groups\ folder. The
name of the file is the same as the name of the printer group.
Each file contains a list of the printer servers that are in the group.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Reference

Reference
alias.tab: Server class definitions
The alias.tab file maps server classes to their associated component servers.
File location and name
%UNIQDIR%\servers\alias.tab

Content
The file contains one line for each printer or stream in a class, with two
space-separated fields.
Field

Value

class

The name of the class.

server

The name of a print or stream server in that class.

p_mk.tab: Multiple printer creation


The p_mk.tab file defines configuration keywords used by p_mk when creating
multiple print servers.
for more information, see
File location and name
%UNIQDIR%\menus\p_mk.tab

Content
The file contains one line, with any number of comma-separated fields.
Server,keyword1,keyword2,keyword3,...

A list of print server parameter keywords, always including Server. p_mk


associates the list of keywords in p_mk.tab with the corresponding list of
values from a single line in the user-supplied file to arrive at a set of
configuration parameters for a new print server. Parameters which are not
explicitly defined in this way are set to the default values taken from
%UNIQDIR%\menus\printer.d.

COLUMBUS OM INSTALLATION AND CONFIGURATION

159

160

CHAPTER 6

Setting up printers

Reference

Paper types: File format


Paper types are stored in files in the %UNIQDIR%\media\paper\ folder. The name
of each file is the same as the paper type that it defines.
Content
Each file contains one line for each attribute, with two space-separated fields.
Field

Value

attribute

The name of the attribute.

value

The value of the attribute, enclosed in quotes "..." if it


contains spaces or is null.

Attributes
The configurable name identifiers applicable to a Columbus OM instance are listed
in %UNIQDIR%\menus\def_paper; however several of the names in that file are
actually merged into a composite Attributes setting:
Attributes attribute_list

A space-separated list of apq options enclosed in quotes "...", from this list:
-CO file

General control codes

-FI file

Finishing control codes

-F file

Font control codes

-HP file

Input hopper control codes

-OR file

Orientation control codes

-OH file

Output hopper control codes

-PT file

Pitch control codes

-PR file

Presentation control codes

Forms_Mode SIMPLEX|DUPLEX|DUPLEX2|BOILERPLATE

If applicable, the overlay mode.


Page_Delay number

The number of seconds to delay between pages.


Page_Length number

The number of lines per page.

xcaps command: Finding the features of a printer


The xcaps command produces a report of the features that a printer has. The
report includes information about:

the languages that the printer supports (for example, PCL or PostScript)

the status values that it can return

its input trays

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 6

Setting up printers

Reference

features that can be used as selection criteria by the xselect command, for
example, its resolution (DPI), its duplexing capabilities, and whether it can
print in colour. For more information about the xselect command, see
xselect: Selecting a suitable printer on page 324.
the current queue.

Requirements
For Columbus OM to get the information from a printer, the printer must be:

able to respond to SNMP requests

directly connected to the network

turned on.

Syntax
xcaps printer [snmp] [-q] [-v]

Parameters
printer

The printer: its IP address, its host name, or the name that has been set up in
Columbus OM.
snmp

(Can be used if printer is a printer name.) Uses SNMP to find out the printers
capabilities instead of the channel that is specified for the printer in its
Channel_Type parameter.
-q

Displays the devices queue.


-v

Verbose mode: displays more information while the command runs.


Examples
xcaps 10.0.26.9

or
xcaps MyPrinter

COLUMBUS OM INSTALLATION AND CONFIGURATION

161

162

CHAPTER 6

Setting up printers

Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

163

CHAPTER 7

Chapter 7

Configuring the printer


features

You can change how the printer operates by changing its configuration parameters.
For all the parameters, Columbus OM uses a default setting, which in most cases
will provide the results that you want.
To set the configuration parameters, see page 164.
To

See

accept or reject documents according to Controlling the documents below


their size or contents
accept, reject or change documents
according to their format (for example,
PCL and PostScript)

Supported document formats on


page 166

apply overlays to selected pages

Applying overlays on page 168

print a banner page at the start of every Printing banner pages on page 172
document
change the format of documents

Formatting documents on page 174

specify the format of document to be


printed on a PJL-enabled printer

Specifying document formats for


PJL-enabled printers on page 166

report when a page or document has


Assured delivery on page 181
been actually printed, instead of when it
has been sent to the printer
print documents with the same alias
together

Processing documents in batches on


page 183

control what happens if a document


cannot be printed

Handling documents that fail on


page 182

COLUMBUS OM INSTALLATION AND CONFIGURATION

164

CHAPTER 7

Configuring the printer features

Configuring the printer

Configuring the printer


1

In Columbus OM Explorer, do one of the following

If you are adding a new printer: In the Add New Printer dialog box, click
the Advanced Settings tab.

To change the properties of an existing printer: Advanced tab


icon Printers printer icon Printers menu Modify.

Click

instance

next to the group containing the parameter you want to change.

The list includes only the configuration parameters that apply to the type of
printer that you selected on the Printer tab.
3

Click the parameter whose value you want to change. For more information
about the parameters, see Configuring the printer features on page 163.

Type or select the value of the parameter.

Click OK.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Controlling the documents

Controlling the documents


Testing the size of documents
To

Set this parameter

set a minimum size of documents

Floor

set a maximum size of documents

Ceiling

Testing the contents of documents


You can use programs that test the contents of a document to decide whether the
document is accepted or not.
1

Create a program to test the contents of the document:


If the document is valid, then the program must return a value of zero.
If the document contains an error, the program must:

return a value of not zero.


write a one line message to a file called output.txt in the
%UNIQDIR%\servers\printer folder.

The message must be in this format:


number dd Mon hh:mm:ss text

For example:
210 16 Oct 12:45:04 Invalid document format

The number must be a three-digit number that indicates the type of error, and
what you want Columbus OM to do:
Number range

Description

Columbus OM action

000 099

Information message Continue processing the document.

100 199

Temporary error

Postpone the document.

200 299

Fatal error

Move the document to the


completed queue and set its status
to Failed.

300 399

Configuration error

Postpone the document and disable


the printer.

The maximum length of the text is 32 characters.


2

Set the Input_Filter parameter to the path and name of the program.

COLUMBUS OM INSTALLATION AND CONFIGURATION

165

166

CHAPTER 7

Configuring the printer features

Supported document formats

Supported document formats


Specify which document formats (for example, PCL or PostScript) the printer
supports by setting the following parameters.
PostScript support
Set the PostScript parameter to one of the following:
If the printer

Select

supports only PostScript files

Only

support both PostScript files and non-PostScript files Yes


does not support PostScript files

No

Other supported formats


Set the following parameters to specify which document formats the printer
supports.
To specify the document formats that

Set this parameter

the printer supports

Codes_Accepted

the printer does not support

Codes_Barred

Use these parameters in conjunction with the Codes_Filtered parameter (see


Changing document formats below. For example, if you specify some document
formats for the Codes_Accepted and Codes_Filtered parameters, then you can
leave the Codes_Barred parameter blank, and every code that is not accepted or
filtered will be barred.
Specifying document formats for PJL-enabled printers
When printing a PostScript or PCL format document to a PJL-enabled printer using
the pjlout driver, you must specify the format of the document if the printer is
unable to automatically recognize it.

Changing
document
formats

If the printer is able to recognize the format of the document, set the printers
Set_Language parameter to No.

If the printer is unable to recognize the format of the document, set the printers
Set_Language parameter to Yes.

You can change the format of a document by using a filter program before it is
printed. For example:

A PCL document can be printed on a printer that supports only PostScript by


by first filtering the document through a PCL-to-PostScript program, if you
have one.

Control characters can be added or removed to match the exact requirements


of a printer.

There are two ways of doing this:

Method 1 affects all documents that are processed by the printer.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Supported document formats

Method 2 affects only documents that are in selected formats.

To convert ASCII (plain text format) files to PostScript, see Converting text
documents to PostScript on page 167.
Method 1

Set the Input_Filter parameter to the path and name of the filter.

Method 2
1

Specify which formats you want to be filtered by setting the Codes_Filtered


parameter.
For example, to filter PostScript and PCL format documents, set the
Codes_Filtered parameter to PostScript,PCL.
Use this parameters in conjunction with the Codes_Accepted and
Codes_Barred parameters. For example, if you set Codes_Accepted to accept
PCL files, and Codes_Barred to reject PostScript files, then the Columbus OM
print instance will filter all other codes: you do not have to specify them by
using the Codes_Filtered parameter.

Set the Code_Filter parameter to the path and name of the filter program.

Converting text documents to PostScript


If the printer can print only PostScript files, and you want it to convert text files into
PostScript so that it can print them, set the printers Postscript_Filter
parameter to:
%UNIQDIR\programs\commands\ps_filter

If you want the printer to ignore non-PostScript files, leave the


PostScript_Filter parameter blank.

COLUMBUS OM INSTALLATION AND CONFIGURATION

167

168

CHAPTER 7

Configuring the printer features

Applying overlays

Applying overlays
If your printer supports overlays, this section explains how to set up Columbus OM
so that overlays can be applied to documents. Columbus OM prints the overlay on
top of the document to create the final output.
To apply an overlay, you need to:

Creating an
overlay

create a file that contains the overlay

assign the file to a paper type

set up the printer to use that printer type.

Create the overlay as a image file, by using a PC application such as Microsoft


Word or PaintBrush.
You can create different overlays for different parts of the document.
For single-sided printing, you can create two separate overlays: one for the first
page of the document, and one for all of the other pages that are in the
document.
For double-sided printing, you can create four separate overlays, that are
applied to:

the first page in the document

the back of the first sheet of the document (that is the second page of data)

the front of all the other sheets in the document (the odd-numbered pages)

the back of all the other sheets in the document (the even-numbered pages).

Print the document to a file, using a printer driver that is supported by the
printer that you want to use.
Give the file the same name as the paper type to which it relates.

Create a folder on the host to contain the file:


%UNIQPRINT%\media\print\printer_type\FORMS\usage

where:

printer_type is the name of the printer type that will use the overlay.

usage is one of the following:

For an overlay to be applied to

Use

the first page in the document

INITF

the back of the first sheet of the document (that is the second page INITB
of data)

the front of all the other sheets in the document (the


odd-numbered pages)

OVLYF

the back of all the other sheets in the document (the


even-numbered pages)

OVLYB

Copy the file into the folder.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Applying overlays

The application used to create the overlay might have included unwanted
information. To tidy the file, use the ovclean program (see ovclean: Create
overlay files on page 169.

Guidelines for creating an overlay

Avoid print commands such as printer reset (<Esc>E) because they can affect
the subsequent printed data.
On HP printers and compatibles, do not use these escape codes:
<Esc>E (printer reset)
<Esc>&|#X (number of copies)
<Esc>&|#S (simplex/duplex instructions)
<Esc>&|#A (paper size), or any other codes that are described as paper

control
<Control-L (formfeed)

Any HP-GL instructions

If a value is SET in the overlay file, it remains set when the main data is printed,
unless you specifically reset the value.

If the printer does not support overlays in hardware (the graphic cannot be
stored in the printers memory), then the file must include a cursor position to
the origin (0,0) at the end to reset the print position ready for the user data.

ovclean: Create overlay files


The ovclean command converts a PCL file to a format suitable for use as an
overlay file.
Syntax
To convert a file:
ovclean -clean [-force] [-list] [-macro number] pcl_file ov_file

To install a file that has been converted:


ovclean -install [-force] ov_file printer_type [overlay]

To create a paper type for use with the overlay:


ovclean -paper [-force] overlay

Parameters and options


-clean|-c

Convert pcl_file to ov_file ready for use as an overlay.


-force|-f

If the output file already exists, overwrite it without prompting for


confirmation.
-help|-h

Display command help.

COLUMBUS OM INSTALLATION AND CONFIGURATION

169

170

CHAPTER 7

Configuring the printer features

Applying overlays

-install|-i

Install a converted file ov_file as the overlay for printer_type by copying it


to %UNIQDIR%\media\print\printer_type\FORMS, optionally changing the
name to overlay.
-list|-l

Display information during the conversion process.


-macro|-m number

Use macro number to specify the conversion process; the default is 14.
-paper|-p

Create a dummy paper_type definition for the specified overlay as


%UNIQDIR%\media\paper\overlay.
1 Set up a paper type. See Defining paper types on page 153.
Configuring the
printer to use an 2 Specify which pages you want the overlay to be applied to by setting the
overlay
Forms_Mode parameter for the paper type:
To print

Set Forms_Mode to

single-sided, with the data and the overlay on the


same side of the paper

SIMPLEX

double-sided, with the data on both sides of the paper, DUPLEX


and the same overlay on both sides of the paper
double-sided, with the data on both sides of the paper, DUPLEX2
and different overlays on each side
double-sided, with the data on the front side of the
paper, and different overlays on each side (for
example, an invoice on the front, with terms and
conditions on the back)
3

BOILERPLATE

If duplex printing is being used, you must set up files that contain the
commands to set up the printer into the correct mode. These are:
PORTRAIT

Simplex portrait.

LANDSCAPE

Simplex landscape.

DUPPORTLE

Duplex portrait long edge binding.

DUPLANDLE

Duplex landscape long edge binding.

DUPPORTSE

Duplex portrait short edge binding.

DUPLANDSE

Duplex landscape short edge binding.

Set the printers Paper_Type parameter to use the paper type.

Set the printers Forms_Flash parameter:


To send the overlay

Set Forms_Flash to

only once, at the start of the document

HARD

with every page

SOFT

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Applying overlays

Some printers have extra memory that can store graphical overlays, so
Columbus OM has to send the overlay to the printer only once, at the start of
the document. If the printer does not have this extra memory, then
Columbus OM has to send the overlay with each page, which slows down the
printing.

COLUMBUS OM INSTALLATION AND CONFIGURATION

171

172

CHAPTER 7

Configuring the printer features

Printing banner pages

Printing banner pages


You can print a banner page in front of every document.
To print banner pages for printers that use the xprinter driver, see Banner pages
for xprinter on page 192.
Creating a banner page
Create a file that contains what you want on the banner page.
The Columbus OM print installation includes sample files that you can use:
banner.pcl and abanner.pcl. Both of these are for PCL printers.

For a PCL printer, the banner page can include substitution variables (see
page 603). You can simulate large characters by including the keyword banner.
For example, if you include BANNER %OWNER, Columbus OM prints the owners
name in large characters. To specify the maximum width of this large text, include
a number in brackets after BANNER, for example: BANNER(80) %OWNER.
To print the banner page on different paper to that used for the document itself,
you might be able to include control characters at the start (to select an alternative
paper tray) and at the end (to reset the paper tray). For more information, see the
printers documentation.
If the printer supports both PostScript and non-Postscript documents, you can
create two banner files.
Configuring Columbus OM to print banner pages
To print a banner page

Do this

with all documents on all printers

Set the Print_Banner parameter in the


system defaults file (default.tab) to
Yes.

with all documents on a specific printer See Configuring individual printers to


print a banner page below
Include the -b parameter in the apq
command.

with only specific documents

Configuring individual printers to print a banner page


Set these parameters for the printer:
Parameter

Value

Banner

Yes

Banner_File

The path and name of the file that contains the banner
page. If the banner page is in PostScript format, set the
Banner_PSFile parameter instead.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Printing banner pages

Parameter

Value

Banner_FF

To output a formfeed code after the banner page, specify


Yes.

PostScript_End

If the printer supports only PostScript files, specify the


PostScript comment string to be sent after the banner. The
default string is %-END-PS.

COLUMBUS OM INSTALLATION AND CONFIGURATION

173

174

CHAPTER 7

Configuring the printer features

Formatting documents

Formatting documents
This section explains the parameters that you can use to format documents.
You might not need to set any of the parameters because most applications that
produce documents also format them.
To

See

define text to be printed at the top or bottom of Headers and footers below
every page
control the printer, for example to specify the
default font to be used

Printer control on page 175

set a default font

Default font on page 176

set default values for some of the other


formatting option

Other formatting defaults on


page 176

make wide documents fit the page by changing Formatting text files to fit the
the orientation or pitch
paper on page 178

Headers and
footers

print multiple page images on single sheets

Printing multiple page images


on single sheets on page 179

format the document by embedding control


characters in it

Intervention strings on
page 177

You can add a header and a footer at the top and bottom of every page.
1

Create a file that defines the format of the header or footer (see Header and
footer file format below).
The file can be stored anywhere on the host.
To print both a header and a footer, create a separate file for each.

Set these parameters for the printer:


Parameter

Value

Header and/or
Footer

The name of the appropriate file. To use environment


variables in the filename, enclose them in braces.

Page_Width

The width of the header and footer.

Header and footer file format


LEFT text
CENTRE text
RIGHT text
BEFORE_GAP lines
AFTER_GAP lines

Parameters
text

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Formatting documents

The text that you want to be printed. The text can include substitution
variables, for example %TIME for the current time or %DOCUMENT for the
documents filename.
lines

The number of blank lines to be printed between the header or footer and the
rest of the document.
Example file
LEFT %OWNER
CENTRE %DOCUMENT
RIGHT Page %MESSAGE
BEFORE_GAP 0
AFTER_GAP 1

This file prints a header or footer that looks like this:


JS

Printer control

Report1.doc

Page 1

Use the following parameters to control the printer, for example, to add form feeds.
To

Parameter

Value

send instructions (control


characters) to the printer
before each document

Command

The path and name of a file


that contains the instructions.
(Not used for PostScript
printers.)

send instructions after each


document

Finishing

The path and name of the file.


(Not used for PostScript
printers.)

send data to the printer before Prefix


each document

The path and name of the file


that contains the data.

Suffix

The path and name of the file


that contains the data.

send data to the printer after


each document

CR_Required
force the printer to print a
carriage return character after
every newline character

Yes

produce a formfeed at the start Leading_FF


of each document

Yes

produce a formfeed between


pages

COLUMBUS OM INSTALLATION AND CONFIGURATION

Format

This should not need to be set


on most modern printers.

Format

175

176

CHAPTER 7

Configuring the printer features

Formatting documents

To

Parameter

produce a formfeed at the end Trailing_FF


of a document (this is used to
flush the last page from some
laser printers)

Value
Yes

send null characters at the end Trailing_Nulls The number of characters.


of a document
To use environment variables in any path and filename, enclose them in braces.

Default font

To set a default font to be used, set the Font parameter.

For a non-PostScript printer


Specify the control code sequence. For example, for an HP LaserJet,
<esc>(s1S changes the font to italic, and <esc>(s0S changes the font to
normal.

For a PostScript printer


Specify the text in the format:
/ name -sn -xn -yn -in -ln

where:
name

The name of the font known to PostScript, for example Courier or


Times.

-sn

The scale or point size of the font.

-xn

The x-coordinate of the left margin in 1/72 inches.

-yn

The y-coordinate of the top margin in 1/72 inches.

-in

The increment in the y-coordinate between lines.

-ln

Lines of text on a page.

For example:
/ Courier -s10 -x30 -y780 -i11 -l66

Other formatting To set default values for the hopper, orientation and so on, set these parameters.
For each parameter, specify the control codes that select the default value that you
defaults
want. For information about the control codes to use, see the printers
documentation.
These parameters might be overriden by the values set for the printers paper type.
These parameters do not affect PostScript printers.
Parameter

Sets the default

Hopper

input hopper

Orientation

orientation (that is portrait or landscape)

Output_Hopper

output hopper

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Formatting documents

Parameter

Sets the default

Pitch

pitch (for example: 10, 12 or 16)

Presentation

presentation (for example, simplex or duplex)

For example, to set the default pitch to 10 on an HP LaserJet printer, set the Pitch
parameter to <esc>&k0S.

Intervention
strings

You can create documents that contain control codes to change values such as the
font and orientation.
1

Create a file that contains the control codes.

In the document, add a command:


If the command is

Specify

on a line of its own

string filename

within other text

string(filename)

Replace:

string with a word that indicates what the command does. For example,
to change the font, you could use ##CHANGEFONT. You can use any word, as
long as that word does not appear anywhere in the main text of the
document.
filename with the name of the file that you created in step 1.

To tell Columbus OM what string you have used, specify one of the
following parameters:
To specify a string that

Set this parameter

obeys a user-defined command

Co_Intervention_String

includes a file that contains user-defined


commands

Fi_Intervention_String

specifies a font

Ft_Intervention_String

uses paper from a different hopper

Hp_Intervention_String

changes the hopper into which the completed Oh_Intervention_String


document is put
changes to a different orientation

Or_Intervention_String

changes the presentation

Pr_Intervention_String

changes the pitch

Pt_Intervention_String

Example

To change the font to Helvetica:


1

Create a file that contains the control codes that change the font to Helvetica.
Call the file helvetica.cmd.

In the document, at the point where you want to change the font, add:

COLUMBUS OM INSTALLATION AND CONFIGURATION

177

178

CHAPTER 7

Configuring the printer features

Formatting documents

##CHANGEFONT(helvetica.cmd)
3

Formatting text
files to fit the
paper

Set the Ft_Intervention_String parameter to ##CHANGEFONT.

You can make sure that documents that are in ASCII-text fit on the paper by either:

changing the paper orientation (for example, if the file contains very long lines,
you can print it on landscape orientation instead of portrait)

changing the font pitch.

To format text files according to their line-width

Set these parameters for the printers:


Parameter

Value

Prefix

A file that Columbus OM will use to hold the reformatted


document temporarily.

Input_Filter

%UNIQDIR%\programs\tools\rotate length [printer]


[attribute value1 value2]

(See Parameters for the rotate program below.)


Parameters for the rotate program
length

A number of characters. Documents that contain lines of this length or less are
affected by what you specify in attribute value1. Documents that contain
lines longer than this length are affected by what you specify in value2.
printer

The name of the printer, as set in Columbus OM.


attribute

The attribute to change, either ORIENTATION or PITCH.


value1

What you want to change the attribute to if the document contains short lines,
for example PORTRAIT or 12.
value2

What you want to change the attribute to if the document contains long lines,
for example LANDSCAPE or 16.
Example 1
..\..\programs\tools\rotate 80 ORIENTATION PORTRAIT LANDSCAPE

This example prints a text file in:

portrait format if it contains only lines with 80 or less characters

landscape format if it contains any lines with more 80 characters.

Example 2
..\..\programs\tools\rotate 80 PITCH 12 16

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Formatting documents

This example prints a text file in:

12 pitch if it contains only lines with 80 or less characters

16 pitch if it contains any lines with more than 80 characters.

Error handling
If the rotate program encounters any errors, Columbus OM disables the printer
and writes a message in its day log.
Error

Description

Wrong number of arguments

Check that the Input_Filter


parameter has been set correctly.

Invalid line length

Line length specified must be a positive


number.

Cannot open printer


configuration

The Columbus OM printer


config.tab file could not be read.

No prefix file specified

Check that the printers Prefix


parameter has been set correctly.

No printer type specified

Check that the printers Printer_Type


parameter has been set correctly.

Invalid attribute xxx/yyy/zzz

Check the printer type attributes.

Cannot update prefix file

Might indicate a problem with


permissions on the file specified by the
Prefix parameter.

Printing multiple Multiple page images can be printed on a single side of paper, by reducing the size
page images on of each page image. This feature is available for ASCII format files printed on HP
and compatible printers.
single sheets
A four page document
is usually printed on
four sides

2-up prints two pages


on each side

4-up prints four pages


on each side

Page 1

Page 1

Page 2

Page 2

Page 1

Page 2

Page 3

Page 4

Page 3

Page 1
Page 2
Page 3
Page 4

COLUMBUS OM INSTALLATION AND CONFIGURATION

Page 3

Page 4

Page 4

179

180

CHAPTER 7

Configuring the printer features

Formatting documents

To print multiple page images

Set these parameters for the printer (see Configuring the printer on page 164):
Parameter

Set to

Format

No

Any_Paper

Yes

Paper_Mandatory

No

Output_Filter

use the multipage program (see below)

Using the multipage program

To always print 1-up, 2-up or 4-up, set Output_Filter to:


%UNIQDIR%\programs\tools\multipage -p images

where images is 1UP, 2UP or 4UP.

To enable the user to select what type of multiple images to print, set
Output_Filter to:
%UNIQDIR%\programs\tools\multipage %SERVER_INFO

Then mount the paper types that are associated with multipage printing: one or
more of 1UP, 2UP and 4UP (see Assigning paper types to a printer on
page 155). You can also create your own paper types that print multiple images
by setting their Orientation to either 2UP or 4UP.
When you add a print request, choose the appropriate paper type.

To set a default which the user can override by choosing a paper type, set
Output_Filter to:
%UNIQDIR%\programs\tools\multipage -p images %SERVER_INFO

where images is 1UP, 2UP or 4UP.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Assured delivery

Assured delivery
Assured delivery tells you when a page or a document is printed instead of when it
has been sent to the printer.
This feature works with PJL-enabled printers (including HP printers and
compatible printers) that are connected to the host or to the network.
With this feature, the printer pauses at the end of each page, after every 2000
characters, or at the end of each document. When it has confirmed that the text has
been printed, it prints the next part of the text.
To use it, set the printers Driver parameter:
To check

Set Driver to

at the end of each page (this option can be used only


with text files)

pjlout -t

after every 2000 characters

pjlout

at the end of each document

pjlout -e

COLUMBUS OM INSTALLATION AND CONFIGURATION

181

182

CHAPTER 7

Configuring the printer features

Handling documents that fail

Handling documents that fail


You can control what happens if Columbus OM cannot print a document the first
time that it tries. You can specify how many times you want it try, and how often
you want it to try.
1

Set the Attempts_Limit parameter to the maximum number of times that you
want Columbus OM to attempt to print a document.
If it cannot print the document after this number of attempts, it sets the
documents status to Failed, moves it to the completed queue, and stops
trying to print it.
If you want Columbus OM to try only once to print each document, set this
parameter to either 0 or 1:

0 tries to print the document once, and sets the documents status to
Completed whether or not it was successful.
1 tries to print the document once, and if it fails, sets the documents status

to Failed.
2

Set the Postpone_Time parameter to specify the interval (in seconds) between
trying again to print a document if it fails the first time.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 7

Configuring the printer features

Processing documents in batches

Processing documents in batches


To print a group of documents together, give them all the same alias.
Columbus OM then searches the pending queue for all documents with the same
alias, and then prints them before moving onto the next document. To enable this
feature for a printer, set these parameters for it:
Parameter

Value

Batch_Aliases

Yes

Alias_Limit

The maximum number of documents in each batch.

Alias_Banner

If you want to print a banner in front of the first


document in each batch, set this parameter to Yes.

Alias_Banner_File or
Alias_Banner_PSFile

The name of the banner file to be printed.


Columbus OM includes an example banner file for
use with PCL printers called abanner.pcl. The
default banner is: %UNIQDIR%\config\abanner.def

COLUMBUS OM INSTALLATION AND CONFIGURATION

183

184

CHAPTER 7

Configuring the printer features

Processing documents in batches

COLUMBUS OM INSTALLATION AND CONFIGURATION

185

CHAPTER 8

Chapter 8

Using the xprinter driver

The xprinter driver provides enhanced communication with a device. As well as


sending instructions to print documents to the device, it can handle information
returned by the device, enabling it to monitor the progress of documents.
The xprinter driver improves control over secure printing, overlapped printing,
and recovery actions.
For information about

See

the types of device that can use the


xprinter driver

Devices supported by xprinter on


page 186

how to configure a device to use xprinter Configuring a printer to use the xprinter
driver on page 188
the modes in which xprinter can deliver xprinter delivery modes on page 189
documents
control what happens if a page or
document does not print

Handling delivery failures on page 195

control what happens if a printer cannot Handling stalled printers on page 195
complete a document
print banner pages at the start of a
document or to warn of problems

Banner pages for xprinter on page 192

track the progress of documents

Monitoring entries submitted to


xprinter on page 195

examples of configuring specific types of Example configurations for xprinter on


printer
page 198

COLUMBUS OM INSTALLATION AND CONFIGURATION

186

CHAPTER 8

Using the xprinter driver

Devices supported by xprinter

Devices supported by xprinter


To use a device with xprinter, the device must:

be directly connected to the network

support one of xprinters channels (see below).

Channel types
Channel

Description

Example

COMMAND

Data is sent the device by a piped Lexmark PrintCryption printers:


command.
use the Lexmark dcp command.
See also Connecting to printers
using commands on page 201.

IPP

Internet Printing Protocol

NLPD

Data is sent to the device by using Xerox NPS printers.


the lpr/lpd protocol.
See also Using the lpr/lpd
The devices onboard spooler is protocols on page 187 and
Configuring Xerox printers on
an lpr/lpd variant. This used to
page 198.
get the devices status.

PJL

Data is sent to the device by using HP and Lexmark laser printers


that support PJL.
a raw socket.

See Configuring IPP printers on


page 200.

PJL is inserted into the datastream


to control the device and to obtain
the status
RAW

Data is sent to the device by using Any non-spooled printer that


supports raw socket
a raw socket.
communication.
No printer control is used; this is
See also Raw delivery mode on
similar to other Columbus OM
page 191.
drivers.
Columbus OM can confirm when
the data has been sent to the
device; it cannot get information
back from the device about the
status of the document.

RAWLPD

Data is sent to the device by using Any non-spooled printer that


supports raw socket
the lpr/lpd protocol.
communication.
Columbus OM can confirm when
See also Using the lpr/lpd
the data has been sent to the
device; it cannot get information protocols on page 187.
back from the device about the
status of the document.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Devices supported by xprinter

Channel

Description

Example

SNMP

Data is sent to the device by using Xerox DocuCentre printers (for


example, Xerox 440) and Xerox
the lpr/lpd protocol.
WorkCentre Pro printers.
SNMP is used to control the
device and get its status.

VIP

Data is sent to the Emtex VIP


subsystem

Emtex VIP-connected printers


configured to send documents to
an IPDS device.
See also Configuring Emtex
VIP-connected printers on
page 199.

WLPD

Data is sent to the device by using Xerox DocuPrint with Windows


controller.
the Windows lpr/lpd protocol.
The devices onboard spooler
uses the Windows version of
lpr/lpd. This is used to get the
devices status.

See also Using the lpr/lpd


protocols on page 187 and
Configuring Xerox printers on
page 198.

XLPD

Data is sent to the device by using Xerox DocuSP printers.


the lpr/lpd protocol.
See also Using the lpr/lpd
The devices onboard spooler is protocols on page 187 and
Configuring Xerox printers on
an lpr/lpd variant. This used to
page 198.
get the devices status.

XPP

The XPP/XPP2 protocol is used


to send data and to control the
device

XPP1

XPP printers.
The XPP1 protocol is used to
send data and to control the
device. This channel is usually
used only for testing and resolving
problems with the XPP/XPP2
protocol.

XPP printers.

Using the lpr/lpd protocols


UNIX: If you want to use the lpr/lpd protocols, and you want them to use reserved
ports (that is, the Use_Reserved_Ports parameter is set to Yes), xprinter must
run as root. For more information about how to make it do this, see the operating
systems documentation.

COLUMBUS OM INSTALLATION AND CONFIGURATION

187

188

CHAPTER 8

Using the xprinter driver

Configuring a printer to use the xprinter driver

Configuring a printer to use the xprinter driver


1

Add a new printer server. See Adding printers on page 130.

In the Add New Printer dialog box, select XPrinter, and then click the
XPrinter Details tab.

Set these properties:

Property

Description

Host Name

The network name or IP address of the printer.

Port Number

The port number that the printer uses.

Channel Type

See Devices supported by xprinter on page 186.

On Advanced Settings tab, set other parameters as required, and then click
OK.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

xprinter delivery modes

xprinter delivery modes


xprinter supports these delivery modes:

standard

secure (secure at page level)

overlapping (secure at document level)

Standard
delivery mode

raw (similar to standard printer driver operation; there is no communication


with the printer).

In standard job delivery mode, Columbus OM sends documents one a time.


Columbus OM sends the next document only when the printer has sent a message
that it has finished printing the previous document.
Requirements

The device must support PJL.

To configure a device to use standard delivery mode

Set these parameters:

Secure delivery
mode

Parameter

Value

Server

A name to identify the server.

Medium

print

Device

"NETWORK ip_address 9100"

Channel_Type

PJL

Delivery_Mode

""

In secure delivery mode, Columbus OM sends the document one page at a time.
Columbus OM sends the next page only when the printer has sent a message
confirming that it has finished printing the previous page.
If Columbus OM does not receive the confirmation message from the printer, it
can take remedial action. See Handling delivery failures on page 195.
Secure printing is slower than other methods.
Requirements

The device must support PJL.

This feature cannot be used with devices that have an onboard queue.

To configure a device to use secure delivery mode

Set these parameters:


Parameter

Value

Server

A name to identify the server.

Medium

print

COLUMBUS OM INSTALLATION AND CONFIGURATION

189

190

CHAPTER 8

Using the xprinter driver

Overlapping
delivery mode

xprinter delivery modes

Parameter

Value

Device

"NETWORK ip_address 9100"

Channel_Type

PJL

Delivery_Mode

secure

Page_Mode

intelligent

Overlapping delivery mode with xprinter provides fast delivery with end-to-end
security.
Columbus OM sends the documents to the printer as fast as it can. It sets the status
of an entry to Completed only when the printer has confirmed that it has finished
printing the document.
If an error occurs, remedial action can be taken. If the job control language is PJL,
recovery is at page level. An error banner page can be printed, indicating if any
pages might have been duplicated.
Overlapping delivery mode is faster than secure printing (see Secure delivery
mode on page 189), and is secure at document level.
Requirements

The device must:

be able to respond to one of the supported job control protocols


support one or more of these channel types: PJL, SNMP, XPP, XLPD. (See
Devices supported by xprinter on page 186.)

To configure a device to use overlapping delivery mode

Set these parameters:


Parameter

Value

Server

A name to identify the server.

Medium

print

Device

"NETWORK ip_address 9100"

Delivery_Mode

Overlapping

If the device has an onboard queue, also set these parameters:


Parameter

Value

Channel_Queue

The name of the devices onboard queue.


For a Xerox DocuCentre printer, the name is print.

Hard_Queue

If the onboard queue is disk-based or non-volatile, set this


parameter to Yes.

Max_Overlap

If the device has an internal queue, set this parameter to the


maximum number of jobs that can be processed at once.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Raw delivery
mode

Using the xprinter driver

xprinter delivery modes

Raw delivery mode is similar to the standard printer driver operation. There is no
communication with the printer. As soon as Columbus OM has sent all of the data
for a document to the printer, it sets the status of the entry to Completed.
To configure a device to use raw delivery mode

Set these parameters:


Parameter

Value

Channel_Type

RAW

Device

"NETWORK ip_address 9100"

Medium

print

Server

A name to identify the server.

COLUMBUS OM INSTALLATION AND CONFIGURATION

191

192

CHAPTER 8

Using the xprinter driver

Banner pages for xprinter

Banner pages for xprinter


Banner pages can be used to indicate:

the start of a document

the reprinting of a document that had an error and was not completed

that a document has been restarted.

The banner page is separate from the document: that is, it is produced by
Columbus OM and not by the application that produced the document; and it is
not included in the page count for the document.

Printing banner
pages

Printing banner pages on all devices


To configure all devices to print banner pages, set the Printer_Banner parameter
in the system defaults file (default.tab) to Yes.
Printing banner pages on specific devices
To configure an individual device to print banner pages, set these parameters in its
configuration file:
Parameter

Description

Banner

Set to Yes.
See also Printing banner pages on page 172.

XBanner_Type

See Setting the banner page format (XBanner_Type


parameter) below.

Error_Banner

To print a banner page when an error occurs, set this


parameter to Yes.

XError_File

(If Error_Banner is set to Yes.) The path and name of a file


to be printed when a warning or error message occurs.

Setting the banner page format (XBanner_Type parameter)

Set the XBanner_Type parameter according to the printer languages that the
printer supports.
If the printer supports

Set XBanner_Type to

only text

TXT

only PCL and text

PCL

only PostScript

PS

PCL, PostScript and text

PCL

Columbus OM uses a banner that is in the same


format as the document.
Most modern printers support PCL, so you are most likely to use the PCL setting.
If the printer supports PostScript, make sure that either:

its PostScript parameter is set to Yes

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Banner pages for xprinter

its Code_Filter parameter is set to ps_filter, and its Codes_Filtered


parameter is set to TEXT.

Using different banner pages


To print different banner pages from the default ones, create the alternative pages
in a file, and then set these parameters in the printers configuration file:
Parameter

Description

XBanner_File

Path and name of a banner page file.

XNormal_Message

Text to be printed on the normal banner page.


This parameter overrides the message that is in the
xnormal_message.tab file.

XReprint_Message

Text to be printed on the banner page when a document is


reprinted.
This parameter overrides the message that is in the
xreprint_message.tab file.

XResume_Message

Text to be printed on the banner page when a document is


resumed.
This parameter overrides the message that is in the
xresume_message.tab file.

XTemplate_File

Path and name of a template banner page.


This parameter replaces the xtemplate.pcl,
xtemplate.ps or xtemplate.txt file.

Banner pages
available

Standard banner page


The standard banner page can be printed at the start of each document. The
information on this banner page includes the name of the document and the
number of pages that it contains.
To change the standard banner page, see Customizing the banner pages below.
Banner pages for warnings and errors
Special banner pages can be printed if a warning or error occurs. The information
on these banner pages can include:

the number of pages that have been confirmed as printed so far

how many pages are still to be printed, and if any pages will be reprinted
(taking into account the action that is specified by the Unconfirmed_Action
parameter: see Handling delivery failures on page 195).

To print these banner pages, use the Error_Banner and XError_File parameters.

COLUMBUS OM INSTALLATION AND CONFIGURATION

193

194

CHAPTER 8

Using the xprinter driver

Customizing the
banner pages

Banner pages for xprinter

To customize the banner pages, edit the template files that are in the
Columbus OM config folder.
Banner page template files
There are separate files for each format:

xtemplate.pcl

xtemplate.ps

xtemplate.txt.

In the template file, you can change the literal text and substitution variables. For
example, the xtemplate.pcl file looks like this:
UID:
%UID
Name: %DOCUMENT
Owner: %OWNER
%MESSAGE

Messages on the banner pages


To change the content of text (that is, the %MESSAGE variable), edit these files:

%UNIQDIR%\config\xnormal_message.tab

xpreprint_message.tab

xresume_message.tab.

More information about how to use these files is contained in the files themselves.
To change the language in which the message is displayed, see Changing the
language used for banner pages below.
These files are used by all xprinter devices. To change the messages used by a
specific xprinter device, see Using different banner pages on page 193.
To print the messages that are displayed on the banner pages in a different
Changing the
language, do the following:
language used
for banner pages 1 Copy the set of files for the appropriate language from the %UNIQDIR%\lang
folder to the %UNIQDIR%\config folder.
2

Change the file names to xnormal_message.tab, xpreprint_message.tab


and xresume_message.tab (overwriting the existing files).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Monitoring entries submitted to xprinter

Monitoring entries submitted to xprinter


When you print a document using a xprinter printer, Columbus OM creates a
status log specifically for that entry. To display the status log for an entry in
Columbus OM Explorer, right-click the entry, and then click Status Log.

Handling delivery failures


If Columbus OM does not receive a message back from the printer that confirms
that a page or document has been completed, you can reprint part of the document,
or assume that it has actually completed.
Requirements

The printer must support PJL.

To specify the action

Set the Unconfirmed_Action parameter:


To

Set Unconfirmed_Action to

reprint from the last confirmed job

RESTART

reprint from the last confirmed page

RESUME

assume that the job has been completed, COMPLETE


and move it to the completed queue
take no action

Leave blank.

See also Banner pages for warnings and errors on page 193.

Handling stalled printers


You can control what happens if a printer cannot complete printing a document
(for example, if it runs out of paper or has been taken offline). You can redirect the
output to another printer, restart the document on the same printer, cancel the
entry or disable the printer.
Requirements

The device must support PJL, and the Channel_Type parameter must be set to
PJL.
The delivery mode must be either secure or standard (as indicated by the
devices Delivery_Mode parameter). See also xprinter delivery modes on
page 189.

Setting the actions for a printer


Do one of the following:

Command line: Edit this file:


%UNIQDIR%\servers\printer_name\blockact.tab.

Columbus OM Explorer: Advanced tab instance icon


icon File menu Properties Xprinter details tab

COLUMBUS OM INSTALLATION AND CONFIGURATION

Printers
Actions.

printer

195

196

CHAPTER 8

Using the xprinter driver

Monitoring entries submitted to xprinter

Entry format
The file contains one line for each status.
status

delay

action

offset

destination

Field

Value

The status that the printer might report, one of:


Buffer_Full

Offline_Error

Processing

Cover_Open

Offline_No_Error

Ready

Error

Offline_No_Info

Ribbon_Jam

Intray_Empty

Other

Ribbon_Low

Intray_Missing

Outtray_Full

Service

Maintenance

Outtray_Missing

Toner_Low

Marker_Missing

Outtray_Near_Full

Unavailable

No_Ribbon

Paper_Jam

Unknown

No_Toner

Paper_Low

Warmup

Offline

Paper_Out

The period (measured in seconds) that the status must last for, before the
action is performed.

What to do when the status occurs. One of:


Action

Description

DISABLE

Disable the current printer.

FAIL

Fail the current entry.

IGNORE

Ignore the status.

REDIRECT

Redirect the document to a different printer.


Specify the printer by using the destination
parameter, and specify the page at which to
restart by using the offset parameter.

REPOSITION

Continue printing the document on the current


printer.
Specify the page at which to restart by using the
offset parameter.

(Used with the REPOSITION and REDIRECT actions.) Where to continue


printing the document from:
Offset

Description

Continue from the current page

-n

Go back and reprint n pages.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Field

Using the xprinter driver

Monitoring entries submitted to xprinter

Value
+n

Skip n pages.

(Used with the REDIRECT action.) The name of the printer to use. The
printer must be the same type as the original printer.

Example blockact.tab file


# Status
# ----------TONER_LOW
COVER_OPEN
ERROR
PAPER_JAM
PAPER_OUT
UNAVAILABLE

Delay(secs)
----------12
15
5
64
50
5

Action
---------REPOSITION
REDIRECT
REDIRECT
FAIL
DISABLE
REDIRECT

Offset
------5
0
0

Destination
-----------

MyPrinter2

MyPrinter2
MyPrinter2

In this example, the actions include:

If the printer reports that its toner is low, and the message appears for at least
12 seconds, Columbus OM reprints the previous 5 pages of the document, and
then prints the rest of the document.

If the printer reports that its cover is open (perhaps because it is being
serviced), Columbus OM redirects the document to a different printer,
MyPrinter2.

COLUMBUS OM INSTALLATION AND CONFIGURATION

197

198

CHAPTER 8

Using the xprinter driver

Example configurations for xprinter

Example configurations for xprinter


This section shows how to configure xprinter to support some specific printers.
These examples work in most situations: you might need to change them to meet
the needs of your environment.

Configuring Xerox printers


Xerox DocuCentre 440ST and Xerox DocuColor
Xerox DocuCentre 440ST printers and Xerox DocuColor printers have a
disk-based onboard queue.
Parameter

Value

Server

name

Medium

print

Device

"NETWORK ip_address 515"

Channel_Queue

PRINT

Channel_Type

SNMP

Delivery_Mode

Overlapping

Hard_Queue

Yes

Xerox DocuPrint and Xerox DocuTech with DocuSP controller


Xerox DocuPrint and Xerox DocuTech printers with a DocuSP controller run the
Xerox version of lpd.
Parameter

Value

Server

name

Medium

print

Device

"NETWORK ip_address 515"

Channel_Queue

Usually PRINT. Check the printers documentation for


the correct value.

Channel_Type

XLPD

Delivery_Mode

Overlapping

Hard_Queue

Yes

Xerox DocuPrint with NPS controller


Xerox DocuPrint printers with a NPS controller run the NPS version of lpd.
Parameter

Value

Server

name

Medium

print

Device

"NETWORK ip_address 515"

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Example configurations for xprinter

Parameter

Value

Channel_Queue

Usually PRINT. Check the printers documentation for


the correct value.

Channel_Type

NLPD

Delivery_Mode

Overlapping

Hard_Queue

Yes

Xerox DocuPrint with Windows controller


Xerox DocuPrint printers with a Windows controller run the Windows version of
lpd.
Parameter

Value

Server

name

Medium

print

Device

"NETWORK ip_address 515"

Channel_Queue

Usually PRINT. Check the printers documentation for


the correct value.

Channel_Type

WLPD

Delivery_Mode

Overlapping

Hard_Queue

Yes

Configuring Emtex VIP-connected printers


To use Emtex VIP-connected printers such as IPDS printers, set these parameters:
Parameter

Value

Server

name

Device

"NETWORK hostname 6001"

Channel_Type

VIP

Delivery_Mode

Overlapping

Hard_Queue

Yes

Map_Prio_0 to
Map_Prio_9

(Optional.) The VIP priority levels that Columbus OM


priority levels are to mapped to

Profile_Exit

(Optional.) The VIP job ticket

VIP_Data_Root

The path of the shared VIP data folder, as seen by


Columbus OM

VIP_Data_Root_Name

The name of the shared VIP data folder, as seen by


Columbus OM

VIP_Directory

The path of the shared VIP home folder, as seen by


Columbus OM

COLUMBUS OM INSTALLATION AND CONFIGURATION

199

200

CHAPTER 8

Using the xprinter driver

Example configurations for xprinter

Parameter

Value

VIP_Directory_Name

The name of the shared VIP home folder, as seen by


VIP

VIP_Force_Disk_Mode

(Optional.)
Yes writes the document to the shared disk.
No writes the document to the device socket.

Configuring Zebra label printers


To use a Zebra label printer with xprinter, set the Channel_Type parameter to ZPL,
and the BackChannel parameter to zplinfo.
Columbus OM shows the number of labels that are in a print job in the Pages
field.

Configuring IPP printers


Printers that supports IPP (Internet Printing Protocol) can be used with xprinter by
setting the parameters that are described below. However, IPP provides little or no
extra functionality over other channel types; sometimes, it provides less
functionality. Use it only if none of the other channel types can be used.
Parameter

Value

Channel_Type

IPP

Device

NETWORK address 631

Replace address with the printers host name or IP


address.
BackChannel

ippinfo
ippinfo is not recommended for use with Xerox printers.
Xerox printers always return the worst case status: for
example, if a paper tray is empty, ippinfo reports that the
printer is unavailable, even if other paper trays contain
paper. (See also Quick_Ipp below.)

Quick_Ipp

Yes or No

xprinter usually sends documents to a printer only if the


printer reports that it is available. However, some
printers report that they are unavailable even when they
are still usable: for example, they consider paper out in
one tray makes them unavailable, even though there is
plenty of paper in other trays.
If your printer does this, you can set this parameter to Yes:
xprinter then assumes that the printer is available if it
makes any reply to a status enquiry; xprinter does not try to
parse the reply.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Example configurations for xprinter

Parameter

Value

URI_Extension

If the printer has multiple IPP addresses or queues, and


you want to use a specific one, specify its name.
To use the default queue, leave this value blank.
If the printer has only one queue, leave this value blank.

Delivery_Mode

If the printer has multiple IPP addresses or queues, you


might be able to increase the processing speed by setting
this parameter to Overlapping.

Columbus OM does not support communication by SSL/TLS that some


implementations of IPP offer.

Connecting to printers using commands


To connect to a printer by using a piped command (for example a Lexmark
PrintCryption printer that uses the Lexmark dcp command), set these parameters:
Parameter

Value

Channel_Type

COMMAND

Device

NETWORK address port

Replace address with the printers host name or IP address,


and port with the port number on which it listens for
commands.
Command

"myscript myargs"

Replace myscript with the name of the command, and


myargs with any arguments that the command uses.

COLUMBUS OM INSTALLATION AND CONFIGURATION

201

202

CHAPTER 8

Using the xprinter driver

Reference

Reference
xprinter configuration
Configuration file
%UNIQDIR%\servers\printer_name\config.tab

Configuration parameters
The following parameters are specific to xprinter. If you cannot find a parameter
in this section, see Other xprinter configuration parameters on page 208.
Accounting_DB_Method
Accounting_DB_Type

These values override the values that are set in the system defaults files.
Accounting_XML_Port number
Accounting_XML_Server text

(Used when Accounting_DB_Method parameter in the system defaults file,


default.tab is set to XMLSERVER.) The port number and server on which the
xmlserver listens. The default port number is 8082.
These values override the values that are set in the system defaults files.
Action_On_Cancelled command
Action_On_Delivered command
Action_On_Disabled command
Action_On_Incomplete command
Action_On_Paused command
Action_On_Resumed command

Commands to be run in response to events. For more information, see


Common parameters on page 602.
AFP_Analysis YES|NO
YES analyzes AFP documents to find out their requirements. See also
Analysis_Mode.
Analysis_Mode ALL|SELECTED|NONE

Specifies which document formats are analyzed to find out:

their requirements (for use with the xselect command)

their page count.

To analyze

Do this

all document formats

Specify ALL.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Reference

To analyze

Do this

no document formats

Specify NONE.

selected document
formats

Specify SELECTED, and then set the appropriate


parameters for the selected formats to YES.
The parameters that can be set are:
AFP_ANALYSIS, IDOL_ANALYSIS, PCL_ANALYSIS,
PCL6_ANALYSIS, PDF_ANALYSIS, PS_ANALYSIS,
PSD3_ANALYSIS, TEXT_ANALYSIS,
TIFF_ANALYSIS

Block_Size number

The maximum size (measured in bytes) of the blocks of data that are to be sent
to the printer.
This parameter is used only if PAGE_MODE is set to BLOCKED.
The default size is 500000.
BlockAct_Messages YES|NO
YES sends a pop-up message to the entry owner if the entry becomes blocked.
See also Message_Type.
Channel_Queue queue

The name of the onboard queue. For example, on DocuCenter devices, the
queue is print.
The default value is print.
Channel_Type SNMP|PJL|XPP|RAW|VIP|XLPD|NLPD|IPP

The channel type. For more information, see Devices supported by xprinter
on page 186.
Check_Page_Meter Yes|No

(Used with the RAW and RAWLPD channel types.) Enables assured delivery
by checking when a document has finished that the printers page counter
increases by the same number of pages that are in the document.
This feature can be used with printers that have a lifetime page counter that can
be accessed by their MIB.
Columbus OM records the page count both before and after printing the
document in the printers day logfile.
See also the Page_Meter_Wait parameter.
Check_Status Yes|No

(Used with the RAW channel type.)


Yes checks that the printer is available, and that it is not offline, before sending

data to it. When the printer becomes available again, Columbus OM starts
sending data to it.
No assumes that the printer is always available, and sends the data to it without

checking.

COLUMBUS OM INSTALLATION AND CONFIGURATION

203

204

CHAPTER 8

Using the xprinter driver

Reference

The default value is No.


Completion_Messages YES|NO
YES sends a pop-up message to the owner when an entry is completed. See also
Message_Type.
Connect_Interval number[m]

The interval at which xprinter tries to connect to a printer, if it can not connect
at the first attempt.
To specify the interval in seconds, put only the number, for example:
Connect_Interval 10.
To specify the interval in milliseconds, put the number followed by m, for
example: Connect_Interval 1000m.
The minimum value is 0. The maximum value is 32767.
The default value is 1.
Connect_Retries number

The maximum number of attempts that xprinter makes to connect to a printer.


The minimum value is 0. The maximum value is 32767.
The default value is 120.
Delivery_Mode SECURE|OVERLAPPING|""

The delivery mode. For more information, see xprinter delivery modes on
page 189.
For standard delivery mode, specify "".
Device "NETWORK host port"

The network connection via TCP/IP to the device.


Disconnect_Delay n[m]

The delay after breaking a connection and before continuing; some networks
require a short recovery period after disconnecting.
To specify the value in seconds, use only the number (for example,
Disconnect_Delay 1).
To specify the value in milliseconds, use the number followed by m (for
example, Disconnect_Delay 1000m)
The default value is 4 (seconds).
Error_Messages YES|NO
YES sends a pop-up message to the owner if an error occurs. See also
Message_Type.
Forms_Flash YES|NO
YES sends a forms overlay to the printer to be printed with the document.

You can specify a different forms overlay for each paper type. Put the file that
contains the forms overlay in this folder:
%UNIQDIR%\media\print\printertype\FORMS\INITF\papertype

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Reference

Hard_Queue YES|NO
YES indicates that the printers onboard queue is disk-based (non-volatile).
IDOL_Analysis YES|NO
YES analyzes IDOL documents to find out their requirements. See also
Analysis_Mode.
Incomplete_Timeout number

The maximum time (measured in seconds) that Columbus OM waits for the
printer to return a message confirming that an entry has been completed. After
this time, it moves the entry to the completed queue, and sets its status to
Incomplete.
Job_Control PJL|JOB_TICKET

The job control protocol that is used to control the printer and to separate the
datastream.
Value

Description

PJL

Protocol used for HP LaserJet printers and compatible


printers

Job_Ticket

Protocol used for Xerox DocuSP printers

The default value is PJL.


Job_Control_Filter application

An application for changing the job control. Columbus OM submits the job
control to the application, the application changes it, and then Columbus OM
uses the result.
Job_Control_Rules filename

Rules to modify a job control action.


Local_Host localhost

The network card to which a server binds. This parameter is required only if
the computer has multiple network cards (which means that it also has multiple
host names).
The value can be:

the computer name, for example: MyServer01

the IP address, for example, 10.0.20.123

0.0.0.0, to bind to any network card that is on the host.

If the Local_Host parameter is omitted, Columbus OM uses the IP address of


the host.
Map_Prio_n_TO x

(Map_Prio_0_To to Map_Prio_9_To. Used with Emtex VIP-connected


printers.) Maps Columbus OM priority level n to VIP priority x.

COLUMBUS OM INSTALLATION AND CONFIGURATION

205

206

CHAPTER 8

Using the xprinter driver

Reference

Max_Overlap number

Maximum number of jobs to overlap. Used when Delivery_Mode is set to


OVERLAPPING.
Message_Type NS|UW

How pop-up messages are to be delivered (see also BlockAct_Messages,


Completion_Messages, Error_Messages, and Start_Messages). The
method to use depends on the operating system.
Platform

Value

Windows (using the net_send command)

NS

UNIX (using the write command)

UW

Page_Meter_Wait number

(Used with the Check_Page_Meter parameter.) Specifies how long (measured


in seconds) Columbus OM waits for the printers page counter to change.
Page_Mode INTELLIGENT|BLOCKED

If the job protocol allows page level operation, specify INTELLIGENT.


To deliver data in block size amounts, specify BLOCKED. To specify the size of
the blocks, use the Block_Size parameter.
The default values are:

If the Channel_Type is PJL, the default value is INTELLIGENT.


If the Channel_Type is anything else, the default value is BLOCKED (see also
Block_Size).

PCL6_Analysis YES|NO
YES analyzes PCL 6 documents to find out their requirements. See also
Analysis_Mode and PCL_Analysis.
PCL_Analysis YES|NO
YES analyzes PCL documents to find out their requirements. See also
Analysis_Mode and PCL6_Analysis.
PDF_Analysis YES|NO
YES analyzes PDF documents to find out their requirements. See also
Analysis_Mode.
PostScript YES|NO
YES indicates that the printer supports PostScript.
Profile_Exit text

(Used with Emtex VIP-connected printers.) The VIP job ticket.


PS_Analysis YES|NO
YES analyzes PostScript documents to find out their requirements. See also
Analysis_Mode.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Using the xprinter driver

Reference

PSD3_Analysis YES|NO
YES analyzes PostScript level 3 documents to find out their requirements. See
also Analysis_Mode.
Removed_Action CANCEL|COMPLETE|FAIL|INCOMPLETE

Specifies the status to be applied to entries that disappear from the LPD queue
between scans without having apparently been printed. This might happen if a
user deletes the entry; if the job is so small that it completes in the interval
between scans; or if the printer is slow to update its queue.
The default value is CANCEL.
Response_Timeout number

Specifies the maximum time (measured in seconds) that xprinter waits for a
status message from a printer after sending a job to it. If the printer does not
send a status message within this time, xprinter assumes that a problem has
occurred, and then tries to send the job again.
The default value is 90 (seconds).
Start_Messages YES|NO
YES sends a pop-up message to the entry owner when the entry is started. See
also Message_Type.
Sync_Check_Limit number

The maximum number of attempts that Columbus OM makes to synchronize


with the printer.
Text_Analysis YES|NO
YES analyzes text-format documents to find out their requirements. See also
Analysis_Mode.
TIFF_Analysis YES|NO
YES analyzes TIFF documents to find out their requirements. See also
Analysis_Mode.
Trailing_FF Yes|No
Yes handles badly-formed last pages, for example, text documents with no

specific end-of-page marker, by adding a formfeed to force the last page out of
the document. Without this feature, there might be delay of about one minute
for the last page is output.
Unconfirmed_Action RESTART|RESUME|COMPLETE

Specifies what you want Columbus OM to do if a document cannot be sent to


the printer:
To

Do this

reprint from the last confirmed job

Set this parameter to RESTART.

reprint from the last confirmed page

Set this parameter to RESUME.

COLUMBUS OM INSTALLATION AND CONFIGURATION

207

208

CHAPTER 8

Using the xprinter driver

Reference

To

Do this

assume that the job has been


completed, and move it to the
completed queue

Set this parameter to COMPLETE.

take no action

Leave the value blank.

Use_Doc_Suffix Yes|No
Yes identifies the format of a document by using its file name extension. For
example, .txt identifies the format as TEXT.
No identifies the format by examining the content of the file.
Wait_For_Close Yes|No
Yes waits for printer messages before closing a connection. This might take a
few seconds before connection can be closed: in an environment with high
throughput, you can close the connection without waiting for the messages by
setting the parameter to No.

See also the Keepalive_Time parameter.


This parameter applies only to the PJL, ZPL and Raw channels.
The default value is Yes.
VIP_Text_As PCL|XRX

(Used with Emtex VIP-connected printers.) Controls how plain text is handled:
XRX sends plain text as DJDE. The default value is PCL.
XPP_TIMEOUT n

The maximum time (measured in seconds) that xprinter waits for a printer to
respond (for example, to report that it is XPP-capable; that it has printed a
block of data; or how much memory it has available).
The default time is 120 seconds.
Other xprinter configuration parameters
xprinter also has the following configuration parameters:

These configuration parameters specify how banner pages are produced. for
more information, see Banner pages for xprinter on page 192.
Error_Banner
XBanner_File
XBanner_Type
XError_File
XNormal_Message
XReprint_Message
XResume_Message
XTemplate_File

Parameters starting with VIP (for example, VIP_Data_Root) are used with
Emtex VIP-connected printers. For more information, see Configuring Emtex
VIP-connected printers on page 199.
These configuration parameters are the same as for a printer server. For more
information, see page 129.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 8

Action_On_Completion
Action_On_Failure
Action_On_Postponement
Action_On_Start
Action_Pre_Completion
Any_Paper
Attempts_Limit
BackChannel
Banner
Ceiling
Floor
Hold_Connect
Input_Filter
Keepalive_Time
Medium
Paper
Paper_Mandatory
Pause_Time
Postpone_Time
PostScript
Printer_ID
Query_Printer
Scan_Interval
Server
Status_Type

COLUMBUS OM INSTALLATION AND CONFIGURATION

Using the xprinter driver

Reference

209

210

CHAPTER 8

Using the xprinter driver

Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

211

CHAPTER 9

Chapter 9

Adding entries

There are several ways of adding entries for processing by Columbus OM.

To test a Columbus OM system, the easiest way of adding an entry might be by


using the Windows interface, Columbus OM Explorer.

In a production system, entries are usually added by using the command line.

On UNIX, you can intercept lp requests and lpr/lpd requests, and then add
them to Columbus OM.

To integrate Columbus OM with another application, you scan folders for files
that the other application has created, and then add them to Columbus OM.

To integrate Columbus OM with SAP R/3, see Integrating Columbus OM


with SAP R/3 on page 539.

Users without direct access to a Columbus OM instance can still use it to print
documents, if they can transfer files to the host on which a Columbus OM
instance is installed.

To

See

add entries by using Columbus OM Explorer

page 212

add entries by using the command line

page 216

intercept UNIX lp and lpd/lpr requests

page 224

scan folders for files that another application has created

page 234

transfer documents from other hosts

page 232

COLUMBUS OM INSTALLATION AND CONFIGURATION

212

CHAPTER 9

Adding entries

Adding entries by using Columbus OM Explorer

Adding entries by using Columbus OM Explorer


Finding devices
To display the devices that are available
To

Do this

check which devices are available for


use

Double-click the Printers folder in the


navigation pane.

display device groups and classes

On the View menu click Options. In


the Columbus OM Preferences dialog
box, click the Printers tab and then click
Grouping. Select the groups and
classes, and then click OK.
Double-click the Printer Groups and
Printer Classes folders in the
navigation pane.

To make sure that a device can be used

To use a device, the device must be enabled. To print a


document to a printer class, at least one printer in the class
must be enabled.
Enabled
printer
An icon with a red cross indicates that the device is not
enabled and cannot be used at the moment.

Disabled
printer

To enable a device, right-click its icon, and then click Enable.


To check for device problems
To

Do this

display the status of a device

Right-click its icon, and then click


Status.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Adding entries by using Columbus OM Explorer

To

Do this

display all enabled printers with a


problem

Click the Printer Warnings folder.

display the status by using MarkVision

To enable this feature, see Scanning


printers for status changes on page 416.
Click the Printers folder, and then click
the MarkVision toolbar button. This
toolbar button is available only if
MarkVision is installed on your PC.

Printing documents
Document formats for printing

If the document is in ASCII (unformatted text), PCL, or PostScript format and


the printer supports the format, you can add it directly to the print queue: see
Printing documents below.

If the document is in a different format, print it to a file in one of the supported


formats, and then add that file to the Columbus OM print queue.

Printing documents
1

In Columbus OM Explorer, select the Columbus OM instance that controls


the printer that you want to use.

Under the instance icon, select the type of printer that you want to use:
Folder

Description

Printers

Printers that are controlled by the instance you have


selected.

Remote Printers

Printers that are controlled by other instances.

Printer Classes

Groups of similar printers, for example, all the printers


in one office. Columbus OM Explorer chooses a printer
in the class that is not already being used.

In the navigation pane, click the printer or printer class that you want to use.

On the Entry menu, click Add Entry.


The Add New Entry dialog box appears.

COLUMBUS OM INSTALLATION AND CONFIGURATION

213

214

CHAPTER 9

Adding entries

Adding entries by using Columbus OM Explorer

Specify where the document that you want to print is:


If the document is on

Select

your PC or network, and it is in ASCII format

On Local (ASCII)

your PC or network, and it is in binary format

On Local (Binary)

the host computer where the Columbus OM print


instance is installed

On Server

(Documents created by printing to a file are usually in binary format.)


6

In the Document box, type the path and name of the file, or click the
(Browse) button.

Select the Medium that indicates the server that you want to process the
document, usually print.

Do one of the following:


To

Do this

print the document as soon as possible Click OK.


See Changing the document details
change any of the other settings (for
example, to print more than one copy below.
or to control when the document is
printed)
Changing the document details
To

Do this

print more than one copy

On the Details tab, change the Copies


option. Each copy appears as a separate
entry in the document queue.

print a banner page

On the Details tab, select Banner.


What the banner page contains is set by
the Columbus OM administrator.

print only selected pages from the


document

On the Details tab, set the From and To


page numbers under Partial Print.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Adding entries by using Columbus OM Explorer

To

Do this

control how long the document is to be On the Details tab, set the Retain for
kept on the Completed queue when it
option.
has been processed
delete the document when it has been
processed (instead of moving it to the
Completed queue)

On the Details tab, set Retain for to 0.

delete the document when it has been


completed successfully (instead of
moving it to the Completed queue).

On the Details tab, set Retain for to -1.

add a remark to be displayed in the


On the Details tab, type the text in the
queue (this remark does not get printed) Remark box.
control the printer attributes (for
example, the font, paper and
orientation)

Click the Printer tab. To override the


default values for the printer, select the
required attributes.

specify the file format

On the Details tab, select a value from


the File Coding list. Make sure that the
format is supported by the printer that
you are using.

record the page count

Type PAGES in the Remark field.

Controlling when the document is printed


Columbus OM prints the document as soon as possible, unless you set these
properties:
To print the document

Do this

on a specific date and time

Click the Date/Time tab. Select Defer


to, and then set the date and time.

only when another document has been


printed

Click the Date/Time tab. In the


Chained after box, type the entry
number of the document that you want
to be completed first.

depending on its urgency

Click the Date/Time tab. Set the


Priority: Columbus OM prints
documents with a high priority (for
example, 9) before those with a low
priority (for example, 0).

put a document on hold (add to the


queue, but do not print it)

On the Details tab, select Put on hold,


and Take Copy.

COLUMBUS OM INSTALLATION AND CONFIGURATION

215

216

CHAPTER 9

Adding entries

Adding entries from the command line

Adding entries from the command line


aeq command
To add entries or change the properties of existing entries from the command line,
use the aeq command.
Syntax for adding entries
aeq [documents] [destination] [option...] [qualifier...]

Syntax for changing an entry


aeq entry_id option... [qualifier...]

Specifying the documents


To specify the documents that you want to process, use one of the following
keywords. Columbus OM adds each document as a separate queue entry. If you do
not use any of these keywords, Columbus OM does what is specified by the
AEQ_Default system parameter (in the default.tab file).
-DOCUMENT_FILE|-df file...
file... is a space-separated list of pathnames to the documents. The
-DOCUMENT_FILE|-df keyword can be omitted. Under UNIX, a file
argument can include ? and * wildcard characters.
-DOCUMENT_INPUT|-di

The document is read from standard input (stdin).


-DOCUMENT_LIST|-dl file

The documents are listed in file, one per line.


-DOCUMENT_TEXT|-dt string

The document is the literal text string, which should be enclosed in quotation
marks "..." if it contains spaces.
Specifying the destination
Use one of these keywords to specify the destinations to be used. Columbus OM
adds a separate queue entry for each destination. For multiple documents and
multiple destinations, Columbus OM sends the first document to all destinations,
then the second document, and so on. If the destination is omitted, the default is
taken from the Address system parameter (in the default.tab file). The
destination must be 80 characters or less.
-ADDRESS_FILE|-af file

The destinations are listed in the file that you specify. Each destination has one
of these forms:
destination
destination

# string

The optional string is included in the queue entry for identification purposes,
but can be overridden by -REMARK_FILE and -REMARK_TEXT.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Adding entries from the command line

-ADDRESS_TEXT|-at destination

A destination appropriate to the function that you are using, for example, a
printer, a fax number, or an email address. For the Columbus OM dispatch
instance, it does not represent a conventional destination and so can be any
character string, which can be tested in the rules.
Specifying the qualifiers
The command normally adds and changes entries in the pending section of the
queue instance which is defined by the value of %UNIQDIR%. You can affect this,
and the commands output, using these qualifiers.
-ARCHIVE|-ar [number]

Add or change an entry in the archive queue number; if number is zero or


omitted, the default is the current archive queue.
-COMPLETE_QUEUE|-cq

Change an entry in the completed section of the queue. The only attribute
which you can change is -RETENTION_DAYS.
-NO_BANNER|-nb
-NO_WARNING|-nw
-QUEUE_NAME|-qn instance
-SILENT|-si

See Common parameters on page 602.


Specifying the options
-ALIAS|-as string

A user-defined document identification of up to 80 characters, enclosed in


quotation marks "..." if it contains spaces.
-CHAIN|-c [entry_id]

This entry is dependent on an existing entry_id, and will not be processed


until that entry has completed. If multiple source documents are being added to
the queue, each is made dependent on the document which precedes it; the first
document is either dependent on an existing entry (if entry_id is specified) or
not.
-CHILD

This entry is a child of the master entry specified as -ORIGINAL_UID.


-COPIES|-cp number

Only when adding entries: Create number queue entries for each source
document.
-ENCRYPT|-enc|-en [NO|YES|AES128|AES192|AES256]

Only when adding entries: Controls whether the document file is encrypted when
it is on the queue. The encryption system that is used is AES (Rijndael).

NO adds the document to the queue without encrypting it.

COLUMBUS OM INSTALLATION AND CONFIGURATION

217

218

CHAPTER 9

Adding entries

Adding entries from the command line

YES encrypts the document. Columbus OM uses the method that is


specified by the Disk_Encrypt parameter in the system defaults table
(default.tab). If that parameter is omitted or set to NO, Columbus OM

encrypts the document by using 128-bit keys.

AES128 uses 128-bit keys.

AES192 uses 192-bit keys.

AES256 uses 256-bit keys.

The default value is NO.


If you encrypt the document (that is, you use the YES, AES128, AES192 or
AES256 option), you cannot also use the -Document_Text, -No_Copy or
-No_read parameters.
For more information about encrypting documents, see Encrypting
documents on page 374.
-FROM_PAGE|-fp number

Only when adding entries: The first page of the source document to be processed;
earlier pages are discarded from the queued file. The default is the start of the
file.
-HELP|-h

Only if no other options are supplied: Display command help.


-HOLD|-h

Set the entrys status to Held; it will not be processed until released (using
-RELEASE).
-MEDIUM|-m medium

The transmission medium. The available media are defined in the media.tab
file.
-NO_COPY|-nc

Only when adding: Use the source document directly, rather than take a
temporary copy. Cannot be used with -FROM_PAGE and -TO_PAGE.
-NO_READ|-nr

Only when adding: Do not read the source document (to determine its size), also
do not take a temporary copy. Used to save time when queuing very large
documents. Cannot be used with -FROM_PAGE and -TO_PAGE.
-ORIGINAL_UID|-ou entry_id

This entry was originally identified as, or is a child of, entry_id.


-OWNER|-o user_id

The entry belongs to user_id. If you do not use this parameter, the entry
belongs to the user whom you are logged in as.
-PAGE_LENGTH|-pl number

Page breaks are to be calculated by counting number lines per page.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Adding entries from the command line

-PC number

Specifies the page count (instead of using Columbus OMs features to count the
pages).
-PRIORITY|-p number

A digit in the range 0 (lowest) to 9 (highest), to be used when prioritizing


entries.
-PROGRAM|-pg string

The identification of the program which created the queue entry (useful when
entries are being added directly from an application). Must be 32 characters or
less.
-RELEASE|-r

Only when changing entries: Change the entrys status from Held (set using -HOLD)
to New, so that it can now be processed.
-REMARK_FILE|-rf file
file contains a queue entry annotation.
-REMARK_TEXT|-rt string
string is a queue entry annotation of up to 80 characters, enclosed in
quotation marks "..." if it contains spaces.
-REPORT_UID|-ru file

Only when adding: If the attempt to add the source document to the queue is
successful, its entry_id is written to the file; otherwise, 0 is written.
-RETENTION_DAYS|-rd number

The minimum number of days that the entry should be retained on the
completed queue after having been processed.
To delete the entry as soon as it has been completed successfully, specify -1.
-SECURITY_LEVEL|-sl {number|text}

Specifies the security level to be applied. The security levels are listed in the
seclev.tab file. You can specify either the number or the description.
-SECURITY_GROUP|-sg text

Specifies the security group to be applied, that is, a user group file in the
security folder, without the u_ prefix.
-SERVER_TEXT|-st string

Additional information specific to the product server.


The maximum length of the string is 80 characters. If the string contains spaces,
enclose it in quotation marks "...".
-SPECIAL_COPY|-sc

Indexes the file, if possible.

COLUMBUS OM INSTALLATION AND CONFIGURATION

219

220

CHAPTER 9

Adding entries

Adding entries from the command line

-TIME|-t time

The earliest point at which the source document should be processed, one of:
hh:mm

At absolute time hh:mm, either today (if hh:mm is later


than now) or tomorrow (if hh:mm is earlier than now).

hh:mm DD MON YEAR At absolute time hh:mm on day DD MON YEAR.


+[DD.]hh:mm

At relative time DD days, hh hours and mm minutes in


the future.

Immediately. (There is actually a delay of 10 seconds,


to ensure that the queue is not locked.)

-TO_PAGE|-tp number

Only when adding: The last page of the source document to be processed; later
pages are discarded from the queued file. The default is the end of the file.

apq command
To add print entries or change the properties of existing entries from the command
line, use the apq command.
Syntax for adding an entry
apq [documents] [destination] [option...] [qualifier...]

Syntax for changing an entry


apq entry_id option... [qualifier...]

Parameters and options


documents

See Specifying the documents on page 216.


destination

See Specifying the destination on page 216.


-BANNER|-b YES|NO
YES if a burst page banner is required; NO if not. If you omit this parameter, the
default behaviour is determined by parameters Print_Banner in
default.tab and Banner in the printers config.tab.
-COMMAND|-co file
%UNIQDIR%\media\print\printer_type\COMMANDS\file contains a

sequence of control codes (which cannot be supplied by other more specific


attributes) to be sent to the destination before the document.
-DOCUMENT_CODE|-dc encoding

The encoding of the source document, one of:


0 or NONE

Plain text, unknown (equivalent to


-NON_POSTSCRIPT)

1 or POSTSCRIPT or PS

PostScript (equivalent to -POSTSCRIPT)

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Adding entries from the command line

2 or PCL

HPs Printer Control Language

4 or PDF

Adobes Portable Document Format

5 or BENSON

Benson plotter language

8 or HTML

Hypertext Markup Language

10 or EPSON

Epson FX-1050 protocol

12 or AFPDS

AFP Data Stream documents

other numbers

user-specified encodings

If no coding is specified, the documents format determines its type.


-FINISHING|-fi file
%UNIQDIR%\media\print\printer_type\FINISHING\file contains a

sequence of control codes (which cannot be supplied by other more specific


attributes) to be sent to the destination after the document.
-FONT|-f file
%UNIQDIR%\media\print\printer_type\FONT\file contains a sequence of

control codes defining the font to be used.


-HOPPER|-hp file
%UNIQDIR%\media\print\printer_type\HOPPER\file contains a sequence

of control codes defining the input hopper to be used.


-HOST_NAME|-hn host

The destination is on a remote system host.


-MEDIUM|-m medium

The medium of the server that is to process the entry, usually PRINT.
-NON_POSTSCRIPT|-nps

The source documents encoding is not PostScript; equivalent to


-DOCUMENT_CODE NONE.
-ORIENTATION|-or string
%UNIQDIR%\media\print\printer_type\ORIENTATION\file contains a

sequence of control codes defining the page orientation to be used.


-OUT_HOPPER|-oh file
%UNIQDIR%\media\print\printer_type\OUT_HOPPER\file contains a

sequence of control codes defining the output hopper to be used.


-PAPER|-pp paper_type
%UNIQDIR%\media\paper\paper_type contains settings defining the paper

type to be used.
-PITCH|-pt file

Sets the character spacing to be used: put the control codes for the character
spacing in a file in the %UNIQDIR%\media\print\printer_type\PITCH
folder, and then specify the name of the file here.

COLUMBUS OM INSTALLATION AND CONFIGURATION

221

222

CHAPTER 9

Adding entries

Adding entries from the command line

-POSTSCRIPT|-ps

The source documents encoding is PostScript; equivalent to


-DOCUMENT_CODE POSTSCRIPT.
-PRESENTATION|-pr file

Sets the presentation to be used, by applying the control codes that are in the
file specified. The file must be in this folder:
%UNIQDIR%\media\print\printer_type\PRESENTATION.
-SPECIAL_COPY|-sc

Indexes the file, if possible.


This parameter has an effect only if the AEQ_Index parameter in the system
defaults file (default.tab) is set to Yes.
-SOURCE_HOST|-sh host
host identifies the machine on which the entry originated.

The following options for the apq command have the same effect as for the aeq
command: for more information, see Specifying the options on page 217.
-ALIAS|-as string
-CHAIN|-c [entry_id]
-CHILD
-COPIES|-cp number
-FROM_PAGE|-fp number
-HELP|-h
-HOLD|-h
-NO_COPY|-nc
-NO_READ|-nr
-ORIGINAL_UID|-ou entry_id
-OWNER|-o user_id
-PAGE_LENGTH|-pl number
-PRIORITY|-p number
-PROGRAM|-pg string
-RELEASE|-r
-REMARK_FILE|-rf file
-REMARK_TEXT|-rt string
-REPORT_UID|-ru file
-RETENTION_DAYS|-rd number
-SECURITY_LEVEL|-sl {number|string}
-SECURITY_GROUP|-sg string
-SERVER_TEXT|-st string
-SPECIAL_COPY|-sc
-TIME|-t time
-TO_PAGE|-tp number

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Adding entries from the command line

Specifying the qualifiers


For more information, see Specifying the qualifiers on page 217.
-ARCHIVE|-ar [number]
-COMPLETE_QUEUE|-cq
-NO_BANNER|-nb
-NO_WARNING|-nw
-QUEUE_NAME|-qn instance
-SILENT|-si

COLUMBUS OM INSTALLATION AND CONFIGURATION

223

224

CHAPTER 9

Adding entries

Intercepting the lp and lpstat commands

Intercepting the lp and lpstat commands


(UNIX only.)
To print all documents using Columbus OM instead of the UNIX lp queue, you
can replace the standard UNIX lp and lpstat commands with the Columbus OM
versions.
To do this, change the assignments to the $PATH environment variable so that the
Columbus OM bin directory is in front of the existing $PATH value, instead of at
the end.

Using the Columbus OM lp command


You can add print entries by using Columbus OMs version of the UNIX lp
command.
Syntax
lp [option...] file...

or
uniqlp [option...] file...

Parameters and options


The parameters and options for the Columbus OM version of lp are case-sensitive.
(This is consistent with other standard UNIX commands.)
Columbus OM below indicates additional options that are specific to
Columbus OM.
file

A list of files to be submitted. Include the paths to the files. To specify two or
more files, separate their paths by using a space. The paths can include
wildcard characters.
-atime

(Columbus OM.) When the entry is to be processed, one of:


hh:mm

At absolute time hh:mm, either today (if hh:mm is


later than now) or tomorrow (if hh:mm is earlier than
now).

'hh:mm DD MON YEAR'

At absolute time hh:mm on day DD MON YEAR.

+[DD.]hh:mm

At relative time DD days, hh hours and mm minutes


in the future.

-bN|-bY

(Columbus OM.) To print a banner page, use -bY. To omit the banner page,
use -bN.
-c

Take a temporary copy, rather than use the source document directly.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Intercepting the lp and lpstat commands

-dprinter

The destination: a printer server or class.


-enumber

(Columbus OM.) number is the last page of the source document to be sent to
the destination; the default is the end of the file.
-fnumber

(Columbus OM.) number is the first page of the source document to be sent to
the destination; the default is the start of the file.
-gusername

(Columbus OM.) Adds the entries as belong to the user specified (instead of the
user whom you are logged in as).
-h

(Columbus OM.) If no other options are supplied: Display command help.


-i

(Columbus OM.) Sets the status of the entries to Held. They will be printed
only when they are released.
-jentry_id

(Columbus OM.) Specifies that this entry is dependent on an existing


entry_id, which must be processed first. If several source documents are
being queued, they are chained in the order in which they were added to the
queue.
-lnumber

(Columbus OM.) A range of pages is being specified (using -f and -e) but the
document is not paginated using formfeed characters: therefore, page breaks
are to be calculated by counting number lines per page. The default is obtained
from the paper_type definition, or from the destination.
-m

Sends you an email message on completion.


-nnumber
number queue entries are to be created for each source document.
-ostring
string is additional information specific to the printer server, of up to 80
characters and enclosed in quotation marks "..." if it contains spaces. It can
be used either to provide parameters for an lp-style interface filter (if one if

configured for the destination printer), or to pass Columbus OM options not


directly supported by lp. For example, lp -o"-ORIENTATION LANDSCAPE"
file is equivalent to apq file -ORIENTATION LANDSCAPE.
-ppaper_type

(Columbus OM.) paper_type is destination-specific and identifies the paper


type to be used.

COLUMBUS OM INSTALLATION AND CONFIGURATION

225

226

CHAPTER 9

Adding entries

Intercepting the lp and lpstat commands

-rstring

(Columbus OM.) string is a queue entry annotation of up to 80 characters,


enclosed in quotation marks "..." if it contains spaces.
-s

Hides error messages and warning messages.


-tstring
string is a printout title of up to 80 characters, enclosed in quotation marks
"..." if it contains spaces.
-unumber

(Columbus OM.) number is a digit in the range 0 (lowest) to 9 (highest), to be


used when resolving contention for a destination.
-w

Write a message to your terminal on completion.

Configuring the lp command


To configure how the Columbus OM lp command operates, set these parameters
in the system defaults file (default.tab):
LP_Concatenate YES|NO
YES makes the Columbus OM lp command behave like the UNIX lp
command when printing multiple files, by concatenating the files into a single
entry.
NO makes separate queue entries for each file.

The default value is NO.


LP_Message YES|NO
YES makes the Columbus OM lp command behave like the UNIX lp

command when reporting status information on a print request.


NO uses standard Columbus OM reporting.

The default value is NO.


LP_QLocal YES|NO

When using the Columbus OM lp command in client/server mode:


YES adds the print request to the local (client) queue
NO adds it to the remote (server) queue.

The default value is YES.


LP_Val_Dest YES|NO

When using the Columbus OM lp -d command:


YES validates the destination.
NO adds the entry to the queue without validation.

The default value is YES.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Converting lpr/lpd requests to Columbus OM print entries

Converting lpr/lpd requests to Columbus OM print


entries
UNIX only.
Print requests made by using lp can be intercepted by Columbus OM print
instance and added as entries to its queue. To do this, you replace the lpr/lpd
process with the Columbus OM lpdserver.
To use lpdserver
1

Refer to Configuring lpdserver on page 228 to see if any of the configuration


parameters for lpdserver need to be changed.

Shutdown the lpd process.

Start lpdserver.
The lpdserver server listens on the same TCP/IP socket as the lpr/lpd
process (number 515), and then translates incoming lpr/lpd requests to
Columbus OM print queue entries.

Using lpdserver with multiple instances


To use lpdserver with multiple instances of Columbus OM on the same
computer, you must choose one instance to run lpdserver (because lpdserver
has to use socket 515, and a socket can be used by only one instance). You then
configure that instance to send entries to the appropriate instance.
To configure the instances
1

Choose one Columbus OM instance to control and run lpdserver.

In this instances config.tab file, set the Scan_Instances parameter to Yes.

In the instances systems.tab file, add the other instances, in the order that
you want lpdserver to check them.
lpdserver looks at the name of the printer that the user has selected for an
entry (for example, Accounts).

If there is a printer called Accounts in the instance that runs lpdserver,


then lpdserver adds the entry to that instance.

If there is no printer called Accounts in the main instance, then


lpdserver looks down the list of instances in the systems.tab file, and
then adds the entry to the first instance in which there is a printer called
Accounts.

If there is no printer called Accounts in any instance, then lpdserver


adds the entry to the main instance.

Configuring lpdserver for sequential printing


To use sequential printing with lpdserver, you must use a regular form of the
lpr/lpd protocol:

the control and data file set must be sent as a pair, one immediately after the
other

COLUMBUS OM INSTALLATION AND CONFIGURATION

227

228

CHAPTER 9

Adding entries

Converting lpr/lpd requests to Columbus OM print entries

only single copies can be specified on the command line.

To configure lpdserver to print sequentially, set its RestrictedMode parameter.


For more information, see the examples below.
Example 1

You have a system in which spool requests are added to a client instance of
Columbus OM. This instance sends the entries to a server instance of
Columbus OM. You want the server instance to print the entries in sequence.
1

On the client, set this parameter in the system defaults file (default.tab):
UID_order

YES

On the server, set the same parameter in the system defaults file:
UID_order

YES

Example 2

You have a system in which lp/lpr spool requests are added to a client instance of
Columbus OM. This instance sends the entries to a server instance of
Columbus OM. You want the server instance to print the entries in sequence.
1

On the client, set this parameter in the system defaults table:


UID_order

In the lpdservers configuration table (config.tab), set these parameters:


RestrictedMode
Action_On_AddFailure
Temp_Path

YES

YES
"syq -tnw lpdserver 5/2"
AUTO

Setting RestrictedMode to Yes ensures that lpdserver processes the


requests that it receives in order.
The value for the Action_On_AddFailure parameter shuts down
lpdserver if lpdserver cannot add an entry to the Columbus OM queue,
so that subsequent lp/lpr requests are not affected.
Setting the Temp_Path parameter tells lpdserver to use a temporary file
in the $UNIQDIR/queue/document folder. Doing this saves a file copy
process.

On the server, set this parameter in the system defaults table:


UID_order

YES

Configuring lpdserver
Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Action_On_AddFailure script

Specifies a command to be obeyed in the event that a request was not added
successfully to the pending queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Converting lpr/lpd requests to Columbus OM print entries

For example, this example stops lpdserver if it cannot add to the queue thus
alerting subsequent lp/lpr requests:
Action_On_AddFailure

"syq -tnw lpdserver 5/2"

Action_On_Shutdown command

A command to be run when the server stops. For more information, see
Operating system actions during processing on page 417.
Bundle_Files YES|NO

All items from the lp/lpr command line will be put in one queue entry.
This parameter cannot be used with RestrictedMode YES.
Class CRYPT|DEST|IGNORE|PAPER|SECLEV|SOURCE

The action to be taken when the server is sent a Receive Job subcommand C
specifying a class name.
To

Specify

ignore the command (this is the default value)

IGNORE

use the class value as the entrys encryption method (the value
must be No, Yes, AES128, AES192 or AES256)

CRYPT

use the class value as the entrys destination host

DEST

use the class value as the entrys paper type

PAPER

use the class value as the entrys security level

SECLEV

use the class value as the entrys source host

SOURCE

Local_Host host

The network card to which a server binds. This parameter is required only if
the computer has multiple network cards (which means that it also has multiple
host names).
The value can be:

the computer name, for example: MyServer01

the IP address, for example, 10.0.20.123

0.0.0.0, to bind to any network card that is on the host.

If the Local_Host parameter is omitted, Columbus OM uses the IP address of


the host.
Medium PRINT

The medium name used when adding an incoming document to the


Columbus OM print queue.
NAK_Immed Yes|No

Controls what happens if the lpdserver cannot write the data file that it receives
to the disk (for example, if the disk is full). Setting this parameter to Yes sends a
NAK to the sender immediately.

COLUMBUS OM INSTALLATION AND CONFIGURATION

229

230

CHAPTER 9

Adding entries

Converting lpr/lpd requests to Columbus OM print entries

Preprocess OWNER|PAPER|ALIAS=DF_NAME[n:m]

Extracts the owner name, paper type, or alias from the document filename.
Specify the position of the value that is in the filename by using [n:m]. (Include
the brackets.)

n is the number of the character where the value starts. If the value starts at
the start of the filename, you can omit the n part.
m is the number of the character where the value ends. If the length of the
value varies, you can omit the m part.

For example, if the filename includes the owners name like this:
ABCDE0123SMITH (where SMITH is the owners name)

you can set the owner property of the entry when it is added to the print queue
by specifying: PREPROCESS OWNER=DFNAME[10:14] (if the name is always 5
characters) or PREPROCESS OWNER=DFNAME[10:] (if the name always starts at
the 10th character but can be any length).
Priority n

A number from 1 to 9 which lpdserver will set as a priority on all the requests
it receives.
RestrictedMode YES|NO
YES to send a response back after the entry has been added to the pending
queue. (Normally lpdserver sends a response back to the sending process
after the print request has been received but before it has been added to the
pending queue.)
RestrictedMode YES also ensures that entries are added to the pending queue
in sequence. (Note that lpdserver can only honour the sequence if a regular
form of the lpr/lpd protocol is used. Thus lpr requests which result in the
control and data file set not being sent as a contiguous pair are excluded as are
additional copies that are specified on the command line.)

Because indexing large PCL files might cause the protocol to time-out, it is
recommended that AEQ_index is set to NO in the systems default
(default.tab) when using this mode.
It is recommended that Action_On_AddFailure is set for use with this mode.
Scan_Instances YES|NO
YES (the default) to transfer incoming lpd requests to the instance where the
specified printer is configured; NO to queue it on the local instance.
Security_Level number

The security level to be applied to entries. The security levels that you can use
are stored in the seclev.tab file.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Converting lpr/lpd requests to Columbus OM print entries

Service service

The name of a service, which is defined in the operating systems services


file, and used in conjunction with the protocol tcp to identify a
communications port.
The default value is printer, which normally identifies the standard lpd port,
515.
SuperLock YES|NO
YES forces lpdserver to add entries to the pending queue in order of their
UID. This slows performance. Set this parameter to NO unless you specifically

want to use this feature.


Temp_Path folder|AUTO

The full path of a folder used to hold documents temporarily, used instead of
the systems default temporary location which might have insufficient capacity.
AUTO means that the temporary file will be created in
UNIQDIR%\queue\document. This is the preferred option since an additional

copy is not involved.


Timeout number

The delay in seconds after which a network connection attempt is deemed to


have failed. The default is 60.
Wait_Time number

The interval in seconds at which the server suspends its normal listening
function in order to perform any necessary housekeeping. The default is 10.
Zero_Is_ASCII Yes|No

Tells Columbus OM how to process files whose size is indicated in the data file
to be zero.

Yes tells Columbus OM to finish the job immediately. Use this setting only

if your lp/lpr programs set the file as zero and send only ASCII files.

No tells Columbus OM to wait for the timeout period and then finish the

job.

COLUMBUS OM INSTALLATION AND CONFIGURATION

231

232

CHAPTER 9

Adding entries

Transferring documents from other hosts into Columbus OM

Transferring documents from other hosts into


Columbus OM
Users without direct access to a Columbus OM instance can still use it to print
documents, if they can transfer files to the host on which a Columbus OM instance
is installed. Use this method only as a last resort, as it does not give users access to
the tracking, monitoring and other features that are in the Columbus OM user
interfaces.
This feature uses Columbus OMs ftserver server. ftserver monitors the folder
to which users transfer the documents that they want to process. When it finds a file
to be processed, it adds the file to the Columbus OM queue.
Configuring the ftserver server
1

Create a list of commands that you want Columbus OM to process, for


example, apq and aeq commands. See Creating the list of permitted
commands below.

Choose a folder (on the Columbus OM host) into which users will transfer the
files that they want to be processed.

Configure ftserver to tell it which folder you have chosen, how often you
want it to check the folder, and so on. See Configuration parameters for
ftserver below.

To add a document to the queue, see Printing a document or sending a fax


using ftserver on page 233.

Creating the list of permitted commands


1

In the %UNIQDIR%\servers\ftserver folder, create a file called


permitted.tab.

In the file, list the Columbus OM commands that you want ftserver to
process (for example, apq and aeq).

Against each command, specify the maximum amount of time (in seconds) that
you want ftserver to spend servicing a request of that type, for example:
aeq 10
apq 10

Configuration parameters for ftserver


To configure ftserver, set its configuration parameters:
Parameter

Value

Incoming_Directory

The folder in which users will put the files that they
want processed.
The value can include operating system variables
${name} and Columbus OM variables %name.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Transferring documents from other hosts into Columbus OM

Parameter

Value

Wait_Time

The interval (in seconds) at which you want ftserver


to check the folder to see if there are any documents to
process.

Start_Delay

The delay (in seconds) between locating a document


for printing and starting to process the file.

Printing a document or sending a fax using ftserver


For each document that you want to print, you have to create two files:

one file containing the document

one file containing the command that you want Columbus OM to use to
process the document (usually an apq command).

Create the document file with the name filename.Dnn, where:

filename can have a maximum of 10 characters

D can be uppercase or lowercase

nn is any two digits.

For example, myreport.D01.


2

Create the command file with the same name as the document file, but with C
instead of D, for example: myreport.C01. The C can be uppercase or
lowercase.

In the command file, put a Columbus OM command to add an entry to the


Columbus OM queue. The command must be in the permitted.tab file.
In the command, replace the document filename with %s. For example:
apq %s -at print1

or
apq %s -at print1 -rt "Transferred from mainframe"
4

Transfer the document file and the command file to the folder specified by
ftservers Incoming_Directory parameter. Make sure that the document
file is put into the folder before the command file.
The ftserver server monitors the folder, and when it finds a document file
and matching command file, adds them as an entry to the pending queue.

Tracking errors
If ftserver can not issue the command, it:

puts an error message in a file called filename.Enn (where the filename and
nn are the same as in the original file)
renames the original files by putting B (or b) on the end.

COLUMBUS OM INSTALLATION AND CONFIGURATION

233

234

CHAPTER 9

Adding entries

Processing files in scanned folders

Processing files in scanned folders


The filein server scans a folder for files, and adds them to Columbus OM. This is
for use with other applications that are creating files and putting them into the
scanned folder; the filein server then processes the files when they are ready.
How the filein server works
1

You specify a folder for the filein server to scan. You put the files that you
want it to process into this folder or subfolders of it (or you configure the
application that creates the files to put them there).

You can process files in either single mode or batch mode:

In single mode, the filein server looks for files in the folder. When a file
stops growing in size, Columbus OM processes it.
If the processing succeeds, Columbus OM deletes the file.
If the processing fails, Columbus OM moves the file to another folder.

In batch mode, the filein server looks in the subfolders. When an end of
batch file appears in the folder, Columbus OM processes all the other files
that are in the folder.
If the processing succeeds, Columbus OM deletes the files and the
subfolder.
If the processing fails, Columbus OM moves the files to another folder, and
deletes the subfolder.

You can configure the filein server to send the files either to a specific
destination, or to select a destination according to the requirements of the files.

Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Server filein

Set to filein.
Medium text

The medium that you will assign to the entries that you want the server to
process.
Action_on_Start command
Action_on_Postponement command
Action_on_Completion command
Action_on_Failure command
Action_on_Shutdown command

Actions to be performed in response to events. For more information, see


Operating system actions during processing on page 417.
Attempts_Limit n

The maximum number of times that the server tries to select a destination.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Processing files in scanned folders

This parameter applies only if the Auto_Select parameter is set to Yes. See
also the Postpone_Time parameter.
Auto_Select Yes|No

To use a specific destination, set this parameter to No, and then set the
Destination parameter.
To select a device from the device pool, set this parameter to Yes, and then set
the Devpool, Select_Criteria, and Sort_Criteria parameters.
Destination text

The destination to which the files are to be sent.


To use this parameter, you must also set the Auto_Select parameter to No.
Devpool filename

The name of the device pool file to be used. For more information about
creating a device pool file, see Creating a pool of devices on page 327.
To use

Do this

%UNIQDIR%media\xselect\pool
\devpool.tab

Leave this parameter blank

a specific file

Specify the path and name of the file


(for example,
c:\MyFiles\MyPool.tab)

a specific file in the filein servers


folder, or the %UNIQDIR\media\
xselect\pool\ folder

Specify the name of the file (for


example, mypool.tab).
Columbus OM looks for the file in the
filein servers folder. If it is not
there, it looks in the
media\xselect\pool\ folder.

To use this parameter, you must also set the Auto_Select parameter to Yes.
Directory_Read_Order OLDEST_FIRST|UNSORTED

Specifies the order in which the server processes the files that are in the
scanned folder:

OLDEST_FIRST processes the files in the order in which they were put in

the folder.

UNSORTED processes the files in alphabetic order.

The default value is UNSORTED.


EOB_File filename

(Applies only if Scan_Mode is set to BATCH.) The name of the file that will be
added to the scanned folder to indicate that the batch is complete.
See also the Queue_EOB and Scan_Mode parameters.
Empty_Wait n

Interval (measured in seconds) to wait before processing an empty file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

235

236

CHAPTER 9

Adding entries

Processing files in scanned folders

Error_Dump folder

The folder in which files that cannot be processed are to be put.


Incoming_Wait n

Period (measured in seconds) to wait after a file stops growing, before the
filein server starts to process it.
See also the Scan_Mode parameter.
Owner text

The owner to be assigned to the entries.


Postpone_Time n

The interval (measured in seconds) between attempts to select a destination.


This parameter applies only if the Auto_Select parameter is set to Yes. See
also the Attempts_Limit parameter.
Prefix filename

The name of a file to be added to the front of each file that is processed.
Queue_EOB FIRST|LAST|NO

Controls whether the end of batch file is to be added as an entry to


Columbus OM. (See also the EOB_File parameter.)
To

Set this parameter to

not add the file

NO

add the file after the other files

LAST

add the file before the other files

FIRST

Scan_Interval n

The frequency (measured in seconds) at which the filein server scans the
folder.
See also the Scan_Root parameter.
Scan_Mode BATCH|BOTH|SINGLE

The mode in which the filein server is to work: one of SINGLE, BATCH or
BOTH. See also How the filein server works on page 234.
Scan_Root folder

If filein is working in single mode: the folder to be scanned for files


If filein is working in batch mode: the folder to be scanned for subfolders.
Security_Group text

The security group to be applied to the entries.


Security_Level n

The security level to be applied to the entries.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Processing files in scanned folders

Select_Criteria filename

The selection criteria file to be used. For more information about creating a
selection criteria file, see .
To use

Do this

media\xselect\select\
select_criteria.tab

Leave this parameter blank

a specific file

Specify the path and name of the file


(for example,
c:\MyFiles\MySelect.tab)

a specific file in the filein servers


folder, or the
%UNIQDIR%\media\xselect\
select\ folder

Specify the name of the file (for


example, MySelect.tab).
Columbus OM looks for the file in the
filein servers folder. If it is not
there, it looks in the media\xselect\
select\ folder.

all possible criteria

Specify ALL.

This parameter applies only if the Auto_Select parameter is set to Yes.


Sort_Criteria filename

The sort criteria file to be used. For more information about creating a sort
criteria file, see Selecting from similar devices on page 329.
To use

Do this

media\xselect\sort\
sort_criteria.tab

Leave this parameter blank

a specific file

Specify the path and name of the file


(for example,
c:\MyFiles\MySort.tab)

a specific file in the filein servers


folder, or the %UNIQDIR%\media\
xselect\sort\ folder

Specify the name of the file (for


example, MySort.tab).
Columbus OM first looks for the file
in the filein servers folder. If it is
not there, it looks in the
media\xselect\sort\ folder.

the TIME criteria (fastest printer first) Specify TIME.


This parameter applies only if the Auto_Select parameter is set to Yes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

237

238

CHAPTER 9

Adding entries

Reference

Reference
System parameters
These parameters can be set in the system defaults file (default.tab).
Address server

The destination used if you use the aeq or apq command without specifying
one: a print server, a fax number, or whatever is appropriate for the instance.
AEQ_Default ERROR|PROMPT|STDIN

What happens if you use the aeq, afq or apq command without specifying the
source of the document:
ERROR

Displays an error message.

PROMPT

Prompts for up to eight source documents.

STDIN

Reads the document from standard input (stdin).

APQ_Val_Attr YES|NO|printer_type
YES validates device-related attributes (font, hopper, orientation, and so on) in
an apq command.
NO adds the request to the queue without validation.

The nature of the validation depends on the destination:


A local printer

The request is rejected if the printer type of the specified


server is undefined, or does not support the attribute.

A printer class

Validation is performed against the first local printer of the


server class.

A remote printer

Normally, no validation is performed. However, if


APQ_Val_Attr is set to a printer type, validation is
performed both for local printers and classes (as already
described), and for remote requests by assuming that the
remote printer has this printer type.

APQ_Val_Dest YES|NO
YES validates the destination server in an apq command.
NO adds the request to the queue without validation.

The default value is YES.


Ignore_Signals YES|NO

(UNIX only.) YES ignores signals (which are sometimes issued spuriously)
when a document is being added to a queue.
NO issues a warning message.

The default value is NO.


Medium DISPATCH|FAX|PRINT|MAIL|WEB etc

The medium used if you use the aeq command without specifying one.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 9

Adding entries

Reference

PCL_Converter XREQS|NONE

Specifies the program that is used to process documents that are in PCL format;
the program usually used is xreqs. (xreqs supersedes the PCLRead program
that was used in earlier versions of Columbus OM).
NONE turns off print indexing.

The default value is XREQS.


Print_Command file
Print_Finishing file
Print_Font file
Print_Hopper file
Print_Orientation file
Print_Out_Hopper file
Print_Paper paper_type
Print_Pitch file
Print_Presentation file

The printer options used if you use the apq command without specifying them.
Priority number

The priority used (0 9 ) if you add an entry without specifying it.


The default is 5.
Unknown_Doc_Type type

The document type used, if the type cannot be otherwise identified.


For example, to assume that documents are in text format, even if they do not
have .txt as the file name extension, set this parameter to TEXT.

COLUMBUS OM INSTALLATION AND CONFIGURATION

239

240

CHAPTER 9

Adding entries

Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

241

C H A P T E R 10

Chapter 10

Managing entries

To

See

display the entries that are in the queue Displaying entries on page 242
change the properties of an entry

Changing entries on page 255

reprint a document that is in the queue

Resubmitting documents on page 257

restart a document that is Held,


Blocked or Paused

Restarting documents on page 259

delete an entry from the queue

Deleting entries on page 260

COLUMBUS OM INSTALLATION AND CONFIGURATION

242

CHAPTER 10

Managing entries

Displaying entries

Displaying entries
Displaying entries using Columbus OM Explorer
Selecting the queues that are displayed
1

On the View menu, click Options.

In the Columbus OM Preferences dialog box, click the Customise tab.

Click Config.

In the Queue Options dialog box, select the queues that you want to display,
and then click OK.

Selecting the documents to be displayed


1

On the View menu, click Options.

In the Columbus OM Preferences dialog box, click the Options tab, and then
click Filter Queue.

In the Filter Queue dialog box appears, select the criteria that you want the
documents to meet to be included in the display.

Click OK.

Controlling how many documents are displayed at once


To improve the speed of Columbus OM Explorer, you can reduce the number of
documents that are displayed at once.
1

On the View menu, click Options.

In the Columbus OM Preferences dialog box, click the Customise tab.

Under Queue Buffering, click Buffering.

In the Queue Buffering dialog box, click Cache, and then type the maximum
number of documents that you want displayed at once.

Click OK.
Columbus OM Explorer changes the queue so that only the first group of
documents is displayed.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

To display the next group of documents, click the

Displaying entries

toolbar button.

Changing what information is displayed


To

Do this

display the files as large icons

Click the Large icons toolbar


button.

display the files as small icons

Click the Small icons toolbar


button.

display the files in a list

Click the List toolbar button.

display detailed information about the


files

Click the Details toolbar button

move a column

Drag the column heading to a new


position.

change which columns are displayed

On the View menu, click Options. On


the Columns tab, select the columns
you want to display.

sort the entries

Click the heading of the column on


which you want the entries sorted.

(Changing the order in which the


documents are displayed does not
change the order in which they are
processed.)
reverse the sort order

Click the column heading again.

set the default sort order

On the View menu, click Options.


Click the Options tab, and then select
the column in the Sort By Column list.

Updating the display


Columbus OM Explorer automatically updates the display at regular intervals.
To

refresh the document queue yourself

On the View menu, click Refresh.

change how often Columbus OM


Explorer updates the document queue
display

On the View menu, click Options.


Click the Customise tab, and then click
Refresh. Type the interval (measured in
minutes) at which you want
Columbus OM to update the display.

COLUMBUS OM INSTALLATION AND CONFIGURATION

243

244

CHAPTER 10

Managing entries

Displaying
information
about a
document

Displaying entries

To

Do this

display general information

Click the document you want to check,


and then click Properties on the File
menu. In the Properties dialog box, click
the Statistics tab.

check the current status of a document

Click the document you want to check,


and then click Query on the Entry
menu.

Checking the status of a document

The Status column gives more information about the progress of a document.
Status

Description

Blocked

The paper type specified for the document is not available on the
printer. There are two solutions: you can either change the paper
type specified, or mount the paper type on the printer. See
Restarting Blocked documents on page 259.

Complete?

Multiple actions were performed on the document; more actions


succeeded than failed.
This status can occur only with documents that were processed by
using a dispatch server.

Completed

The document has been processed successfully.

Failed

Columbus OM Explorer has attempted to process the document,


but could not complete it. This may be because a printer is out of
order or an incorrect fax number has been specified.

Failed?

Multiple actions were performed on the document; more actions


failed that succeeded.
This status can occur only with documents that were processed by
using a dispatch server.

Held

The document has been put on hold. It will be processed only


when it is released: see page 259.

New

The document is waiting to be processed.

Paused

The printer that the document is being printed on has been


paused.
To start the printer again, see Restarting Paused documents on
page 259.

Postponed

Columbus OM Explorer could not print the document last time it


tried, and it will try again later.

Printing

The document is currently being sent to the printer.


To stop the document being printed, see page 255.

Started

The document is currently being processed.


To stop the document being processed, see page 255.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Displaying the
contents of a
document

Managing entries

Displaying entries

Status

Description

Transferred

The document has been transferred to another printer.

TxStarting
(and other Tx
statuses)

Tx indicates the document is being processed by a remote printer


(one that is controlled by a Columbus OM instance on another
host computer)

Columbus OM Explorer includes functions that can display the contents of


documents that are in text format and PCL format. For documents that are in
different formats, you can choose a program in which to display them.
To

Do this

display the contents of a


document

Click the document icon. On the Entry menu, click


Browse.

download the document


to your PC

Click the document icon. On the Entry menu, click


Download.

display a confirmation
On the View menu, click Options. In the Preferences
message before displaying dialog box, click the File Types tab. In the Prompt
very big documents
box, specify a size (in megabytes); if a document is
bigger than this size, Columbus OM displays a
confirmation message before opening it.
Navigating the document
To

Do this

move quickly through the document

Drag the scroll bar.

move to the next page

Click the Next Page toolbar


button.

move to the previous page

Click the Previous Page toolbar


button.

display a specific page

Click the View Page No.


toolbar button.

Type the page number.

Click OK.

go to the first page

Click the First Page toolbar button.

go to the last page

Click the Last Page toolbar button.

search for text in the document

On the Search menu, click Find.

move forwards to the next occurrence of On the Search menu, click Find Next.
the text
print the document again (add it to the
queue as a new entry)

COLUMBUS OM INSTALLATION AND CONFIGURATION

On the File menu, click Print.

245

246

CHAPTER 10

Managing entries

Displaying entries

Additional features for PCL documents


To

Do this

change the size of the image

Click the Zoom toolbar button.

rotate the image 90 degrees clockwise

Click the Rotate Clockwise


toolbar button.

rotate the image 90 degrees


anticlockwise

Click the Rotate Anticlockwise


toolbar button.

Displaying entries using the command line


To display a list of entries that are in the queue and information about them from
the command line, use these commands:
To

See

display a list of entries

liq: Displaying pending and completed


queue entries on page 250

create a file that contains information


about entries

getacc: Reporting information about


entries on page 246

display information about an entry that xinfo: Displaying information about


has not been completed
entries on page 252
find out why an entry has not been
completed

getacc:
Reporting
information
about entries

uqwhy: Finding why an entry is not


printing on page 253

The getacc command produces a report about entries in the pending and
completed queues.
To

See

specify the entries that you want to


include by their entry number

Selecting entries by their number on


page 246

specify the entries that you want to


include by their completion date and
time

Selecting entries by their completion


date on page 247

control the format of the report

Specifying the format of the report on


page 247

specify the name and location of the


report file (instead of using standard
output)

Specifying the name and location of the


report file on page 249

Options for this command are case-sensitive; for example, you must use -pf (not
-PF), and so on.
Selecting entries by their number
Syntax
getacc number [, number] ... [options]

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Displaying entries

Parameters
number

An entry number. The entry can be in either the pending queue or the
completed queue. You can also specify a range of numbers, for example: 1100.
options

See Specifying the format of the report on page 247, Specifying the name and
location of the report file on page 249 and Other options on page 249.
Selecting entries by their completion date
Only entries that are in the completed queue have a completion date.
Syntax
getacc -f from_date -t to_date [options]
Parameters
from_date

The completion date and time of the earliest entry that you want to include.
You can specify either a relative or absolute value:

To specify a relative date and time, use: -[dd.]hh:mm

To specify an absolute date and time, use: hh.mm [dd Mon yyyy]

For example:
-4:00

4 hours ago

-2.00:00

2 days ago

14:45

2:45pm today

0:00 01 jan 2005

The beginning of 2005

to_date

The completion date and time of the latest entry that you want to include.
options

See Specifying the format of the report below, Specifying the name and
location of the report file on page 249 and Other options on page 249.
Specifying the format of the report
-pf filename
-sf filename
-pf adds extra text to the start of the report.
-sf adds extra text to the end of the report.
filename is the name of the file that contains the text to be added. The text can

include substitution variables (see Substitution variables on page 603).

COLUMBUS OM INSTALLATION AND CONFIGURATION

247

248

CHAPTER 10

Managing entries

Displaying entries

Columbus OM looks for the files in the


%UNIQDIR%\media\accdata\templates folder. If a file is in a different folder,

include the path.


The default values are: %UNIQDIR%\media\accdata\templates\prefix.tab
and %UNIQDIR%\media\accdata\templates\suffix.tab.
If you want a report without a prefix file or a suffix file (and the default files
exist), specify the parameters as -pf "" or -sf "".
If you use either of these options, you cannot use the -tl option.
-tf filename

Specifies the name of a file that defines the format in which the entries are to
appear. The file is a text file containing one or more lines of data, including
substitution variables (see Substitution variables on page 603) to indicate
where information about an entry is to appear. For an example of the file, see
Example on page 249.
Columbus OM looks for the file in the
%UNIQDIR%\media\accdata\templates folder. If the file is in a different

folder, include the path.


The default value is:
%UNIQDIR%\media\accdata\templates\template.tab.

If you use this option, you cannot also use the -tl option.
-tl filename

Uses different formats in the report, according to the medium of the entry. In
the file, specify the template file to be used for each medium, and (optionally)
the prefix file and template file to be used for all media, in this format:
type

filename

type

The item that the file specified is to be used for, that is, one of:
prefix_file, suffix_file, the name of a medium, or *
(asterisk) for all media not otherwise mentioned.

filename

The name of the file to be used. Columbus OM looks for the


file in the %UNIQDIR%\media\accdata\templates folder. If
the file is in a different folder, include the path.

For example:
prefix_file
print
fax
*
suffix_file

MyStartFile.txt
MyPrintTemplate.txt
MyFaxTemplate.txt
MyGeneralTemplate.txt
MyEndFile.txt

If you select the entries by their entry number, and do not use -tf or -tl,
Columbus OM uses -tf %UNIQDIR%\media\accdata\templates\
template.tab.
If you select the entries by completion date, and do not use -tf or -tl,
Columbus OM uses -tl $UNIQDIR\media\accdata\lists\list.tab.
If you use this option, you cannot also use the -pf, -sf or -tf options.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Displaying entries

Specifying the name and location of the report file


To use a specific file name and location, use the -rf option.
If you let Columbus OM generate the file name, you can specify the file name
extension and the file location by using the -rs, -rt and -rd options.
To write the report to standard output instead of a file, omit all these options.
-rf filename

The name of the file to be created. If the file already exists, Columbus OM
overwrites it.
The default location is %UNIQDIR%\media\accdata\reports. To create the
file in a different folder, include it in the filename.
If you use this option, you cannot also use the -rd, -rs or -rt options.
-rd folder

The folder in which the report is to be created.


The default folder is %UNIQDIR%\media\accdata\reports.
If you use this option, you cannot also use the -rf option.
-rs text

The file name extension. The default value is no suffix.


The text must be different from the suffix specified by the -rt option.
If you use this option, you cannot also use the -rf option.
-rt text

A temporary suffix to be used while the file is being created. When the file is
complete, Columbus OM changes the suffix to the one specified by the -rs
option.
This suffix must be different from the suffix specified by the -rs option.
If you use this option, you cannot also use the -rf option.
Other options
-no_banner|-nb
-queue_name|-qn instance
-silent|-si

See User variables on page 612.


-vn integer

The value of user variable n (0 9). Accessed by the %PARAMn substitution


variable.
-m text

The value of a user message. Accessed by the %MESSAGE substitution variable.


Example
To produce a file with information about the entries, and their status and size, you
could use a template file like this:

COLUMBUS OM INSTALLATION AND CONFIGURATION

249

250

CHAPTER 10

Managing entries

Displaying entries

%UID,%DESTINATION,%STATUS,%PAGES,%XREQ(LARGEST_PAGE)

Run this command:


getacc 1-100 -rf myreport.txt

Columbus OM produces a file that contains entries like this:


100,myprinter1,New,10,12420
99,myprinter2,Completed,20,30317
98,myprinter1,Completed,10,15920
...

To produce a file with more formatting in it, you could use a template file like this:
Entry number: %UID
Device:
%DESTINATION
Total pages: %PAGES

Status:
%STATUS
Max page size: %XREQ(LARGEST_PAGE)

This template produces a report like this:


Entry number: 100
Device:
myprinter1
Total pages: 10

Status:
New
Max page size: 12420

Entry number: 99
Device:
myprinter2
Total pages: 10

Status:
Completed
Max page size: 30317

The liq command displays the entries that are in the pending and completed
liq: Displaying
queues.
pending and
completed queue
Syntax
entries
liq [option...]

This command starts the queue display. For information about the commands that
you can use once it is displayed, see Using the queue display on page 252.
By default, the command displays all the entries in the pending queue and
completed queue of the current instance that belong to you. To display entries in
other ways, use the following options:
Specifying the options
-ADDRESS_TEXT|-at text

Display entries sent to the destination specified.


-ANY_OWNER|-ao

Displays any users entries (not only yours).


-ANY_PENDING|-ap

Displays any users entries from the pending queue, and your own entries from
the completed queue.
-DUMB|-d

Displays entries in plain text, that is with features such as reverse video.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Displaying entries

-ENTRIES|-e number

Displays a specific number of entries


-GROUP|-g user_group

Displays entries that belong to the user group specified.


-LOCAL|-l

When issued from a client (in a client/server environment), displays entries


from the client queues as opposed to the server queues.
-MEDIUM|-m medium...

Displays entries with the medium specified.


MONITOR|-mn

Refreshes the display automatically when the status of an entry changes.


-OWNER|-o user_id

Displays entries that belong to the user specified.


-QUEUE_NAME|-qn instance

Displays entries from a different instance. The instance must be on the current
host computer.
-STATUS|-ss status...

Displays entries with the status specified.


-UID|-u entry_number

Displays information about the entry specified.


-PROMPT|-p string

Replace the standard command prompt with a string of up to 31 characters,


enclosed in quotation marks "..." if it contains spaces.
-SERVER_TEXT|-st string

Display entries whose product-specific server information includes the string,


ignoring case. The values that can be used here include these options:
dispatch entries

none

fax entries

-cs, -ft, -ov, -po, also HP, HPC, HPF, PCL, PCLC, PCLF, PS,
PSC, PSF, TEXT, TEXTC

print entries

-b, -co, -dc, -f,-fi, -hp, -nps, -oh, -or, -pp, -pr, -ps,
-pt

-SUMMARY|-s file

Changes the format of the display. f you do not include this, Columbus OM
uses the format that is defined in the %UNIQDIR%\config\liqsum.tab file.
-VDUMODE|-v command|OFF

An operating system command to be used to display text files, or OFF to display


as for a dumb terminal.

COLUMBUS OM INSTALLATION AND CONFIGURATION

251

252

CHAPTER 10

Managing entries

Displaying entries

Other options
-HELP|-h
-NO_BANNER|-nb

See Common parameters on page 602.


-NO_PROMPT|-np

Exit directly without prompting for further commands. Can be used in


conjunction with -DUMB, -ENTRIES and -SUMMARY to pipe standard output into
a file.
Using the queue display
In the queue display, use these commands:
Command

Description

Display the oldest completed entries on the queue

Redisplay the current page of the queue

Display the oldest pending entries, and the newest completed


entries, on the queue

Display a help page

L entry_id

Locate the entry_id

Enable queue monitoring

Display the next page of the queue

Display entries selected by: status, address, medium,


server text, filename or owner

Display the previous page of the queue

Quit from the liq display

Display the newest pending entries on the queue

entry_id

Display statistics for the entry_id

xinfo: Displaying To display information about entries that have been sent to a printer, but are not
yet complete, use the xinfo command. This command works with printers that use
information
the
xprinter driver.
about entries
Syntax
xinfo printer [interval]
Parameters
printer

The printer: either its IP address or the name that has been set up in
Columbus OM.
interval

The interval (measured in seconds) at which you want the display to be


updated.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

uqwhy: Finding
why an entry is
not printing

Managing entries

Displaying entries

To find out why an entry is not printing, use the uqwhy command:
Syntax
uqwhy entry_id [-QUEUE_NAME|qn instance] [-NO_BANNER|nb]
Parameter
entry_id

The entry number.


-QUEUE_NAME
-NO_BANNER

See Common parameters on page 602.

Displaying page counts


To display the number of pages that are in documents, set these parameters in the
system defaults file (default.tab):
Parameter

Value

AEQ_Index

Yes

This enables you to display the number of pages that are in


a document before the document has been processed.
Honour_Pagecount

YES uses the page count that is calculated by the application


that generated the document. This will be overridden if the
printer returns a page count.
NO uses Columbus OMs features for counting pages.

The default value is NO.


Print_Index

Yes

PS_Count_NonDSC

Controls how Columbus OM counts the pages in


documents that are not compliant with the PostScript
Document Structuring Convention (DSC).

YES tries to count the pages.


NO just reports the page count as 0. (If you use NO, also
set the GhostScript parameter to NO, otherwise
Columbus OM tries to use GhostScript to count the
pages.)

If you are using a PostScript printer and the page count for
a document is shown as 0, try setting the
PS_Count_NonDSC system parameter to Yes.
Temp_Path

The folder in which temporary files created during the


page counting and partial printing process supported by
Ghostscript are stored. The default is
$UNIQDIR/queue/document.

Use_xreqs

Yes uses the Columbus OM xreqs command to count the


pages in a document.

COLUMBUS OM INSTALLATION AND CONFIGURATION

253

254

CHAPTER 10

Managing entries

Displaying entries

If you are using a PCL printer, the page count for a document may be shown as
-1 to start with, while Columbus OM creates the index for the document.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Changing entries

Changing entries
Changing entries using the command line
To change the properties of an entry by using the command line, use the aeq
command. For more information, see aeq command on page 216.

Changing entries using Columbus OM Explorer


Changing entries before they are processed
To

See

increase the number of copies

Resubmitting documents on page 257

reduce the number of copies

Stopping the current document on


page 255

change other settings

Right-click the entry, and then click


Properties. Change the properties as
required.

To stop a document

Do this

temporarily (until you release it)

Click the document, and then click


Hold on the Entry menu.
To release the document, click it again,
and then click Release on the Entry
menu.

permanently

Click the document, and then click


Remove on the Entry menu.

until a specific date and time

Right-click the document, and then click


Properties. Click the Date/Time tab,
and then set the Defer To field.

until after another document has been


processed

Right-click the document, and then click


Properties. Set the Chained After
field.

Stopping the current document


Right-click the printer that is printing the document, and then do one of the
following:
To

Do this

abandon the current document, and


start the next one

Click Cancel Print Job.

COLUMBUS OM INSTALLATION AND CONFIGURATION

255

256

CHAPTER 10

Managing entries

Changing entries

To

Do this

put the current document on hold, and


start the next one

Click Abort Print Job.

pause the current document (and all


other documents waiting to be printed
on the same printer)

Click Pause Print Job.


When you want to start the document
again, right-click the printer, and then
click Resume Print Job.

Skipping pages in the current document


Right-click the printer that is printing the document, and then do one of the
following:
To

Do this

skip to a specific page number

Click Pause. Right-click the printer icon


again, and then click Goto Page in
Print Job. Type the number of the page
that you want to skip to.

skip a specific number of pages

Click Pause. Right-click the printer icon


again, and then click Advance Print
Job. Type the number of pages that you
want to omit.

Printing a document on two or more printers


Right-click the printer that is printing the document, and then do one of the
following:
To

Do this

split the document, to print it on two or Click Pause. Right-click the printer
more printers at the same time
again, and then click Split Print Job.
transfer the rest of the document to a
different printer (ASCII documents
only)

Click Pause. Right-click the printer


again, and then click Transfer.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Resubmitting documents

Resubmitting documents
Resubmitting documents using the command line
To resubmit an entry that is in the pending, completed, or archive by using the
command line, use the rsq command.
Syntax
rsq entry_id [entry_id]...
[-ARCHIVE|-ar number] [-OWNER|-o] [-RELEASE|-r]
common_parameters

To resubmit two or more entries, specify their entry numbers separated by spaces.
The maximum number of entries that can be specified is 100.
Options
Entries are resubmitted as belonging to the same user who submitted them, and
with Held status, unless you use one or more of these options:
To

Use

submit entries that are in an archive


queue

-ARCHIVE|-ar number
number is the number of the archive

queue. To specify the current archive


queue, use -ARCHIVE 0.
submit the entries with you as their
owner

-OWNER|-o

submit the entries as ready for


processing

-RELEASE|-r

Common parameters
-HELP|-h
-NO_BANNER|-nb
-NO_WARNING|-nw
-QUEUE_NAME|-qn instance
-SILENT|-si

See Common parameters on page 602.

COLUMBUS OM INSTALLATION AND CONFIGURATION

257

258

CHAPTER 10

Managing entries

Resubmitting documents

Resubmitting documents using Columbus OM Explorer


1

Select the document that you want to resubmit.


You can resubmit documents from any of the queues.

Do one of the following:


To

Do this

reprint a document (on either the


same printer or a different one)

On the Entry menu, click Reprint.

resend a fax document (to either the


same fax number or a different one)

On the Entry menu, click Resend.

The Reprint or Resend dialog box appears.


3

Type the Number of Copies that you want.

Specify when you want the document processed:


To process the document

Do this

as soon as possible

Clear Put on Hold.

only when you release it

Select Put on Hold.


When you are ready to print or send it,
see Restarting Held documents on
page 259.

on a different printer, or to a different Select Put on Hold, and then see


fax number
Changing entries on page 255.
5

If you want the documents Remark field set to indicate which document it is a
reprint of, select Reprint Remark.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Restarting documents

Restarting documents
Restarting documents using the command line
To restart documents by using the command line, use the opq command. For more
information, see Managing the entries on page 148.

Restarting documents using Columbus OM Explorer


To restart a document that is not being processed, find its status (displayed in the
Status column), and then do one of the following:
Restarting Held documents
Held indicates that a user has put the document on hold.
To restart the document, right-click it, and then click Release.
Restarting Blocked documents
Blocked indicates that the paper type specified for the document is not available
on the printer. To restart the document, you can either change the paper type
specified, or make the one that is specified available.
To

Do this

change the paper type

Right-click the document, and then click


Properties. On the Attributes tab,
change the Paper option.

make the paper type available on the


printer

Under the instances icon, click


Printers. Right-click the printer, and
then click Mount/Unmount Paper.
Select the paper types to assign.

Restarting Paused documents


Paused indicates that the printer has been paused.
To

Do this

restart the document at the page where it Right-click the printer that was printing
was paused
the document, and then click Resume.
restart the document, and reprint some
of the pages

COLUMBUS OM INSTALLATION AND CONFIGURATION

Right-click the printer, and then click


Backup.

259

260

CHAPTER 10

Managing entries

Deleting entries

Deleting entries
Deleting entries using the command line
To delete entries from the queue by using the command line, use the req
command.
Syntax
req entry_id... [option...]

Specifying the entry numbers


To delete

Do this

a single entry

Specify its entry number, for example:


req 432

two or more entries

Specify the entry numbers in a list, separating the


numbers with a space or a comma, for example:
req 1, 5, 12, 209

a range of entry numbers

Separate the first and last number by using a hyphen.


For example:
req 1,3,5-8,10

deletes entries 1, 3, 5, 6, 7, 8 and 10.


The maximum number of entries that you can delete in one command is 100.
Specifying the options
By default, the command deletes only entries that belong to you.
To delete

Use

entries from an archive queue

-ARCHIVE|-ar number
number is the number of the archive

queue. To specify the current archive


queue, use -ARCHIVE 0.
entries from the completed queue

-COMPLETED|-c

entries even if they are locked and being -FORCE|-f


processed
entries with a specific status

-STATUS|-ss text

entries that belong to another user

-OWNER|-o user_id

all users entries

-ANY_OWNER|-ao

entries that belong to members of a user -GROUP|-g user_group


group

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Deleting entries

Common parameters
For more information about these parameters, see Common parameters on
page 602.
-HELP|-h
-NO_BANNER|-nb
-NO_WARNING|-nw
-QUEUE_NAME|-qn instance
-SILENT|-si

Example
req 12000-13000 -c -ao -ss cancelled

Deletes all entries from the completed queue with numbers that are in the
range specified, and whose status is Cancelled.

Deleting entries using Columbus OM Explorer


1

Stop all the servers for the instance. (See Stopping servers on page 102.)

In Columbus OM Explorer, click the Advanced tab, and then click the icon
for the instance.

On the Maintenance menu, point to Purge Queue, and then click Pending,
Completed or Archive.

In the Number of Days to Retain box, specify which entries you want to
keep. For example, to keep all entries that are less than one week old, type 7.

You can create a journal file that records how many entries are deleted:
To

Select

overwrite the journal file, if it already exists

Overwrite

add the information the end of the journal file

Append

not record the information in the journal file

None

The journal file is in the %UNIQDIR%\servers\uqserver folder and it is called


pending.jnl, completed.jnl or archive.jnl.
6

Click OK.

COLUMBUS OM INSTALLATION AND CONFIGURATION

261

262

CHAPTER 10

Managing entries

Deleting entries

Deleting old entries automatically


You can tell Columbus OM to check the pending and completed queue at regular
intervals and delete the oldest entries.

The entries deleted from the pending queue are discarded, so use this feature
with care. Entries in the pending queue are ones that are waiting to be
processed, so if there are entries that have been waiting a long time, it might
indicate a problem.

The entries deleted from the completed queue can be either discarded or
moved to an archive queue.

Set these parameters in the printmaster configuration file


(%UNIQDIR%\printmaster\config.tab):
Parameter

Value

Purge_Time

When you want Columbus OM to check the pending


queue.
The default times are when the printmaster server
starts, and at midnight.
For example, to check the queue four times a day at
six-hourly intervals you might specify:
00:30,06:30,12:30,18:30.

Auto_Pending_Queue
Auto_Completed_Queue

How long (in days) you want entries to be kept before


they are deleted.
For example, to delete entries from the pending queue
that are more than one week old, set
Auto_Pending_Queue to 7.

Also, set these parameters in the system defaults file (default.tab):

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 10

Managing entries

Deleting entries

Parameter

Value

Auto_Purge

Automatically deletes the n oldest entries from the


completed queue when it becomes full, so that new
completed entries can be added.
Columbus OM records information about the entries
that it purges in this file:
%UNIQDIR%\purg_jnl.MONYY

If you do not want the information recorded, include


NO_JOURNAL flag in the value, for example:
Auto_Purge
Auto_Archive

100 NO_JOURNAL

The number of entries automatically archived from


the completed queue when it becomes full.
Columbus OM puts information about which entries
are moved in this file:
%UNIQDIR%\arch_jnl.MONYY

If you do not want the information recorded, include


NO_JOURNAL flag in the value, for example:
Auto_Archive

100 NO_JOURNAL

Keeping cancelled and failed entries


To retain cancelled and failed entries when the completed queue is purged, set
these parameters in the system defaults file (default.tab):
Parameter

Value

Description

Keep_Cancelled

Retains cancelled entries that are n days old or less.

Keep_Failed

Retains failed entries that are n days old or less.

These parameter applies whether the completed queue is purged by using the Auto
Purge command in Columbus OM Explorer, the syq -pc command,
printmasters Auto_Purge parameter, or the Auto_Purge parameter in
default.tab (see above).

COLUMBUS OM INSTALLATION AND CONFIGURATION

263

264

CHAPTER 10

Managing entries

Reference

Reference
System parameters
These parameters can be set in the system defaults file (default.tab):
LIQ_Entries number

The maximum number of entries to be displayed when listing the contents of


the queue. To set no limit, specify 0.
LIQ_Pgroups YES|NO|OWN

Determines whether printer security groups are considered when displaying


queue entries:
NO

(the default) A user sees only their own entries.

YES

A user sees all entries whose destination is a printer or class in a


group to which they have access.
Entries whose destination is a printer or class which is not in a group
cannot be seen by anybody.

OWN

A user sees all entries whose destination is a printer or class in a


group to which they have access, and their own entries (irrespective
of the destination).

COLUMBUS OM INSTALLATION AND CONFIGURATION

265

C H A P T E R 11

Chapter 11

Managing queues

The entries in a Columbus OM instances are arranged in queues.

The pending queue contains entries that are waiting to be processed.

The completed queue contains entries that are have finished processing (either
successfully or unsuccessfully).

The archive queue contains entries that have been completed, and are being
stored for future reference.

Columbus OM moves the entries between the queues as appropriate. The archive
queue is just one of several ways of storing documents: for more information, see
Archiving documents on page 335.
To

See

display information about the queues

Displaying the queues on page 266

increase the number of entries that can


be put in the queues

Increasing the capacity of the queues


on page 267

decrease the disk space occupied by the Reducing the capacity of queues on
queues
page 268
ensure that the queues are correctly
organised

Maintaining queue integrity and


efficiency on page 270

improve the performance of the queues Indexing queues on page 272


set the numbers that are applied to
entries

Controlling the entry numbers on


page 273

control what documents are allowed,


according to their size

Controlling what documents are put in


the queues on page 274

COLUMBUS OM INSTALLATION AND CONFIGURATION

266

CHAPTER 11

Managing queues

Displaying the queues

Displaying the queues


Displaying the queues in Columbus OM Explorer
To

Do this

display the queue statistics

Click the icon for the instance. On the


Maintenance menu, click Statistics.
Click the tab for the queue.

display the archive queue

Click the icon for the instance. On the


View menu, click Options. In the
Columbus OM Preferences dialog box,
click the Customise tab, and then click
Config. Select Display Archive
Queue, and then select the archive
queue from the list.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 11

Managing queues

Increasing the capacity of the queues

Increasing the capacity of the queues


Increasing the capacity of the queues manually
These options increase the capacity of a queue to the number of entries that you
specify. If the queue is already at this size or bigger, nothing happens.
Extending the pending queue
To

Use

extend the pending queue when all


the servers are inactive

syq -EXTEND_PENDING|-ep n

extend the pending queue when one syq -FORCE_EXTEND_PENDING|-fep n


or more servers is active
Extending the completed queue
To

Use

extend the completed queue when all syq -EXTEND_COMPLETE|-ec n


the servers are inactive
extend the completed queue when
one or more servers is active

syq -FORCE_EXTEND_COMPLETE|-fec n

Extending the archive queue


You are unlikely to need these commands, because Columbus OM extends the
archive queue manually.
To

Use

extend the archive queue when all the syq -EXTEND_ARCHIVE|-ea n


servers are inactive
extend the archive queue when one
or more servers is active

syq -FORCE_EXTEND_ARCHIVE|-fea n

Increasing the capacity of the pending queue automatically


To increase the capacity of the pending queue automatically, set this parameter in
the system defaults file (default.tab):
Auto_Extend n
n is the number of entries by which the pending queue is automatically extended

when it becomes full. If you do not want the pending queue to be automatically
extended, set this parameter to 0. (However, if the pending queue is full, and
cannot be extended, you can not add any more entries.)

COLUMBUS OM INSTALLATION AND CONFIGURATION

267

268

CHAPTER 11

Managing queues

Reducing the capacity of queues

Reducing the capacity of queues


When you set the size of queue, Columbus OM assigns disk space for the
maximum number of entries that the queue might contain. The disk space that is
occupied by the queue stays the same however many entries it actually contains. To
save disk space, you can reduce the maximum number of entries in the queue. This
process is called compressing the queue.
This is useful when Columbus OM has automatically extended a queue to handle
an unusually busy period, and then the load has returned to normal levels, leaving
space in the queue that is not needed any more.

Compressing the queues automatically


To compress the queues automatically, set the following parameters in the
printmaster configuration file
(%UNIQDIR%\servers\printmaster\config.tab):
To

Set this parameter

reduce the capacity of the pending


queue to n entries

Auto_Pending_Compress n

reduce the capacity of the completed


queue to n entries

Auto_Complete_Compress n

specify when you want the queue to be


compressed

Compress_Time hh:mm[,hh:mm]

Specify the times as hh:mm, for example:


18:15. To compress the queue two or
more times each day, separate the times
by using a comma, for example:
00:15, 06:15, 12:15, 18:15

The default value is 00:00 (that is,


midnight).
Columbus OM checks the queue at the time that you specify; if the queue is less
than 90% full, Columbus OM compresses it.

Compressing the queues manually


1

Stop all the servers that are scanning the queue.

Run this command:


qcompress queue number file

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 11

Managing queues

Reducing the capacity of queues

You must specify the parameters in the order shown.


Parameter

Value

queue

The queue that you want to compress:


Queue

Use

Abbreviation

archive queue number n

-ARCHIVE[n]

-ar[n] or -a[n]

Do not include a space before the


number.
completed

-COMPLETED

-c

pending

-PENDING

-p

number

The maximum number of entries in the queue. This must be less


than its current capacity, but more than the current number of
entries.

file

A temporary file used during compression, which must not already


exist, and which is deleted at the end of the process.

COLUMBUS OM INSTALLATION AND CONFIGURATION

269

270

CHAPTER 11

Managing queues

Maintaining queue integrity and efficiency

Maintaining queue integrity and efficiency


To maintain the integrity and efficiency of the queues, use the fix queue feature.
Fixing a queue makes sure that the format is correct, making sure that the header
counts match the entries, and organizing the free entries efficiently.
Columbus OM can be configured to fix the queues automatically at regular
intervals. You can also fix the queues manually.

Fixing queues automatically


Columbus OM automatically checks the pending and completed queues, and fixes
them if necessary, every 60 minutes. To change the intervals at which it does this, or
turn off the automatic fixes, set the Fix_Interval parameter for printmaster.
To

Set Fix_Interval to

check and fix the queues at start-up, and if an error is


detected when printmaster scans the queue for new
entries

check and fix the queues every n minutes

turn off the automatic check

OFF

The dispatch server also fixes the queues automatically. If you do not want it to do
this, set the Auto_Fix parameter in the system defaults file (default.tab) file to No.

Fixing queues manually


1

Find out if the queue needs to be fixed by using one of these commands:
To

Use

validate the pending queue

syq -CHECK_PENDING|-cp

validate the completed queue

syq -CHECK_COMPLETE|-cc

validate the archive queue

syq -CHECK_ARCHIVE|-ca

If the results of the command indicate that the queue needs to be fixed, use one
of these commands:
To

Use

fix the pending queue

syq -FIX_PENDING|-fp [file]

fix the completed queue

syq -FIX_COMPLETE|-fc [file]

fix the archive queue

syq -FIX_ARCHIVE|-fa [file]

To record the changes that Columbus OM makes in a file, include a filename at


the end of the command.
If any servers are accessing the queue, use one of the force fix commands
instead:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 11

Managing queues

Maintaining queue integrity and efficiency

syq -FORCE_FIX_ARCHIVE|-ffa [file]


syq -FORCE_FIX_COMPLETE|-ffc [file]
syq -FORCE_FIX_PENDING|-ff [file]

COLUMBUS OM INSTALLATION AND CONFIGURATION

271

272

CHAPTER 11

Managing queues

Indexing queues

Indexing queues
To improve performance of accessing entries, the pending queue and completed
queues can be indexed. This is particularly effective when the maximum entry id
number (set by the Highest_UID parameter in the default.tab file) is exceeded
and Columbus OM starts renumbering the entries at 1.
To index the queues
1

Set the following parameter in the default.tab file:


Queue_Index No|Pending|Complete|Yes
To

Set this parameter to

index only the pending queue

Pending

index only the completed queue

Complete

index both the pending queue and the completed


queue

Yes

index no queues

No

The default value is No. The archive queue cannot be indexed.


2

Create the index by using one of these commands:


Queue

Command

Pending

syq -fp

Completed

syq -fc

If necessary, check the index by using the syq -cp or syq -cc commands.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 11

Managing queues

Controlling the entry numbers

Controlling the entry numbers


Columbus OM assigns a number to each entry that you add to the queue. You can
set the range of numbers that you want to be applied to entries, for example, 10000
19999. When Columbus OM reaches the highest number, it starts again. It
ensures that every entry in the instance has a different number. It does not re-use a
number if the entry that first used that number is still in the queue.
If you have two or more instances of Columbus OM, you can make sure that entry
numbers are unique across the entire system by setting ranges that do not overlap.
For example, you could set the entry range for instance A to 1 9999, and the entry
range for instance B to 10000 19999.
To set the range of entry numbers

Set these parameters in the system defaults file (default.tab):


Parameter

Value

Lowest_UID

The lowest entry number to be used.


The minimum number is 999.

Highest_UID

The highest entry number to be used.


The maximum number is 9999999.

Columbus OM Explorer (Highest UID only): Navigate to Advanced tab

instance icon

View menu

COLUMBUS OM INSTALLATION AND CONFIGURATION

Options

Defaults tab

Adding.

273

274

CHAPTER 11

Managing queues

Controlling what documents are put in the queues

Controlling what documents are put in the queues


To control what documents are put in the queue according to their size, set the
following parameter in the system defaults file (default.tab).
Parameter

Value

Min_File_Size The minimum number of characters that a file must contain

before being added to the queue. For example, to reject


documents that are 0 bytes in size, specify 1.
The default is zero (that is, files are not rejected because of their
size).
Columbus OM Explorer: Navigate to Advanced tab

menu

Options

Defaults tab

instance icon

View

Adding

This parameter affects the entire instance. To control the size of documents
accepted by each printer, see Testing the size of documents on page 154.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 11

Managing queues

Reference

Reference
liqsum.tab: liq display format
The liqsum.tab file defines the default display format used by the liq command,
which displays entries that are in the queue.
The same structure is also used for the %UNIQDIR%\config\arqsum.tab file,
which defines the default display format used by the arq command.
File location and name
%UNIQDIR%\config\liqsum.tab

Content
On the first line, specify the (number of characters) of the display, for example:
SCREEN_WIDTH 96

This line is optional; the default value is 80.


Then add one line for each property that you want to display. On each line specify
these columns:
Column Value

The name of the property to be displayed: see Displayable properties


on page 276.

The text to be displayed at the top of the column. If it contains spaces,


enclose it in quotation marks "...".

The width of the column (number of characters).


For timestamp fields ((DATE, DATE_CREATED, DATE_QUEUED,
FIRST_DATE, LATEST_DATE, NEXT_DATE and RETAIN_DATE), specify 0;
their width is displayed according to their format (that is, the next
column).

The format:
Data type Value

timestamp

See Date and time formats on page 610.

other types L aligns the value to the left; R aligns the value at the right.
5

The spacing (blank spaces) between this column and the next. The
default value is 1; a value of zero is permitted.

COLUMBUS OM INSTALLATION AND CONFIGURATION

275

276

CHAPTER 11

Managing queues

Reference

Example
# Column
# Name
# ----------UID
OWNER
NAME
PAGES
DESTINATION
PAPER
DATE
DATE
STATUS

Column
Column
Title
Width
----------- -----Entry
5
Owner
5
Document
14
Pages
5
Printer
10
Paper
8
'Date '
0
'Time '
0
Status
9

Format or
Justification
------------R
L
L
R
L
L
'DD MON'
'HH:MI'
L

Trailing
Spaces
-------1
1
1
1
1
1
1
1
1

Displayable properties
Property

Description

ALIAS

The text that is specified by the -ALIAS option.

ATTEMPTS

The number of attempts so far to process this entry.

CHAIN_UID

This entry depends on another entry, which must be


processed first.

CHARACTERS

The number of characters in the source document.

CHILD_FLAG

This entry might be a MASTER or a CHILD, or neither.

CRYPT_TYPE

How the document is encrypted.

DATE

The most recent of DATE_CREATED, LATEST_DATE and


NEXT_DATE.

DATE_CREATED

When the entry was added to the pending queue.

DATE_QUEUED

When the entry was added to its current section of the


queue.

DESTINATION

Where the document is to be sent (for example, a printer)

DOC_CODE

The text encoding of the source document, for example


PostScript or PCL.

DOC_ICODE

The numeric encoding of the source document. See


-DOCUMENT_CODE on page 220.

DOCUMENT

The source document. See also DOCUMENT_TYPE.

DOCUMENT_TYPE

If DOCUMENT is the name of a file: FILE.


If DOCUMENT is the information itself: TEXT.

FIRST_DATE

When Columbus OM first tried to process the entry.

HOST_NAME

The destination is on system host.

LATEST_DATE

The most recent attempt to process the entry.

LINES

The number of lines in the source document.

LSTATUS

The entrys current local status.

MASTER

This entry is a child of the master entry entry_id.

MEDIUM

The transmission medium.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 11

Managing queues

Reference

Property

Description

NAME

The value of either ALIAS (if specified) or DOCUMENT.

NEXT_DATE

When Columbus OM will next try to process the entry.

ORIG_UID

This entry was originally identified as entry_id.

OWNER

The entrys owner.

PAGE_LEN

Page breaks are to be calculated by counting number of lines


per page.

PAGES

The number of pages in the source document.

PAPER

The paper type to be used.

PREV_REM

Supplementary information qualifying PREV_STATUS.

PREV_STATUS

The value of STATUS immediately prior to its last change.

PRIORITY

0 (lowest) to 9 (highest).

PROGRAM

The program which created the queue entry (useful when


entries are being added directly from an application).

REMARK

A queue entry annotation. See also REMARK_TYPE.

REMARK_TYPE

FILE or TEXT, depending on whether REMARK is the name of


a file containing the information, or is the information itself.

RETAIN_DAYS

The minimum number of days that the entry is to stay in the


completed queue.

RETAIN_DATE

The timestamp before which the entry cannot be removed


from the completed queue.

RSTATUS

The entrys current remote status.

SEC_GROUP

The entrys security group.

SECLEV

The entrys security level, as a number.

SECLEV_NAME

The entrys security level, as text.

SERVER_INFO

Additional server-specific information. See also


SERVER_INFO_TYPE.

SERVER_INFO_TYPE FILE or TEXT, depending on whether SERVER_INFO is the

name of a file containing the information, or is the


information itself.
SOURCE_HOST

The host computer on which the entry originated.

STATUS

The entrys current status.

SUPP_REM

Supplementary information qualifying STATUS.

UID

The entrys unique identification number.

COLUMBUS OM INSTALLATION AND CONFIGURATION

277

278

CHAPTER 11

Managing queues

Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

279

C H A P T E R 12

Chapter 12

Controlling Columbus OM
with the dispatch server

The dispatch server provides an additional level of control over documents. It


enables you to process requests differently according to the contents of the
documents or some of the options that have been selected.
For example, you can:

make sure that all documents printed by users in a particular department are
printed on their printer

redirect documents sent to a printer that is unavailable to a different printer

put long documents on hold so that other documents can be printed first

combine separate documents into a single item or print only selected pages
from a document

control documents according to the text that they contain

process documents with multiple servers (for example, print an entry, fax it,
and then archive it).

Processing documents with a dispatch server


To use a dispatch server, you create a set of rules that identify which documents
you want it to process, and what you want to do with those documents. See
Creating rules on page 281.
Using the dispatch server
Add an entry to the Columbus OM print queue with the medium of the entry set to
the same as the medium of the dispatch server that you want to process the entry.

COLUMBUS OM INSTALLATION AND CONFIGURATION

280

CHAPTER 12

Controlling Columbus OM with the dispatch server

Configuring a dispatch server

Configuring a dispatch server


A dispatch server is automatically set up for you when you install a
Columbus OM print instance. You can change its configuration to match the
requirements of your installation.
Each dispatch server has its own set of rules. To process different documents in
different ways, you might need to create additional dispatch servers.

Dispatch server
properties

To

See

add a new dispatch server

Adding servers on page 98

change the properties of a dispatch


server

Configuring servers on page 99

These are the dispatch server properties that you are most likely to want to change.
For information about other properties, see dispatch server configuration
parameters on page 320.
Parameter

Value

Medium

The medium that is assigned to entries to indicate that you want this
server to process them (usually dispatch).

PrintCmd

Specify the command that is to be executed by the PRINT actions


that are in the servers rules file.
This is usually a Columbus OM apq command. The command
usually includes these substitution variables:

?FILE? (the document file)


?DEST? (the destination specified in the original command that
added the entry to Columbus OM).

The command can also include other substitution variables (see


Substitution variables on page 603).
For example:
apq ?FILE? -at ?DEST? -o %OWNER -qn print

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Creating rules

Creating rules
To configure a dispatch server to perform different actions on different
documents, you create rules. Each rule specifies:

which documents you want it to affect (for example, all those being sent to a
specific destination, or all those that contain a specific piece of text)

what you want to do with those documents (for example, put them on hold, or
print them on a specific printer).

To edit the rules for a dispatch server


1

In Columbus OM Explorer, click the Advanced tab, and then navigate to


instance Columbus OM Servers.

Click the dispatch server icon.

On the Servers menu, click Modify.

Set the Rules_File property to specify the rules file that you want the server to
use.

Click OK.

On the Servers menu, click Rules File.


The Rules File Editor appears.

Type the rules.


See Rule format on page 282.

On the File menu, click Save, and then close the Rules File Editor.
To make the server use the new rules file, you might need to restart it: for more
information, see Refreshing the server on page 99.

To check the rules

When you change the rules for a dispatch server, and then restart it, Columbus OM
checks that the rules are valid. If the rules are not valid, Columbus OM
immediately stops the dispatch server to ensure that the invalid rules are not
applied to any documents.
1

Check the status of the server to see if it has been started.

If the server has not started, find out what errors are in the rules by checking
the dispatch servers day log file.
See Log files on page 419.

Correct the errors, and then try to start the dispatch server again.

COLUMBUS OM INSTALLATION AND CONFIGURATION

281

282

CHAPTER 12

Controlling Columbus OM with the dispatch server

Rule format

Rule format
This section describes the format for a single rule in a dispatch servers rules file.
Each rules file can contain as many rules as you need.
Each rule must have:

A name to identify it.

A condition: this specifies which documents you want the rule to affect.

One or more actions: these specify what you want to do with the documents
selected by the condition.

Optionally, actions for the document that are not selected by the condition.

Rule syntax
RULE name
CONDITION expression
[action
[action]...]
[final action]
[flow control action]
[ELSE
[action
[action]...]
[final action]
[flow control action]
]

Parameters
name

The name of the rule. Each rule must have a different name.
CONDITION expression

A condition that selects the documents that you want the rule to affect. For
more information, see Selecting documents using a condition on page 284.
action

An action to be performed: for example, to change a property of the document


that is being processed. For more information, see Specifying the actions on
page 291.
final action

What you want to do with the document: for example, release it for further
processing or defer it. For more information, see Specifying the actions on
page 291.
flow control action

What you want Columbus OM to do after processing this part of the rule: for
example, stop processing or move to another rule in the rules file. For more
information, see Specifying the actions on page 291.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Rule format

ELSE [action [action]...]

Actions to be performed on documents that do not meet the CONDITION.


Including other files
To include the contents of other rules files in the rule, use:
INCLUDE filename

Replace filename with the path and name of the file.


Comment lines
To include comment lines in a rule, start them with a hash character #.
Long lines

The maximum length of a line is 1024 characters.

You can split long lines over several lines by putting a backslash character (\) at
the end of every line except the last.

Example rules
This rule selects documents that have been sent to the laser1 printer and prints
them on the laser2 printer instead.
RULE rule1
CONDITION %DESTINATION = laser1
PRINT laser2

This rule directs print jobs to printers based on their page count. Jobs exceeding 50
pages are printed on the laser1 printer. Jobs of 50 pages or less are printed on the
laser2 printer.
RULE rule1
CONDITION (%PAGES > 50)
PRINT laser1
ELSE
PRINT laser2

COLUMBUS OM INSTALLATION AND CONFIGURATION

283

284

CHAPTER 12

Controlling Columbus OM with the dispatch server

Selecting documents using a condition

Selecting documents using a condition


To specify which documents you want the actions to be applied to, you define a
condition.

Only documents that meet the condition will be affected by the actions that
follow it.

Documents that do not meet the condition will not be affected by the actions.
For these documents, you can specify a different set of actions (by using the
ELSE section of a rule).

The condition can check documents for:

a property, for example, the destination or the owner

a specific piece of text in a specific place (works only with ASCII format files)

whether they are part of a bundle (a bundle is a collection of documents that


can be created by the dispatch server).

Condition syntax
To

Use

test a value

CONDITION [^] item operator value

or
CONDITION !([^] item operator value)
CONDITION ALWAYS
specify a condition that is always
met, so that the actions that follow or
are performed on every document
CONDITION TRUE

CONDITION NEVER
specify a condition that is never
met, so that the actions that follow or
are never performed (this might be
CONDITION FALSE
useful when testing a rule)

Parameters
^

Makes the test case-insensitive.


!

Reverses the test, so that documents that do not meet the rest of the condition
will be affected by the rule.
item

The item you want to test. The item can include:

substitution variables, for example: %DESTINATION tests the destination of


the document and %OWNER tests the owner of the document. For a list of the
substitution variables that can be used, see Substitution variables on
page 603.
Columbus OM user variables, defined in variables files, and specified by
using %UQVAR(name,[file]).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

strings

numbers.

Selecting documents using a condition

operator

The type of test you want to make, one of:


Operator

Function

Equal to

!= or <>

Not equal to

<

Less than

<=

Less than or equal to

>

Greater than

>=

Greater than or equal to

Matches (equal to a value that uses wildcard characters). See also


Testing using wildcard characters on page 286.

value

The value that you want to test the item for: a string, number, a substitution
variable, or a macro (see Defining macros on page 288). If it is a string, put it
in quotation marks.
For a list of the substitution variables available, see Substitution variables on
page 603.
When testing a substitution variable for specific text, the text can include
wildcard characters. For more information, see Testing using wildcard
characters on page 286.
Examples
This rule affects all documents that are sent to printer1. These documents are not
printed; their status is set to Failed:
RULE rule1
CONDITION %DESTINATION="printer1"
FAIL

This rule also affects all documents that are sent to printer1. However, including
^ makes the test case-insensitive, so the rule also affects documents that are sent to
Printer1, PRINTER1, and so on:
RULE rule1
CONDITION ^%DESTINATION="printer1"
FAIL

This rule affects all documents that are not sent to printer1. These documents are
printed on a different printer:
RULE rule2
CONDITION !(%DESTINATION="printer1")
PRINT printer2 ALL

COLUMBUS OM INSTALLATION AND CONFIGURATION

285

286

CHAPTER 12

Controlling Columbus OM with the dispatch server

Selecting documents using a condition

Combining conditions
You can combine conditions by using these operators:
Operator

Function

& or &&

AND (both expressions must be true)

| or ||

OR (either expression must be true)

Examples
This rule selects documents that Columbus OM has tried to print more than three
times and have a priority of 1, and puts them on hold:
RULE rule2
CONDITION (%ATTEMPTS>3) & (%PRIORITY=1)
HOLD

This rule selects entries made by any one of the three users listed:
RULE rule3
CONDITION (%OWNER="john") | (%OWNER="mary") | (%OWNER="chris")
PRINT laser1 ALL

Testing using wildcard characters


When you want to test an attribute for a range of values, or you do not know the
exact value, you can specify the value using wildcard characters. For example, you
can select the documents whose names start with a.
To do this, use the match relational operator (~).
Syntax
variable ~ expression

Wildcard characters
Symbol

Matches with

Any characters (including none)

One character of any value.

[abc]

Any one of the characters in the brackets.

[^abc]

Any one character except those in the brackets.

To match any of the special characters, * ? [ ], precede the character with a


backslash \.
Examples
abc*

Matches anything that starts with abc, for example: abc, abcd, abcxyz.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Selecting documents using a condition

abc?

Matches anything that starts with abc, followed by any one character, for
example: abca, abcc, abcx (but not abc or abcxyz).
a[bcC]d

Matches with a string which starts with a, ends with d and includes one of
the characters in the brackets, for example: abd, acd, aCd.

Testing the contents of documents


To create rules that affect documents that contain a specific text string, use the
%CONTENTS variable. You tell the dispatch server:

what text to look for

which pages you want it to look on

where on those pages you want it to look.

Syntax
To search for the
text on
Use

any page of the


document

%CONTENTS("string", col, lin )

a specific page of the %CONTENTS("string", col, lin, page )


document
a range of pages in
the document

%CONTENTS("string", col, lin, startpage-endpage)

Parameters
string

The text string to look for.


col, lin
col and lin specify where on the page you want the dispatch server to look

for the text.


col specifies the column. lin specifies the line.
page

The number of the page on which you want the dispatch server to look for
the text.
startpage-endpage

A range of pages (two integers, separated by a hyphen), specifying the first and
last pages on which you want the dispatch server to look for the text.
Using %CONTENTS in a condition
In the condition, test for either a positive number or 0.

To select documents in which the text does appear at the specified location, test
for a positive number:

COLUMBUS OM INSTALLATION AND CONFIGURATION

287

288

CHAPTER 12

Controlling Columbus OM with the dispatch server

Selecting documents using a condition

CONDITION %CONTENTS("SALES DEPT", 1, 2) > 0

To select documents in which the text does not appear at the specified location,
test for 0.
CONDITION %CONTENTS("SALES DEPT", 1, 2) = 0

Examples
This condition selects documents where the text SALES DEPT appears at column 1,
line 2 on any page of the document.
CONDITION %CONTENTS("SALES DEPT", 1, 2) > 0

This condition selects documents where the text SALES DEPT appears at column 1,
line 2 on page 5.
CONDITION %CONTENTS("SALES DEPT", 1, 2, 5) > 0

This condition selects documents where the text SALES DEPT appears at column 1,
line 2 on page 5, 6, 7 or 8.
CONDITION %CONTENTS("SALES DEPT", 1, 2, 5-8) > 0

This condition selects documents where the text SALES DEPT does not appear at
column 1, line 2 on any page of the document.
CONDITION %CONTENTS("SALES DEPT", 1, 2) = 0

Counting the documents in a bundle


To find out how many documents are in a bundle, use the %BUNDLED variable.
You can create a bundle by using an action statement. For more information, see
Specifying the actions on page 291.
Syntax
%BUNDLED

Example
This condition is met when BUNDLE1 contains four documents.
CONDITION %DOCUMENT = BUNDLE1 && %BUNDLED = 4

Return value
If the document is not a bundle, the function returns the value zero.

Defining macros
To define a macro to use in a CONDITION, use the following syntax.
Syntax
The definition must be before the CONDITION in which the macro is referred to.
To define a macro, use:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Selecting documents using a condition

DEFINE name value

To define a macro that includes wildcard characters, use:


DEFINE name(argument[argument]...) value

Parameters
name

A name to identify the macro.


The name can include letters, numbers and underscore characters. It cannot
include spaces.
argument

A letter that may be replaced in the condition.


value

The value of the macro.


Referring to a macro in a CONDITION
To refer to a macro in a CONDITION, use:
?name

or
?name(argument)

Example
This rule shows some ways of using macros in a condition.

DEFINE a = "SALES" creates a shortcut to refer to a department. In the


conditions, %OWNER = ?a tests to see if the documents owner matches the
value of a.
DEFINE a(z) "MyPrinterz" creates a shortcut that handles wildcard
characters. (z) specifies the wildcard character; "MyPrinterz" specifies that
the wildcard character can appear as the tenth character of the name. In the
condition, %DESTINATION = ?a(1) replaces the tenth character of the
documents destination with 1. Therefore, if a user specifies the destination of a
document as MyPrinter1, this condition will apply to it.

Whichever condition applies to the document, Columbus OM changes the


destination and then advances to the next rule to change the medium of the
document and then release it for further processing.

COLUMBUS OM INSTALLATION AND CONFIGURATION

289

290

CHAPTER 12

Controlling Columbus OM with the dispatch server

Selecting documents using a condition

RULE rule1
DEFINE a(z) "MyPrinterz"
DEFINE b "SALES"
CONDITION %DESTINATION = ?a(1) && %OWNER = ?b
SET DESTINATION "MySalesDepartmentPrinter1"
ADVANCE ReleaseDocument
CONDITION %DESTINATION = ?a(2) && %OWNER = ?b
SET DESTINATION "MySalesDepartmentPrinter2"
ADVANCE ReleaseDocument
RULE ReleaseDocument
CONDITION ALWAYS
SET MEDIUM PRINT
RELEASE

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Specifying the actions


The actions in a rule specify what you want to do with the documents that have
been selected by the condition.
Processing actions
Keyword

Description

BUNDLE

Adds the document to a document bundle

COMMAND

Performs a system command

DAYLOG

Adds a message to the dispatch servers log file

ENFORCE

Applies printing properties to the document

PRINT

Prints the document

SET

Changes the value of one of the entrys properties

Final actions
Keyword

Description

COMPLETE

Sets the entrys status to Completed, and then moves it to the


completed queue

DEFER

Postpones the entry until a specific time and date

FAIL

Sets the entrys status to Failed, and then moves it to the


completed queue

HOLD

Sets the entrys status to Held, until manually released

RELEASE

Releases the entry for further processing

Flow control actions


Keyword

Description

ADVANCE

Moves to another rule that is further down the rules file

NEXT

Stops processing the current rule, and then starts the next rule in
the file

STOP

Stops processing all rules for the current entry

ADVANCE
The ADVANCE action stops processing the current rule, moves to another rule that is
further down the rules file, and then starts processing that one.
Syntax
ADVANCE rulename

COLUMBUS OM INSTALLATION AND CONFIGURATION

291

292

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Parameter
rulename

The name of another rule in the file.


The name can use substitution variables (see Substitution variables on
page 603).
The substitution variable can be combined with text. For example,
ADVANCE Dept_%OWNER could be used to move to rules that are called
Dept_Accounts, Dept_Sales, and so on.
If there is no rule that matches the name, processing continues with the next
line in the rule.
Example: Applying different actions to a document
In these rules, different conditions apply different actions to a document. Then
Columbus OM advances to a rule that contains actions that are applied to every
document.
This example also shows how to use the SET and RELEASE actions to print a
document.
RULE SelectOwner
CONDITION %OWNER = "john"
SET DESTINATION "MyPrinter1"
ADVANCE ReleaseDocument
CONDITION %OWNER = "mary"
SET DESTINATION "MyPrinter2"
ADVANCE ReleaseDocument
RULE ReleaseDocument
CONDITION ALWAYS
# Change medium so that document is processed again, this time
# by a different server
SET MEDIUM PRINT
RELEASE

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Example: Using substitution variables


These rules process documents differently according to their owner:
RULE SelectOwner
CONDITION always
ADVANCE %OWNER
DAYLOG 999 No rule specified for %OWNER
FAIL
STOP
RULE Accounts

commands to process documents that are owned by Accounts


COMPLETE
STOP
RULE Sales

commands to process documents that are owned by Sales


COMPLETE
STOP

and so on

BUNDLE
The BUNDLE action adds a document to a bundle.
BUNDLE can be used only with documents that are not encrypted.

Syntax
BUNDLE name [DEFER=n] [ALIAS=text] [DESTINATION=text]
[OWNER=text] [SOURCE=text] [range]

Parameters
name

The name of the bundle.


The name can include letters (A Z), numbers (0 9), full stop (period),
underscore, hyphen (minus), plus, and equal sign (. - _ + =). Columbus OM
converts lowercase letters to uppercase letters, and removes characters that are
not allowed.
The maximum length of the name is 32 characters.
The name can include substitution variables (see User variables on page 612).
DEFER=n

Defers processing the bundle for n seconds.


If a bundle is updated, it is deferred for another n seconds.
The default value is 0.

COLUMBUS OM INSTALLATION AND CONFIGURATION

293

294

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

ALIAS=text
DESTINATION=text
OWNER=text
SOURCE=text

Set the alias, destination, owner or source of the bundle to the text specified.
text can include substitution variables.

The default value for DESTINATION is bundle. The default values for ALIAS,
OWNER and SOURCE are the same value as the original queue entry.
range

Specifies whether you want the action to be carried out on the entire document
or only part of it. For more information, see Specifying a range on page 304.
Example
This rule creates a bundle called REPORT1. It adds documents to a bundle called
REPORT1; when five documents have been added to the bundle, it prints them all
at once.
RULE create_bundle
CONDITION %BUNDLED = 0
BUNDLE REPORT1
DAYLOG 700: New bundle: Entry %UID added
CONDITION %BUNDLED > 0
BUNDLE REPORT1
DAYLOG 703 Entry %UID added to bundle
CONDITION %BUNDLED = 5
PRINT MyPrinter
DAYLOG 703 Bundle printed
STOP

Where information about bundles is stored


Information about the bundles that are currently being processed are stored in this
file:
%UNIQDIR%\media\dispatch\bundle.tab

COMMAND
The COMMAND action carries out a system command on the selected document.
Syntax
COMMAND[(code[,code]...)] command [range]

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Parameters
code

Columbus OM assumes that if the exit code from the command is 0, the
command was successful.
If

Specify

the command returns a different exit


code to indicate success

COMMAND(code)

For example: COMMAND(1)

the command returns two or more exit COMMAND(code[,code]...)


codes that indicate success
For example: COMMAND(1,3,5)
The maximum number of exit codes
that you can specify is 10.
you want Columbus OM to regard
any exit code from the command as
indicating success

COMMAND(-)

To find out what the exit code was, use the %EXIT substitution variable.
command

A system command. You can use these variables in the command:


?FILE?

The name of the area description file that is specified by the


range.

?DEST?

The destination for the document.

range

Specifies whether you want the action to be carried out on the entire document
or only part of it. For more information, see Specifying a range on page 304.
Example
COMMAND "uqvar -s newtime %DATE+300s"

This action runs the Columbus OM uqvar command. The uqvar command
sets the Columbus OM user variable called newtime to five minutes after the
current time.
COMMAND(1) MyCommand.bat

This action runs a batch file called MyCommand.bat. If the exit code is 1,
Columbus OM assumes that the batch file completed successfully. If the exit
code is anything else, Columbus OM assumes that the batch file failed.
DAYLOG 700 Entry %UID: About to run MyCommand.
COMMAND "MyCommand"
CONDITION %EXIT!=0
DAYLOG 700 MyCommand failed for entry %UID.
COMMAND xmessage %OWNER "Your entry %UID: MyCommand failed"
COMMAND "syq -tn dispatch"

COLUMBUS OM INSTALLATION AND CONFIGURATION

295

296

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

This example runs a command. If the command fails, Columbus OM writes a


message in the day log, sends a pop-up message to the owner, and stops the
dispatch server.

COMPLETE
The COMPLETE action completes an entry. Columbus OM transfers the entry from
the pending queue to the completed queue, and sets its status to Completed.
Syntax
COMPLETE [text]

Parameter
text

Text to be added:

as the entrys Current Status Remark value, and

to the dispatch servers day log file.

The text can include substitution variables (see page 603).

DAYLOG
The DAYLOG action adds a message to the dispatch servers day log file.
Syntax
DAYLOG number text

Parameters
number

A number to identify the message.


text

The text to be added to the dispatch servers day log file.


Example
DAYLOG 700 Entry %UID about to run MyCommand...
COMMAND "MyCommand"

This example adds a message to the servers log file, and then runs a command. If
the command fails, you can look in the log file to see how far the rule reached.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

DEFER
The DEFER action postpones an entry either for a specific period or until a specific
date and time.
Syntax
To defer an entry

Use

for a period

DEFER +period ["text"]

until a specific time

DEFER time ["text"]

until a specific time and date

DEFER time date ["text"]

Parameters
period

A number of days, hours and minutes, in this format: [dd.]hh:mm

dd is the number of days. This is optional. If you include it, separate it from
the number of hours by using a period (dot or full stop).
hh is the number of hours. Separate it from the number of minutes by using

a colon.

mm is the number of minutes.

time

A time. Use the 24-hour clock and this format: hh:mm:ss.


date

The date, by using this format: dd Mon yy

dd is the day number (from 01 to 31).

Mon is month (the first three letters of its name: JAN, FEB, MAR and so on).

yy is the year (the last two digits: 10, 11, 12 and so on).

text

Text to be put in the entrys Remark property.


The text can include substitution variables (see Substitution variables on
page 603).
Example DEFER statements
DEFER +0:00:30

Defers for thirty seconds.


DEFER +0:10

Defers for ten minutes.


DEFER +2:30

Defers for two hours and thirty minutes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

297

298

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

DEFER +7.00:00

Defers for seven days.


DEFER 14:00

Defers until 1400 hours. (If the time is already past 1400 hours today, then the
entry will be deferred until 1400 hours tomorrow.)
DEFER 14:00 31 JAN 12

Defers until 1400 on 31 January, 2012.


Example rules using DEFER
This rule postpones a document if it is sent to laser1.
RULE test_defer1
CONDITION %DESTINATION="laser1"
DEFER 12:30 31 Jan 12

This rule controls the progress of a bundling task which builds a bundle report1
using six source documents. Each time the task is processed, the %BUNDLED variable
is set to the number of documents that are in the bundle. While the number is less
than six, the task is deferred by ten minutes to retain it in the queue.
RULE test_defer2
CONDITION (%DOCUMENT="report1") && (%BUNDLED<6)
DEFER +0:10

ENFORCE
The ENFORCE action applies printing properties to the document, overriding those
set by the user. You can force the document to be single-sided or double-sided, or
in colour or black-and-white, and you can set the n-up number and the
resolution.
Usage
To use ENFORCE on a document, the document must be in either PCL or PJL
format, and it must be copied to the Columbus OM queue.
ENFORCE can be used only with documents that are not encrypted.

Syntax
Use one or more of these commands:
To

Use

print the document single-sided

ENFORCE PCL_PLEX SIMPLEX

print the document double-sided

ENFORCE PCL_PLEX DUPLEX

print the document in colour

ENFORCE PJL_COLOURMODE COLOUR

print the document in black-and-white

ENFORCE PJL_COLOURMODE MONO

print the document in draft quality

ENFORCE PJL_TONER_SAVING YES

print the document in high quality

ENFORCE PJL_TONER_SAVING NO

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

To

Use

set the n-up number

ENFORCE PJL_NUP number

set the dpi (dots per inch) resolution

ENFORCE PJL_RESOLUTION number

If you use the COLOURMODE, NUP, RESOLUTION or TONER_SAVING options, you


might need to convert the codes that Columbus OM puts in the file to codes that
are specific to the printer that you use. For more information about printer code
mapping, see Printer code mapping on page 529.

FAIL
The FAIL action sets the status of the entry to Failed, and then moves it from the
pending queue to the completed queue.
Syntax
FAIL "text"

Parameter
text

Displays a message. Use this to provide an explanation for why the entry failed.
The text can include substitution variables (see Substitution variables on
page 603).
Example
This rule controls bundle report1 by monitoring the time. When the time reaches
10:00, the entry is stopped.
RULE test_fail
CONDITION (%DOCUMENT="report1") && (%TIME~"10:*")
FAIL "Entry Overrun"

HOLD
The HOLD action sets the entrys status to Held.
Syntax
HOLD "text"

Parameter
text

Displays a message. Use this to provide an explanation for why the entry was
put on hold.
The text can include substitution variables (see Substitution variables on
page 603).

COLUMBUS OM INSTALLATION AND CONFIGURATION

299

300

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Example
This rule checks the remark attribute of an entry. If the remark attribute is set to
hold this entry, the dispatch server holds the entry.
RULE test_hold
CONDITION (%REMARK="hold this entry")
HOLD "Held by user"

When the document is ready to be printed, you can release it by using the Release
command in Columbus OM Explorer, but you must also change the Remark field:
if you do not, then this rule will still affect the document and Columbus OM will
put it on hold again.

NEXT
The NEXT action stops processing the current rule, and then starts processing the
next rule that is in the file.
Syntax
NEXT

Example
For an example using the NEXT action, see Dispatch example: Data
transformations on page 309.

PRINT
The PRINT action prints the selected documents.
To specify the command that is to be used to print the documents, set the dispatch
servers PrintCmd property. For more information, see Configuring a dispatch
server on page 280.
For more control over printing, use the SET and RELEASE actions instead of PRINT
(see SET on page 302 and RELEASE on page 301). For an example of how use
these actions, see ADVANCE on page 291.
PRINT can be used only with documents that are not encrypted.

Syntax
PRINT printer [printer...] [range]

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Parameters
printer

The name of the printer on which you want to print the selected documents.
To

Do this

use two or more printers

Type a list of the printers, separating


their names by using a space
character.

use the same printer that was specified Use %DESTINATION.


by the user
range

Specifies whether you want the action to be carried out on the entire document
or only part of it. For more information, see Specifying a range on page 304.
Example
This rule selects a document called reports and prints it on both the laser1 and
laser2 printers.
RULE test_print1
CONDITION ( %DOCUMENT = reports )
PRINT laser1 laser2 ALL

This rule prints all the pages of a document except the first on the laser1 printer.
RULE test_print2
CONDITION ( %DOCUMENT = reports )
PRINT laser1 PAGES 2-$

RELEASE
The RELEASE action releases an entry so that it can be immediately reprocessed; it
puts the entry back in the pending queue with its status set to New.
This action is usually used after changing the properties of the entry to that is
processed differently this time. To change the properties, use the SET action (see
SET on page 302).
One property that you are likely to have to change is the entrys Medium
property so that is processed by a different server. The original value of the
medium would have been set to indicate that you wanted it to be processed by a
dispatch server. For example, to print the document, change the medium to the one
that is used by printmaster (usually print).
Syntax
RELEASE ["text"]

Parameter
text

Text to be put in the entrys Remark property.

COLUMBUS OM INSTALLATION AND CONFIGURATION

301

302

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

The text can include substitution variables (see Substitution variables on


page 603).
Example
For examples that use the RELEASE action, see:

ADVANCE on page 291

Dispatch example: Processing with multiple servers on page 313.

SET
The SET action sets the value of a property of the entry, for example, to change its
medium or its destination.
Syntax
SET property value

Parameters
property

The property to set (see Properties below).


value

The value to which the property is to be set.


Properties
These are the properties that you can set by using the SET action.
Property

Description

ALIAS_PATH

Full pathname of the document alias

ATTEMPTS

Number of attempts

BANNER

Indicates if a banner pages is required: YES or NO

CHAIN

Chain-after entry id

CHARS

Number of characters in the document

CHILD_FLAG

YES makes the entry a child entry.

COPIES

Number of copies required

DEFER

Defer time

DOC_CODE

Document coding (for example, PostScript or PCL)

DESTINATION

Destination

DOCUMENT_PATH

Full pathname of the document

HOST_NAME

Destination host name

JOBCONTROL

Forced job control parameter

LINES

Number of lines in the document

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Property

Description

MASTER

Sets the number of the entrys master entry.


For example: SET MASTER 1234.

MASTER_FLAG

YES makes the entry a master entry.

MEDIUM

Medium name.
See also Dispatch example: Processing with multiple
servers on page 313.

ORIG_UID

Identical to MASTER (see above).

OWNER

Owner id

PAGES

Number of pages in the document

PAPER

Paper type

PRIORITY

Priority (0 to 9)

PROGRAM

Program id string

REMARK

Remark text

RETAIN_DAYS

Number of days retained in the completed queue

SECLEVEL

Security level: either the number or the description of the


security level.
See also seclev.tab: Security levels on page 372.

SET SECGROUP

Security group.
See also Access to documents by security level on
page 370.

SERVER_INFO

Server information.
Changing this property also changes the values of these
properties: BANNER, COPIES, JOBCONTROL, PAPER,
VIPDEVICE and VIPPROFILE.

STATUS

Job status. One of: STARTING, CONNECTING, SENDING,


HELD, TRANSFERED, PRINTED, BLOCKED.

SUPP_REM

Supplementary remark

VIPDEVICE

VIP output device

VIPPROFILE

VIP profile

XFEROK

1 indicates that a document has been transferred


successfully.

Example
For an example that uses the SET action, see Dispatch example: Testing document
properties on page 310.

COLUMBUS OM INSTALLATION AND CONFIGURATION

303

304

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

STOP
The STOP action stops processing all the rules for the current entry.
Syntax
STOP

Example
For an example that uses the STOP action, see Dispatch example: Data
transformations on page 309.

Specifying a range
For the BUNDLE, PRINT and COMMAND actions, you can include a range that specifies
which part of the document you want the action to be carried out on.
The range can be:

the entire document

specific pages

pages that contain a specific piece of text in a specific place.

To specify

Use

the entire document

ALL

a specific page

PAGES pagenumber

several pages

PAGES pagenumber[,pagenumber]

a range of pages

PAGES startpage-endpage

from a specific page to the end of the


document

PAGES startpage-$

pages that contain specific text in a


specific place

PAGES %CONTENTS(parameters)

a selection that is defined in an area


description file

AREA file:area

See also Testing the contents of


documents on page 287.

See also Area description files on


page 305.

Parameters
startpage

The number of the first page that you want.


endpage

The number of the last page that you want.


$ (dollar sign)

The last page of the document, however long it is.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

file:area

The name of an area description file, and the name of an area in it. For
information about how to create an area description file, see Area description
files on page 305.

Area description
files

If you often use the same range in rules, you can store its definition in a separate
file, and then in the rules, use a reference to that file instead of the range itself. If
you decide to change the condition, you only have to change it once, in the
definition file, instead of every occurrence of it in the rules file.
These definition files are called area description files.
When you have created an area description file, you can refer to it a rule by using
the AREA keyword in the range. For more information, see Specifying a range on
page 304.
To create an area description file
1

In Columbus OM Explorer, click the Advanced tab, and then navigate to


instance Columbus OM Servers.

Click the dispatch server icon, and then click the Edit Area Description File
toolbar button
.

In the Area Description File Editor dialog box, type the name of the file you
want to create or edit.

The area description files are stored in the print instances


\media\dispatch\docs folder.

You can have as many area description files as you need.

Each file can contain any number of area descriptions.

Click OK.
The Area Description File Editor appears.

Edit the text by using the standard Windows text-editing commands.


See Area description syntax below.

When you have finished, click the Save toolbar button


Area Description File Editor.

, and then close the

Area description syntax


MATCH { 0, 0, "" }
AREA name
FROM [offset] { column, line, [page_number,] [!] "match_text" }
[TO [offset] { column, line, [page_number,] [!] "match_text" }]
END

You must include the MATCH { 0, 0, "" } line.


Parameters
name

Identifies the area description. The name must be unique within the area
description file (but areas defined in other files can have the same name).

COLUMBUS OM INSTALLATION AND CONFIGURATION

305

306

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

FROM

Specifies the start of the selection. To start the selection to start on a page
relative to the page selected by the rest of the expression, include the offset
value.
TO

Specifies the end of the selection. To include only a single page, as specified by
the FROM parameter, omit the TO parameter.
expression

An expression that specifies where to look for the text. See below.
Area description expressions
{ column, line, [page_number,] [!] "match_text" }

Parameters
column, line

The position of the text in the page: the number of the column, and the number
of the line.

To search for text at any column on a specified line, set column to zero.

To search for text in any line at a specified column, set line to zero.

To search for text at any column and in any line, set both column and line
to zero. Note, that the text searched for must appear within a single line
that is, it must not be spread over a line-break.

page_number

The number of the page on which to search for the text. To search every page,
omit this parameter.
! (exclamation mark)

Reverse the condition so that the expression selects documents where the
match text does not appear at the specified location.
text

The text to search for. Enclose the text in quotation marks.


The text is case-sensitive. For example, if the text is Feb, Columbus OM does
not match with FEB.
Combining expressions
To combine expressions, use these operators:
Operator

Function

& or &&

AND (both expressions must be true)

| or ||

OR (either expression must be true)

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Specifying the actions

Example area descriptions


This area description selects the first page in a document that has the text Sales
Department at column 24, line 4.
MATCH { 0, 0, "" }
AREA targeta
FROM { 24, 4, "Sales Department" }
END

This area description selects the page before the first page in a document that has the
text Sales Department at column 24, line 4.
MATCH { 0, 0, "" }
AREA targetb
FROM -1 { 24, 4, "Sales Department" }
END

This area description selects a page which contains either the string 1996 or 1997 at
column 24, line 4.
MATCH { 0, 0, "" }
AREA targeta
FROM { 24, 4, "1996" } || { 24, 4, "1997" }
END

This area description selects the first page in a document that has the text Sales
Department anywhere in line 4.
MATCH { 0, 0, "" }
AREA targeta
FROM { 0, 4, "Sales Department" }
END

This area description selects the first page in a document that has the text Sales
Department at column 3 on any line.
MATCH { 0, 0, "" }
AREA targeta
FROM { 3, 0, "Sales Department" }
END

This area description selects the first page in a document that has the text Sales
Department anywhere on the page. The text searched for must appear within a
single line: that is, it must not be spread over a line-break.
MATCH { 0, 0, "" }
AREA targeta
FROM { 0, 0, "Sales Department" }
END

COLUMBUS OM INSTALLATION AND CONFIGURATION

307

308

CHAPTER 12

Controlling Columbus OM with the dispatch server

Monitoring the status of dispatch entries

Monitoring the status of dispatch entries


The final status of a dispatch entry provides a guideline to the last action that was
applied to the entry or how many of the actions in the rules were completed or
failed.
Status

Description

Complete?

More actions succeeded than failed

Completed

Either:

Failed

the last action applied to the entry was


COMPLETE or

all the actions succeeded

Either:

the last action applied to the entry was FAIL or

all the actions failed

Failed?

More actions failed than succeeded

Held

The last action applied to the entry was HOLD

New (with a defer time set)

The last action applied to the entry was DEFER

New (with no defer time set) The last action applied to the entry was RELEASE

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

Example rules using the dispatch server


This section contains some example rules that can be used with the dispatch server.
The structure of these dispatch rules can be adapted to your requirements.

Dispatch example: Data transformations


This example rule for the dispatch server shows how to change the format of
documents before processing them.
This example uses commands that are specific to UNIX operating systems; the
same principles can be used on other operating systems.
Rules
RULE SelectProgram
CONDITION ALWAYS
ADVANCE %PROGRAM
RULE crlf
CONDITION ALWAYS
COMMAND " cat %TEMPFILE | crlf

See note 1

See note 2
> %TEMPFILE.tmp"

CONDITION %EXIT != 0
DAYLOG 700 Entry %UID: crlf transform failed
FAIL crlf transform
STOP
ELSE
COMMAND " mv %TEMPFILE.tmp %TEMPFILE"
SET MEDIUM print
DAYLOG 700 Entry %UID: crlf transform succeeded
RELEASE
STOP
RULE afp2pcl
CONDITION ALWAYS
# commands to handle AFP-to-PCL transformations

See note 3

See note 4

# and so on...

Using these rules


1

Configure a dispatch server to handle entries whose medium is transform.

Add entries to Columbus OM by using a command like this:


apq -df MyFile -at MyPrinter -m transform -pg program
-pg sets the entrys Program property. In this example, it is used to control the
rule that is applied to the entry. Replace program with the name of the
transformation application that you want to use.

Analyzing the rules


1

The first section moves processing to the rule whose name matches the
PROGRAM parameter (-pg) that has been specified for the entry:

COLUMBUS OM INSTALLATION AND CONFIGURATION

309

310

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

RULE SelectProgram
CONDITION ALWAYS
ADVANCE %PROGRAM

In the crlf rule, the condition means that the following actions are always
applied.
CONDITION ALWAYS
COMMAND " cat %TEMPFILE | crlf

> %TEMPFILE.tmp"

The COMMAND action copies the document to temporary file, and then processes
that file by running the crlf application.
3

This section tests the exit code from the crlf application.
CONDITION %EXIT != 0
DAYLOG 700 Entry %UID - crlf transform failed
FAIL crlf transform
STOP
ELSE
COMMAND " mv %TEMPFILE.tmp %TEMPFILE"
SET MEDIUM print
DAYLOG 700 Entry %UID - crlf transform succeeded
RELEASE
STOP

If the exit code is not 0, it indicates that the transformation failed.


Columbus OM adds a message to the dispatch servers day log file, then
sets the status of the entry to Failed. Using FAIL also moves the entry to
the completed queue.

If the exit code is 0, it indicates that the transformation succeeded.


Columbus OM copies the file produced by the crlf application back to
the original file, sets the entrys medium to print, and then releases it for
further processing. Because the medium has been changed, the entry will
now be processed by a different server.

The rest of the file contains rules to handle other transformation applications
that may be used.

Dispatch example: Testing document properties


This example rule for the dispatch server shows how to select a printer according to
the properties of a document.
It finds out how many pages there are in a document, and then selects a printer:

If the document contains more than 20 pages, Columbus OM uses a printer


called HEAVY.

If the document contains 20 pages or less, Columbus OM uses a printer called


LIGHT.

The rule analyzes the document by using the xreqs command. For more
information about this command, see xreqs: Analyzing document requirements
on page 322.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

Rules
RULE select
CONDITION ALWAYS
DAYLOG 700 Entry %UID
COMMAND "xreqs ?FILE? %UID -q -f"
DAYLOG 700 Entry %UID medium is %UQVAR(MEDIUM,)

See note 1

CONDITION %UQVAR(PAGES,) <= 20


SET MEDIUM PRINT
SET DESTINATION LIGHT
SET ATTEMPTS 0
RELEASE
ELSE
SET MEDIUM PRINT
SET DESTINATION HEAVY
SET ATTEMPTS 0
RELEASE

See note 2

Analyzing the rule


1

The actions in the first section are always performed:


CONDITION ALWAYS
DAYLOG 700 Entry %UID
COMMAND "xreqs ?FILE? %UID -q -f"
DAYLOG 700 Entry %UID medium is %UQVAR(MEDIUM,)

The COMMAND action runs the xreqs command. The xreqs command analyzes
the requirements of the document (indicated by ?FILE?), and then records the
requirements in a local variables file (indicated by -f). The name of the
variables file include the entrys id, so that Columbus OM can find it again later
in the rule.
The information in the variables file includes the number of pages, which will
be used later in the rule.
The DAYLOG action writes an entry in the dispatch servers logfile. The entry
includes the MEDIUM value, extracted from the local variables file (indicated by
%UQVAR(MEDIUM,).
2

This section tests the number of pages that are in the document.
CONDITION %UQVAR(PAGES,) <= 20
SET DESTINATION LIGHT
SET MEDIUM PRINT
SET ATTEMPTS 0
RELEASE
ELSE
SET DESTINATION HEAVY
SET MEDIUM PRINT
SET ATTEMPTS 0
RELEASE

If the number of pages is 20 or less, Columbus OM sets its destination to


the LIGHT printer.

If the number of pages is more than 20, Columbus OM sets its destination
to the HEAVY printer.

COLUMBUS OM INSTALLATION AND CONFIGURATION

311

312

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

Then Columbus OM sets the entrys medium to PRINT, and releases it. This
puts the entry back in the pending queue with its status set to New, ready to
be processed by the server that uses the PRINT medium.

Dispatch example: Load balancing


This example rule for the dispatch server selects the most suitable printer for a
document from a pool of printers. It selects a printer by using the xselect
command. For more information about the xselect command, see xselect:
Selecting a suitable printer on page 324.
Rule
RULE balance
CONDITION ALWAYS
COMMAND "xselect %BROWSE_PATH %UID -p devpool.tab -f"
CONDITION %EXIT != 0
COMMAND "xmessage %OWNER ""Entry %UID:%%NLxselect failed"" "
COMMAND "syq -tn MyServer"
STOP
CONDITION %UQVAR(MEDIUM,) != "print"
COMMAND "xmessage %OWNER ""Entry %UID:%%NLNo suitable printer"" "
HOLD
ELSE
SET DESTINATION %UQVAR(NEWDEST,)
SET ATTEMPTS 0
RELEASE
COMMAND "xmessage %OWNER ""Entry %UID:%%NLSent to\
%DESTINATION"""

Analyzing the rule


1

This part of the rule applies to every document:


CONDITION ALWAYS
COMMAND "xselect %BROWSE_PATH %UID -p devpool.tab -f"

The COMMAND action runs the Columbus OM xselect command. The


xselect command selects a suitable printer for the document.
If the xselect command finds a suitable printer, it sets the NEWDEST variable to
the name of the printer, and sets the MEDIUM variable to print. (The xselect
command does this automatically; you do not have to use dispatch rules to do
it.) These variables will be used later in the rule.
2

This section handles error conditions if the xselect command fails:


CONDITION %EXIT != 0
COMMAND "xmessage %OWNER ""Entry %UID:%%NLxselect failed"" "
COMMAND "syq -tn MyServer"
STOP

Columbus OM send a message to the user, stops the dispatch server by using
the syq command, and then stops processing the document.
%%NL splits the message over two lines, like this:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

Entry 54321:
xselect failed
3

The rest of the rule applies if the xselect command succeeds. This condition
tests what the MEDIUM variable has been set to by the xselect command:
CONDITION %EXIT != 0
COMMAND "xmessage %OWNER ""Entry %UID:%%NLxselect failed"" "
COMMAND "syq -tn MyServer"
STOP

If the value is not print, it indicates that the xselect command could not find
a suitable printer to print the document. Columbus OM puts the document on
hold.
4

This section applies if the MEDIUM variable is print, which indicates that the
xselect command found a suitable printer:
ELSE
SET DESTINATION %UQVAR(NEWDEST,)
SET MEDIUM %UQVAR(MEDIUM,)
SET ATTEMPTS 0
RELEASE
COMMAND "xmessage %OWNER ""Entry %UID:%%NLSent to\
%DESTINATION"""

Columbus OM sets the destination and medium for the entry to the values that
the xselect command put in the NEWDEST variable (that is, the printer it
selected) and MEDIUM variable (which is PRINT). It sets the entrys number of
attempts back to 0, and then releases the entry for processing again. This time it
will be processed by the server that uses the PRINT medium, which is usually
printmaster.

Dispatch example: Processing with multiple servers


This example show how to process an entry with multiple servers by using the
dispatch features.
This example uses the Completion_Medium parameter. For more information
about this parameter, see Processing entries with multiple servers on page 111.
Rules
# Initialization and error handling
RULE Process_Job_Ticket
CONDITION %PROGRAM = ""
ADVANCE unknown
CONDITION %PREV_STATUS = Failed
DAYLOG 100 %UID: failed at start of %PROGRAM
FAIL
STOP
ELSE
ADVANCE %PROGRAM
NEXT
# Default rule: Used for entries with no "Program" set
RULE unknown

COLUMBUS OM INSTALLATION AND CONFIGURATION

313

314

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

CONDITION always
SET MEDIUM print
SET PROGRAM complete
RELEASE
STOP
RULE complete
CONDITION always
COMPLETE
STOP
# Job ticket A: Print, fax, archive, and then complete
RULE TicketA
CONDITION always
NEXT
# Step 1
RULE TicketA:1
CONDITION always
SET MEDIUM print
SET PROGRAM TicketA:2
RELEASE jt_a:1 %MEDIUM
STOP
# Step 2
RULE TicketA:2
CONDITION always
SET MEDIUM fax
SET PROGRAM TicketA:3
RELEASE jt_a:2 %MEDIUM
STOP
# Step 3
RULE TicketA:3
CONDITION always
SET MEDIUM archive
SET PROGRAM TicketA:4
RELEASE jt_a:2 %MEDIUM
STOP
# Step 4
RULE TicketA:4
CONDITION always
COMPLETE TicketA:4 Finished.
STOP

Using these rules


1

Set the Completion_Medium parameter to dispatch.

Add entries to Columbus OM by using a command like this:


apq MyFile.txt -at MyPrinter -pg TicketA -m dispatch

(-pg sets the entrys Program property. In this example, it is used to control the
rule that is applied to the entry.)
Analyzing these rules
1

First, the dispatch server applies the Process_Job_Ticket rule.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

# Initialization and error handling


RULE Process_Job_Ticket
CONDITION %PROGRAM = ""
ADVANCE unknown
CONDITION %PREV_STATUS = Failed
DAYLOG 100 %UID: failed at start of %PROGRAM
FAIL
STOP
ELSE
ADVANCE %PROGRAM
NEXT

The first two sections handle error conditions:

CONDITION %PROGRAM=""... handles the entry if the Program property is


empty. It moves processing on to the unknown rule, which prints the
document, and then completes it.
CONDITION %PREV_STATUS = Failed... makes sure that the next step

proceeds only if the previous step succeeded.


If the error conditions do not apply, Columbus OM uses this section:

ADVANCE %PROGRAM... moves processing on to the rule that matches the


entrys Program property. If the entry is added by using the apq command

that is shown above, the Program property is TicketA, so processing


moves to the TicketA rule (see note 3 below).
2

The unknown rule applies only if the entrys Program property is blank.
RULE unknown
CONDITION always
SET MEDIUM print
SET PROGRAM complete
RELEASE
STOP
RULE complete
CONDITION always
COMPLETE
STOP

Columbus OM prints the document, and then completes the entry.


3

This rule applies at the start of processing an entry. It moves the processing to
the TicketA:1 rule.
RULE TicketA
CONDITION always
NEXT

The principle of each of the step rules is:

change the entrys Medium to that of the next server that you want to
process it

set the entrys Program property to that of the next rule that you want to
apply to it

release the entry so that it goes back into the Pending queue, ready to be
processed by the next server.

COLUMBUS OM INSTALLATION AND CONFIGURATION

315

316

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

The TicketA:1 rule changes the entrys Medium to print and its Program
property to TicketA:2, and then releases it.
# Step 1
RULE TicketA:1
CONDITION always
SET MEDIUM print
SET PROGRAM TicketA:2
RELEASE TicketA:1 %MEDIUM
STOP

Releasing the entry means that it is now in the queue with its medium set to
print; this means that it is picked up by the printmaster server.
When printmaster has finished processing it, it checks the
Completion_Medium parameter in default.tab. This is set to dispatch, so
printmaster changes the entrys medium to dispatch, its status to New, and
leaves it in the pending queue.
Now the entry is picked up by the dispatch server again, which applies the
entire set of rules again, starting with the Process_Job_Ticket rule.
This time, the ADVANCE %PROGRAM command moves the processing to the
TicketA:3 rule.
5

The rules for steps 2 and 3 work in the same way as the rule for step 1.
# Step 2
RULE TicketA:2
CONDITION always
SET MEDIUM fax
SET PROGRAM TicketA:3
RELEASE TicketA:2 %MEDIUM
STOP
# Step 3
RULE TicketA:3
CONDITION always
SET MEDIUM archive
SET PROGRAM TicketA:4
RELEASE TicketA:3 %MEDIUM
STOP

They change the Medium to that which will be recognized by the next server
that is to process it, change the Program to indicate the next rule that is to
process it, and then release the entry back to the queue.
6

This rule completes the processing of the entry.


# Step 4
RULE TicketA:4
CONDITION always
COMPLETE TicketA:4 Finished.
STOP

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

Dispatch example: Integration with a document composition


service
This section shows how to process master and child entries by integrating the
dispatch features with a document composition service (dcs) application.
These dispatch rules processes the master entry, submits it to the dcs application,
monitors the status of the child entries, and updates the status of the master entry as
appropriate.
Using dispatch to do this is an alternative to using Columbus OMs dcs server.
This example uses the Completion_Medium parameter. For more information
about this parameter, see Processing entries with multiple servers on page 111.
Rules
# Initialization and error handling
RULE Process
# Process the queued request
CONDITION %MASTER_FLAG = Yes
ADVANCE resolve
CONDITION %CHILD_FLAG = Yes & %PREV_STATUS = Failed
FAIL child
STOP
CONDITION %CHILD_FLAG = Yes
COMPLETE child
STOP
ELSE
# Replace the following line with a command to send the entry to your
# document composition service application
COMMAND "aeq %BROWSE_PATH -cp 3 -at %DESTINATION -m print -ou
%UID -child"
SET MASTER_FLAG Yes
RELEASE
STOP
RULE Resolve
# Resolve child statuses
CONDITION %CHILDREN_WAIT = 0 & %CHILDREN_FAIL > 0
FAIL master + %CHILDREN_FAIL children fail %CHILDREN_OKAY OK
STOP
CONDITION %CHILDREN_WAIT = 0
COMPLETE master + %CHILDREN_OKAY children all OK
STOP
ELSE
DEFER +0:00:05 waiting for %CHILDREN_WAIT of %CHILDREN
STOP

Using these rules


1

Set the Completion_Medium parameter to dispatch.

COLUMBUS OM INSTALLATION AND CONFIGURATION

317

318

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

If the master entry might be amended during the processing cycle, set these
parameters:
File

Parameter

Value

system defaults file


(default.tab).

DCS_Medium

The working medium,


usually dispatch.

dispatch servers
configuration file
(%UNIQDIR%\servers

Processed_Delivered

Yes

\dispatch\config.t
ab)
3

Add entries to Columbus OM by using a command like this:


apq MyFile.txt -at MyPrinter -m print

How Columbus OM uses these rules


The "Process" rule handles the entries:

If the entry is new, Columbus OM submits it the dcs application, and marks it
as a master entry.

If the entry is a master entry, Columbus OM checks the status of its children.

If the entry is a child entry, Columbus OM checks whether it succeeded, sets it


status, and then moves it to the completed queue.

This condition checks whether the entry is a master entry.


CONDITION %MASTER_FLAG = Yes
ADVANCE resolve

If the entry is a master entry, Columbus OM moves to the Resolve rule to


check the status of its children. (See note 5 below.)
2

This condition checks whether the entry is a child entry that failed.
CONDITION %CHILD_FLAG = Yes & %PREV_STATUS = Failed
FAIL child
STOP

If it is, Columbus OM sets the entrys status to Failed, moves it to the


completed queue, and then stops processing it.
3

This condition checks whether the entry is a child entry. The previous
condition will have already selected the child entries that failed, so this
condition selects the child entries that did not fail.
CONDITION %CHILD_FLAG = Yes
COMPLETE child
STOP

Columbus OM sets the status of the entry to COMPLETED, moves it to the


completed queue, and then stops processing it.
4

This section affects entries that are neither master entries or child entries, that
is, New entries.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Example rules using the dispatch server

ELSE
COMMAND "aeq %BROWSE_PATH -cp 3 -at %DESTINATION -m print -ou
%UID -child"
SET MASTER_FLAG Yes
RELEASE
STOP

The COMMAND creates the child entries:

To use this rule in your environment, replace the aeq command with a
command that submits the master entry to your dcs application, and
configure the dcs application to submit the child entries that it creates back
to Columbus OM.
To simulate a dcs application for this example, the child entries are created
by using an aeq command to submit copies of the original document. The
-ou parameter connects them with the original entry, and the -child
parameter makes them children of that entry.

SET MASTER_FLAG Yes makes the original entry a master entry.


RELEASE puts the entry back in the queue, ready to be processed again.

The next time that these rules are applied to it, the
CONDITION %MASTER_FLAG... clause will select it, so processing will move to

the Resolve rule.


5

The Resolve rule checks the status of a master entrys children, and then sets
the status of the master entry to match.

This condition is met if none of the child entries are waiting to be processed
(that is, they have all been processed), and one or more has failed:
CONDITION %CHILDREN_WAIT = 0 & %CHILDREN_FAIL > 0
FAIL master + %CHILDREN_FAIL children fail %CHILDREN_OKAY OK
STOP

If this condition has been met, the FAIL clause sets the status of the master
entry to Failed, and then stops processing it.
7

This condition is met if all the children have been processed, and none have
failed. (If any had failed, the previous condition would have applied.)
CONDITION %CHILDREN_WAIT = 0
COMPLETE master + %CHILDREN_OKAY children all OK
STOP

Columbus OM sets the status of the master entry to COMPLETED, and then
stops processing it.
8

This section is reached only if any of the children are still waiting to be
processed.
ELSE
DEFER +0:00:05 waiting for %CHILDREN_WAIT of %CHILDREN
STOP

Columbus OM defers the master entry for 5 seconds. After that, it applies the
rules again.

COLUMBUS OM INSTALLATION AND CONFIGURATION

319

320

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Reference section
dispatch server configuration parameters
Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Action_On_Completion command
Action_On_Failure command
Action_On_Postponement command
Action_On_Shutdown command
Action_On_Start command
Action_Pre_Completion command

Commands to run in response to events. See Operating system actions during


processing on page 417.
Attempts_Limit number

The maximum number of times that you want Columbus OM to attempt to


process a request. If Columbus OM cannot process the request after this
number of attempts, it sets the requests status to Failed and moves it to the
completed queue.
If you want Columbus OM to try only once:

To set the status to Completed if it was successful and Failed if it failed,


set this option to 1.

To set the status to Completed whether it was successful or it failed, set


this option to 0.

The minimum number is 0. The maximum number is 99.


To set the interval between attempts, use the Postpone_Time parameter.
Count_Bundle_Pages No|Yes
Yes counts the pages, lines and characters that are in a bundle when a new
document is added to it, and displays the new total in the queue entrys
properties. If the bundle is large, counting these items might be slow. The page
and line counts are likely to be correct for only plain text files.
No does not count the pages and lines, and sets the number of characters to the

number of bytes that in the file.


The default value is No.
Medium text

See Medium on page 280.


Postpone_Time number

The interval (in seconds) at which you want Columbus OM to try to send the
document again if it fails.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

To set the maximum number of attempts, use the Attempts_Limits


parameter.
The default is 60.
PrintCmd command

See PrintCmd on page 280.


Process_Acks Yes|No
Yes tells the dispatch server to process ACK/NAK queue entries that are sent

from remote hosts. Use Yes only if there is a rule that has been defined to
deal with such entries, and there is not netmaster server able to process them.
No tells the dispatch server to ignore ACK/NAK queue entries. Use this value if
the ACK/NAK mechanism is disabled (see the ACK_Command and
Status_Feedback parameters in the default.tab file), or if netmaster processes

ACK/NAK entries.
The default value is No.
Process_Delivered Yes|No

To enable the dispatch server to process entries whose status is Delivered, set
this parameter to Yes. (These entries are processed in addition to the entries
that the server usually processes, such as New and Waiting.)
This feature is useful when using the dispatch server to process master and
child entries: the status of a master entry changes to Delivered when its child
entries have been added to the pending queue, so this parameter enables the
master entry to be processed by the dispatch server.
Rules_File filename

The path and name of the rules file to be used by the server.
The path can be an absolute path (for example, c:\data\MyRules.tab) or a
relative path (for example, ..\dispatch2\MyRules.tab).

The path can include environment variables (for example,


${UNIQDIR}\MyRules.tab). On both Windows and UNIX, specify the
environment variable by using $ and { } (dollar sign and braces).

If the rules file is in the servers folder, you can omit the path.

To use the default system rules file


(%UNIQDIR%\media\dispatch\rules.tab), leave this parameter blank.
For more information about creating a rules file, see Creating rules on
page 281.
Scan_Interval number

The interval (in seconds) at which the server scans the queue to see if there are
any entries for it to process.
The default is 10.
Server server

The name of the server; this must be the same as the name of the folder that the
configuration file (%UNIQDIR%\servers\server\config.tab) is in.

COLUMBUS OM INSTALLATION AND CONFIGURATION

321

322

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Temp_Path folder

A folder for the temporary files that the server creates. Its capacity must be
bigger than the size of the largest file being submitted. Columbus OM deletes
the temporary files when it has finished using them.
If you do not set this parameter, Columbus OM creates the temporary files in
one of these locations:
Windows

The folder that is specified by the %TEMP% environment variable; if


%TEMP% is not set, then the folder that is specified by the
%UNIQDIR% environment variable.

UNIX

The \tmp folder.

xreqs: Analyzing document requirements


The xreqs command:

analyzes the requirements for a document (for example, its format, whether it is
single-sided or double-sided, and whether it is colour or black-and-white)

counts the number of pages that are to be printed, taking into account the
number of pages in the document, whether the document is single-sided or
double-sided, and how many copies are required.

This command is often used with the dispatch features. For an example, see
Testing the contents of documents on page 287.
Supported document formats
Document formats that are supported by the xreqs command include: AFPDS,
Benson plotter, BMP Bitmap, Canon GL, Epson, GIF, HTML, IDOL, IGP, JPEG,
Microsoft Excel spreadsheet, Microsoft Word, OCE PCL, PDF, plain text, Rich
Text, SAP OTF, SAP RDI, Xerox DJDE, Xerox Metacode, XML, and Zebra ZPL.
Syntax
xreqs [uid] [file] [[-q] [-f [variables_file]]]

Parameters
You can specify the document to be analyzed by using either its entry id or its
name (or both).
uid

The entry id. If you include this parameter, Columbus OM records the results
of the command in a file called %UNIQDIR%\queue\document\xuid.req. uid
has zeroes in front of it to make it 7 characters long, for example:
x0004321.req.
file

The name of the file to be analyzed.


-a <alias>

Uses <alias> instead of <filename> when checking the suffix to the determine
the document type.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

-d

Outputs media totals only.


-f [variables_file]

(Used with the -q parameter.) The variables file in which the variables are to be
stored.
To use

Do this

the standard variables file


(%UNIQDIR%\config\uqvar.tab)

Omit the parameter.

the uqvar.tab file that is in the


current folder

Specify only -f (with no filename).

a specific file in any folder

Specify -f followed by the full path


and name of the file.

-h

Displays more information about using the command.


-q

Stores the requirements in the following Columbus OM variables, in the


variables file that is specified by the -f parameter.
If you do not include this parameter, Columbus OM displays the requirements
onscreen (see Example report on page 324).
Variables
Variable

Value

CHARS

Number of characters that are in the document.


The value takes into account the number of COPIES. For
example, if the document contains 1000 bytes, and COPIES is 2,
CHARS is 2000.

COPIES

Number of copies that have been requested.

DOCTYPE

Document format (for example, PJL or PCL).

APPLICATION

The program the produced the file (for example,


NOTEPAD.EXE).

LINES

Number of lines that are in the document.

TITLE
ORIENTATION

Either PORTRAIT or LANDSCAPE.

PLEX

Either SIMPLEX or DUPLEX.

COLOURMODE

Either COLOUR or MONOCHROME.

SHEETS

The number of sheets of paper that the document requires. For


example, if a 10-page document is printed double-sided, the
number of sheets is 5.

COLUMBUS OM INSTALLATION AND CONFIGURATION

323

324

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Variable

Value

NUP

The number of images on each page.

URGENCY
MEDIA_SIZE

The paper size, for example A4 or LETTER.

MEDIA_WEIGHT
MEDIA_TYPE
MEDIA_COLOUR

The paper colour.

PAGES

Number of pages that are in the document.


The value takes into account the number of COPIES. For
example, if the document contains 10 pages and COPIES is 2,
PAGES is 20.

Example report
To produce a report like this, omit the -q parameter.
Document type is PCL

( 2)

Job control is PJL

( 1)

REQUIREMENTS for MyReport.pcl


Pages:
Largest page:
Title:
Sender:
Message:
Start message:
Output type:
Copies:
Finishing:
Orientation:
Plex:
Resolution:
Colour mode:

6 (

Print
1

208079 bytes /
34680 bytes

0 records) Sheets:

Recipient:

Defer until: 01/01/1970 00:00

Tot pgs:

Portrait
Simplex
600 dpi
Monochrome

Tot sheets:

Quality: Normal

1 media stock(s) required


Media name Type
Colour
Size
Weight
Used
----------- -------------- --------- --------- ---------- -----<default>
White
A4
<default> 0

xselect: Selecting a suitable printer


The xselect command selects a suitable printer for a document, based on the
properties of the document, and selection criteria that you specify.
Information about the printer that is selected can be stored in Columbus OM
variables and displayed onscreen.
For an example of using this command with the dispatch server, see Dispatch
example: Load balancing on page 312.
Before using this command, see Configuring the xselect command on page 327.
Syntax
xselect [uid] [file]
[-c [selection_file]] [-f [variables_file]]
[-o [sort_file]] [-p [device_pool_file]] [-v] [-z number]

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Parameters
You can specify the file to be analyzed by using either its entry id or its name.
uid

The entry id for the file. If you include this parameter, Columbus OM records
the documents print requirements in a file and creates a report of the device
selection. If you run the command again with the same uid, Columbus OM
gets the results from this report file.
The print requirements file that Columbus OM creates is called:
%UNIQDIR%\queue\document\xuid.req.

The device selection report file that Columbus OM creates is called:


%UNIQDIR%\queue\document\xuid.xlg.
(In the filenames, uid has zeroes in front of it to make it 7 characters long, for
example: x0004321.req and x0004321.xlg.)
file

The name of the document file to be checked.


-c [selection_table]

The file that contains the criteria to be used to select a printer. See Specifying
the selection criteria on page 328.
To use

Do this

the default selection criteria file


(%UNIQDIR%\media\xselect\

Omit the parameter.

select\select_criteria.tab)

a different file that is in the


%UNIQDIR\media\xselect\select

Specify -c followed by the file name


(with no path).

folder
the select_criteria.tab file that is Specify only -c (with no filename).
in the current folder
a specific file in any folder

Specify -c followed by the full path


and name of the file.

all possible selection criteria

Specify -c all

-f [variables_file]

Stores the results of the command in Columbus OM variables. See also


Accessing the information produced by the xselect command on page 330.
To use

Do this

the standard variables file


(%UNIQDIR%\config\uqvar.tab)

Omit the parameter.

the uqvar.tab file that is in the


current folder

Specify only -f (with no filename).

a specific file in any folder

Specify -f followed by the full path


and name of the file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

325

326

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

-o [sort_table]

The file that contains the features to be taken into account when two or more
printers meet the selection criteria. See Selecting from similar devices on
page 329.
To use

Do this

Omit the parameter.


the default sort criteria file
(%UNIQDIR%\media\xselect\sort\
sort_criteria.tab)
a different file that is in the
%UNIQDIR\media\xselect\sort

Specify -o followed by the file name


(with no path).

folder
the sort_criteria.tab file that is in Specify only -o (with no filename).
the current folder
a specific file in any folder

Specify -o followed by the full path


and name of the file.

only the time criteria (that is, choose


fast printers in preference to slow
printers, and ignore cost and quality)

Specify -o time

-p [device_pool_file]

The file that contains the list of possible devices from which Columbus OM can
select one. See Creating a pool of devices on page 327.
To use

Do this

the default device pool file


Omit the parameter.
(%UNIQDIR%\media\xselect\pool\
devpool.tab)
a different file that is in the
%UNIQDIR\media\xselect\pool

Specify -p followed by the file name


(with no path).

folder
the devpool.tab file that is in the
current folder

Specify only -p (with no filename).

a specific file in any folder

Specify -p followed by the full path


and name of the file.

-v

Displays information about the document and the printer that the command
selects.
z number

(Used with Columbus IOP deployments). Specifies the number of a zone. The
printers in the zone are listed in file called:
%UNIQDIR%\media\zones\zonenumber.tab.
This parameter takes precedence over the -p parameter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

To configure the xselect command, you must:


Configuring the
xselect command
specify the devices from which Columbus OM can select

See Creating a pool of devices below.

specify the selection criteria that are to be used


See Specifying the selection criteria on page 328.

specify what device features are most important


See Selecting from similar devices on page 329.

Creating a pool
of devices

The pool of devices is a list of the possible devices from which Columbus OM can
select the one that is most appropriate to print a document.
Columbus OM Explorer
To create the default pool of devices that the xselect command uses, navigate to
Advanced tab instance icon Printers folder View menu Options
XPrinter tab Config Add.
To create other pools, see devpool.tab format below.
devpool.tab format
The default location is the $UNIQDIR\media\xselect\pool folder.
The default file name is devpool.tab.
Different locations and file names can be used and specified when you run the
xselect command.
Entry format
name min_pages max_pages cost quality

The file contains one entry for each printer that you want Columbus OM to
consider.
Field

Value

name

The name of the printer, as set up in Columbus OM.

min_pages

The size (number of pages) of the smallest documents that the


printer accepts.

max_pages

The size (number of pages) of the biggest documents that the


printer accepts.

cost

Average cost per page.

quality

An indicator of the relative print quality that the device


produces. For example, you could set the printers that print the
best quality to 10, average printers to 5, and the lowest quality
printers to 1.

COLUMBUS OM INSTALLATION AND CONFIGURATION

327

328

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Example of devpool.tab
# Min Max Cost
# Printer name Pages Pages per page Quality
# ---------------- --------- --------- --------- --------xerox440 10 0 1 9
npi05ed6c 0 0 0 1

The selection criteria indicate which features you want Columbus OM to consider
Specifying the
selection criteria when selecting an appropriate printer.
Columbus OM Explorer
To create the default list of selection criteria that the xselect command uses,
navigate to Advanced tab instance icon Printers folder View menu
Options XPrinter tab Selection.
To create other pools, see below.
select_criteria.tab file
The default location is the $UNIQDIR\media\xselect\select folder.
The default file name is select_criteria.tab.
Different locations and file names can be used and specified when you run the
xselect command.
Entry format
The file contains one entry for each selection criteria that you want Columbus OM
to consider.
criteria used description
Field

Value

used

Yes or No indicates whether you want Columbus OM to


take into account whether the printer supports it when
deciding whether to use the printer.

Example selection criteria file


# Criteria
# ----------ENABLED
MIN_PAGES
MAX_PAGES
LANGUAGE
BOOKLET
BURSTING
DECOLLATING
COLLATION

Used
---Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes

Description
-------------------------------------"Only printers which are enabled are considered"
"Size of document tested against min for printer"
"Size of document tested against max for printer"
"Printer must support the required language"
"Printer must have a booklet maker"
"Printer must be capable of bursting"
"Printer must be capable of Decollating"
"Printer must be capable of Page Collation"

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

OFFSET
STAPLING
PLEX
IMAGE_SHIFT
RESOLUTION
COLOUR
OUT_BIN
IN_TRAY
MEDIA_NAME
MEDIA_ATTR

Selecting from
similar devices

Yes
No
Yes
Yes
Yes
Yes
Yes
Yes
No
No

"Printer
"Printer
"Printer
"Printer
"Printer
"Printer
"Printer
"Printer
"Printer
"Printer

must
must
must
must
must
must
must
must
must
must

Reference section

be capable of Offset stacking"


be capable of Stapling"
be capable of Simplex/Duplex"
be capable of Image shift"
support required resolution"
support required colour mode"
support named output bin"
support named input tray"
have named media stock loaded"
have defined media stock loaded"

If Columbus OM finds two or more devices in the pool that meet the requirements,
you can tell it how to select a device, based on which device will be fastest, which
device will be cheapest, or which device will produce the best quality.
Columbus OM Explorer
1

To create the default list of properties that the xselect command uses, navigate
to Advanced tab instance icon Printers folder View menu Options
XPrinter tab Sort.

Add TIME, COST, and QUALITY to the Available list in the order that you want
Columbus OM to take them into account. Put the most important feature first.

To create other lists of properties, see below.


sort_criteria.tab file format
The default location is the $UNIQDIR\media\xselect\sort folder.
The default file name is sort_criteria.tab.
Contents
Put TIME, COST, and QUALITY in the order that you want Columbus OM to
take them into account, one per line. Put the most important feature first. If you do
not want a feature to be considered, omit it.
Feature

Description

COST

Average cost per page.


Columbus OM takes this value from the device pool file.

QUALITY

Print quality value.


Columbus OM takes this value from the device pool file.

TIME

How long until the document will be completed.


Columbus OM calculates this by dividing the total number of pages
to be printed (the pages already waiting to print plus the pages that are
in the document) by the rate at which the printer can print them.

COLUMBUS OM INSTALLATION AND CONFIGURATION

329

330

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Examples
If cheap printing is more important than speed, and speed is more important than
quality, specify:
COST
TIME
QUALITY

Alternatively, if producing a high quality document is more important than printing


it cheaply or quickly, specify:
QUALITY
COST
TIME

Accessing the
To
Do this
information
produced by the display the information that is produced Use the -v parameter with the
by the xselect command while it runs command
xselect command
Use the -f parameter with the
put the results of using the xselect
command into Columbus OM variables command
Use the uqvar command (see User
variables on page 612)

access the values of the variables

Columbus OM variables used


If Columbus OM has been able to select a suitable printer, the variables contain
these values:
Variable

Value

JOBCOST

The cost of the job. (Integer value.)

MEDIUM

"print"

NEWDEST

The name of the printer that Columbus OM has selected.

NEWTITLE

The zone in which Columbus OM actually printed the


document; this might be the same as the original zone, which
is shown by TITLE. (Used in Columbus IOP deployments.)

PAGES

The number of pages that are in the document.

REMARK

"printer selected"

(where printer is the name of the printer that


Columbus OM has selected)
TITLE

The original zone in which the user tried to print the


document. (Used in Columbus IOP deployments.)

If Columbus OM cannot select a suitable printer, the variables might contain


different values, depending on the reason:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Variable

Value

JOBCOST

MEDIUM

If the uid parameter was used with the command, this value
is the same as the original medium that was specified for the
entry.
If the uid parameter was not used, this value is "dispatch".

NEWDEST

If the file cannot be analyzed, for example because it contains


invalid PCL, this value is "corrupt".
If the file can be analysed, and the uid parameter was used
with the command, this value is the same as the original
destination that was specified for the entry.
If the file can be analyzed, but the uid parameter was not
used, this value is "dispatch".

PAGES

If this parameter is not set, it indicates that the file cannot be


analyzed, for example, if it contains invalid PCL.

REMARK

One of the following:


"corrupt document" indicates that the file cannot be
analyzed, for example, if it contains invalid PCL.
"No suitable printer available" indicates the file could
be analyzed, but there is no printer suitable to print it.

xselect.tab: Control access to xselect features


The xselect.tab file enables you to control who can use various paper types and
colour printing through the xselect command. You can restrict access to only the
users who are listed in a security file, or to only documents produced by specific
applications.
The xselect.tab file works in addition to the a_printername security files that
control which users can use each printer.
File location and name
%UNIQDIR%\media\xselect\xselect.tab

Structure
The file may contain one or more entries in the following format. Each entry
comprises these lines:
REQUIREMENT {PAPER|COLOUR} [text[,...]]
[SECURITY
filename]
ACTION
{IGNORE|REJECT}
APPLICATIONS {ALLOW|DENY}
[text[,...]]

Parameters
REQUIREMENT {PAPER|COLOUR} [text[,...]]

COLUMBUS OM INSTALLATION AND CONFIGURATION

331

332

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

Specifies a feature (that is, PAPER or COLOUR), and a list of properties of that
feature that are controlled.
For PAPER, the text can be A1, A2, A3, A4, EXECUTIVE, LEDGER, LEGAL,
LETTER, and so on.
For COLOUR, the text can be FULL, HIGHLIGHT, or MONOCHROME.
To list two more properties, separate them by commas. Either do not include
any spaces or put the list in quotation marks, for example: REQUIREMENT
PAPER A1,A2,A3 or REQUIREMENT PAPER "A1, A2, A3".
SECURITY filename

Specifies a security file that lists the users who can use the feature. The files are
in the Columbus OM security folder.

The security file for PAPER is the xsel_paper file.

The security file for COLOUR is the xsel_colour file.

To allow all users to use the feature, omit this line.


ACTION {IGNORE|REJECT}

Specifies what happens if a job requires a feature that the owner is not allowed
to use:
To

Specify

reject the job, and not print it

REJECT

print the job, but not use the feature that is not
allowed

IGNORE

APPLICATIONS {ALLOW|DENY} [text[,...]]

Specifies the applications that are either allowed or not allowed to use the
feature. (All other applications have the opposite rights.) To specify the
applications, use one or more of the following:

a list of the program names, separated by commas. If any of the names


contain spaces, put the list in quotation marks, for example:
APPLICATIONS ALLOW NOTEPAD,WINWORD,EXCEL
APPLICATIONS ALLOW "NOTEPAD,MICROSOFT WORD,EXCEL"

UNKNOWN to indicate documents whose application is not known

* (asterisk) to indicate all applications.

Examples
This example allows documents that are on large sizes of paper to be printed by
only the users who are listed in the xsel_paper file:
REQUIREMENT
SECURITY
ACTION
APPLICATIONS

PAPER
A1,A2,A3,LEDGER
xsel_paper
REJECT
ALLOW
*

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

This example allows only documents that are generated by Microsoft Word to be
printed in full or highlight colour:
REQUIREMENT
ACTION
APPLICATIONS

COLOUR
REJECT
ALLOW

COLUMBUS OM INSTALLATION AND CONFIGURATION

FULL,HIGHLIGHT
WINWORD

333

334

CHAPTER 12

Controlling Columbus OM with the dispatch server

Reference section

COLUMBUS OM INSTALLATION AND CONFIGURATION

335

C H A P T E R 13

Chapter 13

Archiving documents

After a document has been processed by Columbus OM, it is usually deleted.


However, if you want to store the document instead of deleting it, you can do one
of the following:
To

See

move documents to the Columbus OM Maintaining an archive queue of


archive queue
completed entries on page 336
transfer the document to
Columbus DW, Macro 4s data
warehousing application

Transferring documents to
Columbus DW on page 341

transfer the document to another


archive application

Transferring documents to other


archiving applications on page 348

COLUMBUS OM INSTALLATION AND CONFIGURATION

336

CHAPTER 13

Archiving documents

Maintaining an archive queue of completed entries

Maintaining an archive queue of completed entries


You can store completed entries in the Columbus OM archive queue.
Columbus OM moves documents out of the completed queue and into the archive
queue after they have been in the completed queue for a number of days that you
specify. (If you do not use an archive queue, Columbus OM deletes the documents
after the specified period.)
When Columbus OM moves an entry to the archive queue, it gives the entry a new
number.
You can define a maximum of 63 archives for each Columbus OM instance. Only
one archive can be active at once, but you could use different archives for different
uses or periods (for example, Sales archive, an Accounts archive and so on, or a
Week1 archive, a Week2 archive and so on).

Creating an archive queue


To create an archive queue
1

Type the following command, and then follow the onscreen instructions:
uq_mkarchive

In the %UNIQDIR%\menus\def_defaults file, delete the hash sign (#) that is in


front of these parameters:

Auto_Archive

Archive

Archive_Compress

Archive_UnComp.

In the system defaults file (default.tab), set these parameters:


Parameter

Value

Archive

The full path of the folder in which the current archive


is stored.

Auto_Archive

n[NO_JOURNAL|nj]

The number of files that you want moved out of the


completed queue and into the archive queue when the
completed queue is full. An appropriate value is 20% of
the size of the completed queue.
Columbus OM records information about the entries
in this file:
%UNIQDIR%\arch_jnl.MONYY

If you do not want the information records, , unless the


NO_JOURNAL flag is supplied.

Auto_Purge

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 13

Archiving documents

Maintaining an archive queue of completed entries

To compress the archive queue

To save disk space, you can compress the entries that are in the archive queue by
setting the following parameters in the system defaults file (default.tab).
However, if you use this feature, you cannot browse the contents of the documents
that are in the archive queue.
Parameter

Value

Archive_Compress

A command to compress the files.

Archive_Uncomp

A command to restore the compressed files.

The commands specified must accept two arguments: the first is the name of the
uncompressed input file, and the second is the name of the compressed output file
to be written.
To display a list of the archive queues

Type this command:


syq -LIST_ARCHIVES|-la

Displaying the entries that are in the archive queue


Columbus OM Explorer
Navigate to: Documents tab
Customise tab Config.

instance

View menu

Options

Command line
Type this command:
arq [option...]

The archive queue display appears. For information about the commands that you
can use in the archive queue display, see Using the archive queue display on
page 338.
Specifying the options
-ADDRESS_TEXT|-at text

Display entries whose destination starts with text specified, ignoring case.
-ANY_OWNER|-ao

Displays entries belonging to any user. To display only entries that belong to
you, omit this option.
-ARCHIVE|-ar [number]

Display entries from the archive queue with the number specified. To display
entries from the current archive queue, omit this option.
-DUMB|-d

Display entries in plain text without using the escape characters that invoke
advanced terminal capabilities such as reverse video.

COLUMBUS OM INSTALLATION AND CONFIGURATION

337

338

CHAPTER 13

Archiving documents

Maintaining an archive queue of completed entries

-MEDIUM|-m medium [medium]...

Display entries with the media specified.


-NO_PROMPT|-np

Displays the entries, and then exits without prompting for further commands.
Use this option with -DUMB and -SUMMARY to pipe standard output into a file.
-OWNER|-o user

Displays entries that belong to the user specified.


-PROMPT|-p string

Replace the standard command prompt with a string of up to 31 characters,


enclosed in quotation marks "..." if it contains spaces.
-SERVER_TEXT|-st text

Display entries whose product-specific server information includes the text


specified, ignoring case. The values that can be used here include these options:
dispatch entries

none

fax entries

-cs, -ft, -ov, -po

print entries

-b, -co, -dc, -f,-fi, -hp, -nps, -oh, -or, -pp, -pr, -ps,
-pt

-STATUS|-ss status [status] ...

Display entries that have the statuses specified.


-SUMMARY|-s file

Displays the entries in the format specified by file, using the rules defined in
the %UNIQDIR%\config\liqsum.tab file.
-VDUMODE|-v command|OFF

The full path of an operating system command to be used to display text files,
or OFF to display as for a dumb terminal.
-HELP|-h
-NO_BANNER|-nb
-QUEUE_NAME|-qn instance

See Common parameters on page 602.


Using the archive queue display
In the archive queue display, use these commands:
Command

Description

Display the oldest entries on the queue

Redisplay the current page of the queue

Display a help page

L entry_id

Locate the entry_id

Display the next page of the queue

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 13

Archiving documents

Maintaining an archive queue of completed entries

Command

Description

Display the previous page of the queue

Quit from the arq display

Display the newest entries on the queue

entry_id

Display statistics for the entry_id

Controlling the format of the display


The format of the display is defined by the first available of:

a file specified by the -SUMMARY option

%UNIQDIR%\config\arqsum.tab

%UNIQDIR%\config\liqsum.tab

For more information about the structure of these files, see liq: Displaying pending
and completed queue entries on page 250.
If none of these files exists, Columbus OM uses a built-in default definition.

Managing entries that are in the archive queue


Columbus OM automatically moves entries from the completed queue to the
archive queue at the appropriate time. To move entries manually, use one of the
following commands.
Moving entries from the completed queue to the archive queue
syq
syq
syq
syq
syq
syq
syq
syq

-WRITE_ARCHIVE|-wa number
-WRITE_ARCHIVE_APPEND|-waa number
-WRITE_ARCHIVE_OVERWRITE|-wao number
-WRITE_ARCHIVE_NOJOURNAL|-wan number
-WRITE_ARCHIVE_EXACT|-wae number
-WRITE_ARCHIVE_EXACT_APPEND|-waea number
-WRITE_ARCHIVE_EXACT_OVERWRITE|-waeo number
-WRITE_ARCHIVE_EXACT_NOJOURNAL|-waen number

syq
syq
syq
syq
syq
syq
syq
syq

-FORCE_WRITE_ARCHIVE|-fwa number
-FORCE_WRITE_ARCHIVE_APPEND|-fwaa number
-FORCE_WRITE_ARCHIVE_OVERWRITE|-fwao number
-FORCE_WRITE_ARCHIVE_NOJOURNAL|-fwan number
-FORCE_WRITE_ARCHIVE_EXACT|-fwae number
-FORCE_WRITE_ARCHIVE_EXACT_APPEND|-fwaea number
-FORCE_WRITE_ARCHIVE_EXACT_OVERWRITE|-fwaeo number
-FORCE_WRITE_ARCHIVE_EXACT_NOJOURNAL|-fwaen number

Replace number with the age (number of days) of the entries that you want to
move. (If an entrys RETENTATION_DAYS parameter is set to more than this number,
Columbus OM does not move it.)
Columbus OM writes information about which entries it moves in a file called
.\archive.jnl.

COLUMBUS OM INSTALLATION AND CONFIGURATION

339

340

CHAPTER 13

Archiving documents

Maintaining an archive queue of completed entries

To

Use

count n as a period of 24 hours

Use one of the EXACT options.

move the entries when no servers are


accessing the queues

Use one of the -WRITE options

move the entries when servers are


accessing the queues

Use one of the -FORCE_WRITE options

overwrite any existing journal file

Use one of the OVERWRITE options

add the information to the end of any


existing journal file

Use one of the APPEND options

not record the information

Use one of the NOJOURNAL options

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 13

Archiving documents

Transferring documents to Columbus DW

Transferring documents to Columbus DW


For longterm storage of documents, Columbus OM can send documents to a
Columbus DW archive.
Documents are transferred from Columbus OM to Columbus DW by the
Columbus OM crserver server. crserver monitors the Columbus OM pending
queue for entries that are to be archived, and then copies the document file to the
Columbus DW postbox folder. Columbus DW then transfers the document from
the postbox folder to its archive.
Supported document formats
Documents that are being transferred to Columbus DW can be in any format. They
are stored in Columbus DW as associated data.
Index entries for documents
When crserver transfers a document file to the postbox folder, it renames the
document file to include the index values for the document. Columbus DW then
extracts the index values for the document from the file name.

Creating a Columbus DW archive to store documents


This section provides an outline of the steps that are required to create an archive in
Columbus DW to which Columbus OM can transfer documents. For more
information about how to use Columbus DW, see the Columbus DW
documentation.
Planning the archive
Decide what information you want to use to index the documents in the archive,
for example, the owner, the document name, and the date.
To ensure that each document has a unique reference in Columbus DW, include an
index box to store the document UIDs from Columbus OM.
Information about the document that can be used in the index values can be
accessed by using Columbus OM substitution variables and user variables. For
more information about these variables, see Substitution variables on page 603.
Creating and configuring the archive
1

Create a file whose name includes the index shortnames and some example
values. You will use this file later to test the pickup points for the indexes when
you create them.
For example, if you intend to use index boxes called UID, OWN (for the owner),
and DOC (for the document name), you could create a file called
UID=1,OWN=MyUser,DOC=MyReport.txt.
This file simulates the files that crserver transfers from Columbus OM to the
postbox folder.

Using the Columbus CAT Configuration Module, create an archive in which to


store the documents from Columbus DW.

COLUMBUS OM INSTALLATION AND CONFIGURATION

341

342

CHAPTER 13

Archiving documents

Transferring documents to Columbus DW

Make a note of the archives postbox folder; you will use it again later when
you tell Columbus OM where to put the documents that it transfers.
3

Make sure that the user under which Columbus OM runs has full access rights
to the archives postbox folder, so that Columbus OM can transfer the files into
the folder and check their progress.

Create a document type, and set its Data type to Associated.

Create the index boxes for the document type.


Set the pickup points of each index box to Use pre-defined pickup from
filename. Test that the pickup points can extract the index values from the file
names that crserver will create by using the test file that you have created.

Configuring the archive process


Documents that have been transferred to the archives postbox folder can be
transferred to the archive itself by the usual Columbus DW methods. You can
archive the file manually, or more usually, by creating a task that monitors the
postbox folder at regular intervals, and then transfers any files that it finds.
See also Tracking the progress of documents that have been archived on
page 343.

Configuring Columbus OM to integrate with Columbus DW


Configuration parameters for crserver
To configure crserver, you must specify these parameters:
Medium text

The medium that you will apply to documents to indicate that you want them
to be processed by crserver, for example: Archive.
Postbox_Dir folder

The path and name of the postbox folder for the Columbus DW archive that
you want to store the documents in. This is where Columbus OM will put the
documents that are to be archived.
The default value is %UNIQDIR%\media\warehouse\postbox.
Postbox_File shortname=value[,shortname=value]...

The Columbus DW indexes and values under which you want the documents
to be stored. Separate the indexes by using a comma.

shortname is the three-letter short name of a Columbus DW index.

value is the value for the index, usually a substitution variable. For more

information about the substitution variables that are available, see


Substitution variables on page 603.
For example, if the index boxes are UID, OWN (for the owner), and DOC (for
the document name), set this parameter to:
UID=%UID,OWN=%OWNER,DOC=%DOCUMENT

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 13

Archiving documents

Transferring documents to Columbus DW

Columbus OM uses this information in the name of the file that it puts into the
postbox folder. Columbus DW extracts the index boxes and values from the
file name to index it. You must ensure that the file names are unique; the
easiest way to do this is to include the %UID substitution variable as one of the
index values.
For information about the other configuration parameters for crserver, see
crserver: Other configuration parameters on page 344.
Tracking the progress of documents that have been archived
You can control when Columbus OM changes the status of a document that has
been transferred to Completed.
To set the status to Completed
when

Do this

Set Complete_On to POST.


Columbus OM has finished its part of
the processing (that is, it has transferred
the document to the postbox folder)
Set Complete_On to ARCHIVE.
Columbus DW has finished its part of
the processing (that is, it has archived the
Make sure that the Columbus DW
document and deleted the file from the
archive process is configured to delete
postbox folder)
the files from the postbox folder after
archiving them.
For more detailed feedback, do the following:
1

Set these parameters for crserver:


Parameter

Value

Complete_On

Set to FBFILE.
The effect of this is to put two more files in the postbox
folder directory for each document file that is archived.
These files are:

index_string.out: contains Processing,

Success or Failed.

index_string.err: contains No error or an error

message.
index_string is the same as the name of the document

file that Columbus OM creates, containing the values by


which it is indexed.
Clean_PostBox

If the Columbus DW archive task does not delete the


document file from the postbox folder after it has been
archived, set this parameter to Yes.

Postbox_Suffix

Set to a string with leading full stop (period), for example:


.post

In the Columbus DW archive task, do the following:

COLUMBUS OM INSTALLATION AND CONFIGURATION

343

344

CHAPTER 13

Archiving documents

Transferring documents to Columbus DW

Set the Each archive thread runs this batch file every [n] seconds during
archive option to:
m4cxretrv.exe %FullFileName %Activity %ErrorMessage

Set the task to archive only files that have the filename extension that is
specified by the Postbox_Suffix parameter.

Processing and archiving documents in one step


To create more complex workflows, for example to print a document, and then
archive it, use the crserver and dispatch servers together.
Example
This rule for a dispatch server prints each document that you submit to it and puts
a copy of each document in an archive.
CONDITION ALWAYS
PRINT %DESTINATION
SET MEDIUM Archive
RELEASE

PRINT %DESTINATION prints the document on the printer that the user

specified.

SET MEDIUM Archive changes the medium to Archive so that the document
will be recognized by crserver.
RELEASE releases the entry so that it can be processed again. This time it will be
processed by crserver, which submits it to a Columbus DW archive.

For more information about the dispatch server, see Controlling Columbus OM
with the dispatch server on page 279.

crserver: Other configuration parameters


Configuration file
%UNIQDIR%\servers\server_name\config.tab
Configuration parameters
Action_On_Completion command
Action_On_Failure command
Action_On_Shutdown command
Action_On_Start command

Commands to run in response to events. For more information, see Operating


system actions during processing on page 417.
Check_Frequency number

(Used if Complete_On is set to ARCHIVE.) Specifies how often the server is to


check the postbox whether a document has been archived. The number is how
many times the queue should be scanned for new entries between each check
of the postbox folder.
The default value is 12.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 13

Archiving documents

Transferring documents to Columbus DW

For example, if Check_Frequency is set to 12, the server checks the postbox
after every 12 scans of the queue. If Scan_Interval is set to 10, the server
checks the postbox every 12 x 10 seconds = 2 minutes.
Escape_Char character

The escape character to be used in file names to indicate that the following
three characters represent the ASCII code for a character.
Characters might need to be replaced by their ASCII codes if they are
characters that the operating system does allow or that have some other special
meaning to Columbus DW.
The default character is % (percent). You are unlikely to need to change this
character.
Feedback_Fail text
Feedback_Okay text
Feedback_Proc text

These parameters specify the messages that Columbus DW writes in the


feedback file. You are unlikely to need to change these values.
Default
value

Parameter

Message written when

Feedback_Fail

Columbus DW fails to archive the


document

Feedback_Okay

Columbus DW successfully archives Success


the document

Feedback_Processing

While Columbus DW is processing


the document

Failed

Processing

Guard_File filename

If the archiving task in Columbus DW has been configured to proceed only if a


specific file exists, specify the path and name of that file here.
This feature ensures that Columbus DW starts archiving a document only
when the entire document is in the postbox. The server deletes the guard file,
copies the document to the postbox, and then recreates the guard file.
If you set this parameter, do not set Postbox_Temp.
Postbox_Suffix .text

The suffix added to the end of the name of the document files that are put in
the postbox folder.
If you are using file-based feedback (that is, the Complete_On parameter is set
to FBFILE), it might be appropriate to specify a fixed suffix. You can then set
the Columbus DW archive task to archive only files with that suffix, and ignore
the feedback files (which have these suffixes: .out and .err).
To

Do this

add a fixed suffix

Specify the text, preceded by a


full-stop (period), for example: .post

COLUMBUS OM INSTALLATION AND CONFIGURATION

345

346

CHAPTER 13

Archiving documents

Transferring documents to Columbus DW

To

Do this

not add a suffix

Specify NONE

automatically add a suffix identifies


the document type (for example,
.pcl)

Specify AUTO

The default value is AUTO.


Postbox_Temp filename

The path and name of a temporary file to be used to hold the document while
the server copies it to the postbox. This feature ensures that Columbus DW
starts archiving the document only when the entire document is in the postbox.
The server copies the document to the temporary file. When the temporary file
is complete, the server moves it to the postbox folder and renames it, ready for
Columbus DW to start archiving it.
The folder for the temporary file must be different from the postbox folder.
If there are multiple crserver servers, the Postbox_Temp must be different for
each one.
If you set this parameter, do not set Guard_File.
Scan_Interval number

The interval in seconds between successive scans of the queue. The default is
10.
Server text

The server name. This must be the same as the name of the folder that the
servers configuration file (%UNIQDIR%\servers\server\config.tab) is in.
Translate_Chars "character[character]..."

Specifies the characters that are to be replaced by ASCII codes (see


Escape_Char above).
These are the default characters that are replaced:
Name

Character

ASCII code

Backslash

092

Slash

047

Colon

058

Asterisk

042

Question mark

063

Quotation mark

"

034

Less than

<

060

Greater than

>

062

Pipe (vertical bar)

124

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 13

Archiving documents

Transferring documents to Columbus DW

Name

Character

ASCII code

Percent

037

Equals

061

Comma

044

Underscore

095

Period (dot or full stop)

046

The equals, comma, and period characters are translated only when they
appear in an index value. They are not translated when they separate fields in
the filename (see Postbox_File).

COLUMBUS OM INSTALLATION AND CONFIGURATION

347

348

CHAPTER 13

Archiving documents

Transferring documents to other archiving applications

Transferring documents to other archiving


applications
To transfer documents to archiving applications other than Columbus DW,
configure the asp server.
Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Action_On_Completion command
Action_On_Failure command
Action_On_Start command

Commands to run in response to events. For more information, see Operating


system actions during processing on page 417.
Archiver RETRIEVER|FILENET

The name of the archive application. Other applications might require other
formatter-specific parameters in this file.
Attempts_Limit number

The maximum number of attempts to archive a queue entry before setting its
status to Failed. The interval between attempts is set by Postpone_Time.
Directory folder

The full path of a folder which provides an interface between Columbus OM


and the archiving application. The folder can include substitution of
operating system variables ${name} and Columbus OM variables %name.
Columbus OM initiates an action on a queue entry by creating a file
entry_id.cmd specifying the path of a file to be archived; the external
systems response is placed in a file entry_id.out.
Failure_Text string

The string in entry_id.out which denotes that the job has failed. The
default is FAILURE.
Incoming_Allowed YES|NO
YES to process queue entries with the medium specified by Medium; NO (the
default) to ignore such entries.
Leave_CMD YES|NO
YES to retain the command file; NO (the default) to delete the jobs command
file after the number of attempts specified in Attempts_Limit.
Medium ARCHIVE

The medium applied to entries that are to be processed by the server.


Path_Format SHORT|LONG
SHORT removes leading ..\ material from relative file paths specified in
entry_id.cmd; LONG (the default) leaves the paths unchanged.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 13

Archiving documents

Transferring documents to other archiving applications

Postpone_Time number

The interval (in seconds) between attempts to archive a queue entry. If


Attempts_Limit is set to 1, this parameter must be set to 0.
Processing_Text string

The string in entry_id.out which denotes that the job is currently being
processed. The default is PROCESSING.
Scan_Interval number

The interval in seconds between successive scans of the queue. The default is
10.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
Status_Interval number

The interval in minutes between successive checks on job status information in


entry_id.out. The default is 30.
Success_Text string

The string in entry_id.out which denotes that the job has succeeded. The
default is SUCCESS.
Target_System WIN|UNIX
WIN to use Windows end-of-line characters in entry_id.cmd; UNIX (the

default) to use the UNIX newline convention.


UQ_Service uniqcs

The uniqcs service matches an entry in the services file defining the port
(normally 2006) that is used for communication between hosts.

COLUMBUS OM INSTALLATION AND CONFIGURATION

349

350

CHAPTER 13

Archiving documents

Transferring documents to other archiving applications

COLUMBUS OM INSTALLATION AND CONFIGURATION

351

C H A P T E R 14

Chapter 14

Security

To ensure that only authorized users can view and print documents, send faxes and
control the output management features, Columbus OM includes extensive
security features.
Basic system security
The basic system security features cover the requirements of most installations:
Any user that can log on to the computer on which Columbus OM is installed can
print and manage their documents. They can use any printer.
You can control who can access Columbus OM administration features (such as
managing other users documents, enabling printers, adding printers, and changing
the system files) by adding users to user groups; different user groups can access
different features.
Advanced system security
To

See

restrict who can use a printer

Access to printers on page 376

enable groups of users to manage each


others documents

Access to documents on page 369

control who can access documents by


applying security levels such as
Confidential

Access to documents by security level


on page 370

prevent the contents of documents that


are in the queue from being displayed

Encrypting documents on page 374

COLUMBUS OM INSTALLATION AND CONFIGURATION

352

CHAPTER 14

Security

Additional security features


To

See

control which users can unlock


administration functions

Controlling which users can unlock


locked functions on page 380

create your own programs or shell


scripts to check a users id

Access control shell scripts on


page 381

use (or ignore) a Windows domain name Using instances on both Windows and
in mixed-platform environments
UNIX on page 379
create a guest user id

Specifying a guest login on page 379

create and update the Windows user


groups file

Creating and updating the users groups


list file on page 380

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to the Columbus OM instances

Access to the Columbus OM instances


To access a Columbus OM instance from Columbus OM Explorer, a user needs a
user name and password. You can use either:

existing user names and passwords (for Windows, UNIX or SAP R/3)

user names and passwords specific to Columbus OM.

Using existing user names and passwords


To specify how usernames and passwords are to be validated, set the
Login_csuniq parameter in the uqserver configuration file
(%UNIQDIR%\servers\uqserver\config.tab).
To

Set Login_csuniq to

to use existing Windows or


csulin
UNIX usernames and passwords
If the computer is in a workgroup (not a
domain), but you want the user to be accepted
only if they are in a specific domain, use:
csulin -d domain

where domain is the name of the domain that


the user must be in.
attempt automatic logon based
on the Windows username and
password

csulin_al

use SAP R/3 usernames and


passwords

See Using SAP R/3 user ids to log on to


Columbus OM Explorer on page 554

validate users with PAM


(Pluggable Authentication
Management)

csulin_pam

validate users by using an


external program

csulin_external program

This feature is available on HP, Linux and


Solaris.

program is the path and name of the external

program.
When you type your username and password
to access Columbus OM, it sends them to the
external program. It also sends a security
number. The external program must validate
the username and password; if they are valid, it
must send the same security number back to
Columbus OM as confirmation. When
Columbus OM receives the confirmation, it
logs you in.
validate users against an LDAP
system

COLUMBUS OM INSTALLATION AND CONFIGURATION

See To validate users against an LDAP system


below.

353

354

CHAPTER 14

Security

Access to the Columbus OM instances

To validate users against an LDAP system


1

Set uqservers Login_csuniq parameter to:


csulin_ldap [-ssl] [-qn instance]
To

Do this

connect to the LDAP system by using SSL


(Secure Shell Layer)/TSL (Transport Layer
Security mode)

Include the -ssl


parameter.

connect to the LDAP system by using TCP/IP

Omit the -ssl parameter.

specify the Columbus OM instance

Replace instance with

the instance name.


2

Specify the LDAP system by setting these parameters in the system defaults file,
defaults.tab:
Parameter

Value

LDAP_Host

The name of the computer that the LDAP system is on.

LDAP_Port

The port number that the LDAP system uses. If you are
using SSL/TSL authentication, use 636.
The default value is 389.

LDAP_CertPath If you are using SSL/TSL authentication: The full path to the

security certificate.
3

Also in the defaults.tab file, set the LDAP_UserDN parameter. This


parameter specifies how to get the LDAP distinguished name (DN) for a user
id.

If all the DNs have the same format, with only the user id being different,
specify that format. To indicate where the user id appears, use %s, for
example:
sn=%s,cn=Sales,cn=MyCompany

If the DNs can have different formats, specify LIST. Put the list of possible
formats in the LDAPlist.tab file (see LDAPlist.tab: Possible DN formats
on page 355).

If you know the appropriate format of the DN to be used for each user,
specify LOOKUP. Put the list of user ids and their DNs in the
LDAPusers.tab file (see LDAPusers.tab: DN formats for LDAP systems
on page 355).

If the appropriate format of DN for a given user id can be evaluated only


by using an external program, specify COMMAND, followed by the command,
for example:
COMMAND echo sn=%s,cn=Development,cn=MyCompany

Columbus OM replaces %s with the user name; executes the command;


and then logs in by using the commands output.
4

If you are using the LIST or LOOKUP value for the LDAP_UserDN parameter,
create the LDAPusers.tab and LDAPlist.tab files.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to the Columbus OM instances

LDAPlist.tab: Possible DN formats


The LDAPlist.tab file contains a list of DN formats that Columbus OM can use to
validate usernames and passwords that are stored in an LDAP system.
This file is used when the LDAP_UserDN parameter in the system defaults file
(default.tab) is set to LIST. Columbus OM first looks for the user id in the
LDAPusers.tab file (see LDAPusers.tab: DN formats for LDAP systems below).
If the user id is not in that file, Columbus OM tries the DN formats that are in the
LDAPLlist.tab file, until it finds one that works. When it finds a format that
works, it also adds the user id and that format to the LDAPusers.tab file, so that it
can be used next time.
File location
%UNIQDIR%\config\LDAPlist.tab
File format

The file contains a single column of LDAP user DN formats, as shown below.
To show where the user id should be inserted into the format, use %s.
Example
# LDAP User DN
# -----------------------------------sn=%s,cn=MyCompany
sn=%s,cn=Accounts,cn=MyCompany
sn=%s,cn=Admin,cn=MyCompany

LDAPusers.tab: DN formats for LDAP systems


The LDAPusers.tab file contains a list of user ids and DNs (distinguished names) to
be used to validate usernames and passwords that are stored in an LDAP system.
This might be useful if the DNs are in different formats for different users.
This file is used when the LDAP_UserDN parameter in the system defaults file
(default.tab) is set to LIST.
Editing this file

You can add entries to this file manually. If the LDAP_UserDN parameter is set to
LIST, Columbus OM also adds entries that it finds to work.
File location
%UNIQDIR%\config\LDAPusers.tab
Entry format

The file contains one entry for each user id. Each entry contains a user id and the
corresponding format of the DN to be used to validate that user in the LDAP
system.

COLUMBUS OM INSTALLATION AND CONFIGURATION

355

356

CHAPTER 14

Security

Access to the Columbus OM instances

Field

Value

A id with which a user logs in to Columbus OM.


To specify a default DN for all users who do not have an individual entry
in this file, use * (asterisk). You can specify only one of these.

The format of the DN for the user. The format can include %s, which will
be replaced with the user id, for example:
sn=%s,cn=Sales,cn=MyCompany.

Example
# User id
# -------------------user1
user2
*

LDAP User DN
-----------------------------------sn=%s,cn=Sales,cn=MyCompany
sn=%s,cn=Support,cn=MyCompany
sn=%s,cn=MyCompany

In this example, if you log in as user1, Columbus OM uses this LDAP DN:
sn=user1,cn=Sales,cn=MyCompany.
If you log in with a username other than user1 and user2, Columbus OM uses
this LDAP DN format: sn=username,cn=Sales,cn=MyCompany.

Using Columbus OM-specific user names and passwords


You can create usernames and passwords that are specific to Columbus OM by
using the Columbus OM password file.
To use these commands, your username must be in the appropriate security file:
see Security files for editing the system files on page 367.
Configuring passwords for Columbus OM
To

Do this

activate the password file

Set the uqserver Login_csuniq


parameter to csulin_uq.

set a default lifetime for passwords

csupwd -t number
number is the default number of days

that passwords are valid for. The


number must be between 1 and 99.
You can override the default password
lifetime for an individual user when you
add them to the password file.
make passwords last forever

Use this command:


csupwd -t NO

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to the Columbus OM instances

To

Do this

display warning messages before


passwords expire

Use this command:


csupwd -w number
number is the number of days before the
expiry date when you want the warning
message to start appearing. The number
must be between 1 and 99.

not display warning messages before


passwords expire

Use this command:


csupwd -w 0

display the default password lifetime and Use this command:


warning message date
csupwd -c

copy a password file from another


Columbus OM instance

See Using the same password file on


multiple instances below.

Maintaining the passwords


To

Use this command

add a user to the password file

csupwd -u userid [-n password]


[-e expiry] [-i]

display a users expiry date and


password lifetime

csupwd -q userid

display a list of all users

csupwd -l

change a users password

csupwd -u userid
-o oldpassword
-n newpassword

change a users password when you do


not know their current password

csupwd -u userid
-f -n newpassword

change a users password expiry date

csupwd -u userid
-o oldpassword -e expiry

change a users password expiry date


when you do not know their password

csupwd -u userid -e expiry

delete a user from the password file

csupwd -d userid -o password

delete a user from the password file


when you do not know their password

csupwd -d userid -f

Parameter

Value

-u userid

The user id. On Windows, this is case-insensitive; on


UNIX, it is case-sensitive.

-n password

The users new password.

COLUMBUS OM INSTALLATION AND CONFIGURATION

357

358

CHAPTER 14

Security

Access to the Columbus OM instances

Parameter

Value

-o oldpassword

The users current password.

-e expiry

The date when the password expires. See Setting the


expiry date below.

Setting the expiry date


To

Use

specify when the password expires

Specify the date, in one of these formats:


Format

Example

dd Mon [yy]yy

31 Jan 2012

dd/mm/[yy]yy

31/01/2012

ddmm[yy]yy

310112

make the password last for n days

Specify -e +n

make the user specify a new password


the first time that they login

Specify either -e 0 or -i.

make the password last forever

Specify -e NO.

use the default password lifetime

Omit the -e parameter.

For example:
To force the user to change their password

Use

after the first 30 days, and then every 30 days after that -e +30
when they first login, and then every 30 days

-e +30 -i

when they first login, and then at the default interval

-i

Using the same password file on multiple instances


If you have two or more instances of Columbus OM, and you want to use the same
user ids and passwords on all of them, you can maintain the password file on one
instance, and then the other instances can refer to that file. To tell an instance to use
another instances password file, use this command:
csupwd -Redirect instance

Replace instance with the name of the instance which has the main password file.
This command moves the user ids and passwords from the current instances
password file to the specified instances password file. The command succeeds only
if the entries do not clash.
To use this option, your user id must be in the pwd_r security file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to the Columbus OM instances

Testing usernames and passwords


To test whether a username and password are valid for the csulin method that
you are using, do the following:
1

Log on as a regular user.

Type:
$UNIQDIR/programs/commands/command

where command is one of the csulin commands shown above, for example:
$UNIQDIR/programs/commands/csulin_al
3

Type the username, password, and then test, on separate lines, like this:
john
mypassword
test

The program tells you whether the username and password are valid.

COLUMBUS OM INSTALLATION AND CONFIGURATION

359

360

CHAPTER 14

Security

Access to Columbus OM features

Access to Columbus OM features


Access to each Columbus OM feature is controlled by security files. To give a user
access to a feature, add their name to the security file that controls it. For a list of
the security files, see Security files on page 364.
Instead of adding individual users to the security files, it is usually easier to add
users to user groups, and then control which features the user group can access.
You must also control who can access the security files themselves.
Microsoft Windows
To control who can access the Columbus OM security files, set the permissions on
the %UNIQDIR%\security folder (by using its Windows Properties dialog box).
UNIX
To

Do this

enable a user to access the


Columbus OM security files

Make the user a member of the


Columbus OM group.

prevent a user from accessing the


Columbus OM security files

Make sure that the user is in the


Columbus OM group, and not listed as
an additional user in the /etc/group
file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to administration functions

Access to administration functions


All users who can access a Columbus OM instance can use the basic features such
as printing documents and tracking their progress.
To give a user access to the administration functions (for example, enabling and
disabling printers, deleting other users entries and controlling security), add their
username to one of the following user groups:
Group

Members of the group can

operators

Change or delete any entries, including other users entries,


enable and disable printers and fax machines, start and stop
print servers, create and change printer classes.

administrators

Do everything that operators can do, and also view other users
entries, change the size of the queues, and delete all entries from
the queues.

implementors

Use every Columbus OM function. In other words, they can do


everything that administrators can do, and also change the
system defaults, and create and change printers.

Adding a user to a user group also enables them to can view, change and delete
entries made by any other user in the group.
Managing user groups
To

See

change which users are in a user group

Changing which users are in a security


group below

change which features members of a


user group can access

Giving users and user groups access to a


function below

create additional user groups

Creating additional user security


groups on page 363

delete user groups

Deleting a user group on page 364

display the functions that a user can


access

Displaying user access rights on


page 364

Changing which users are in a security group


1

In Columbus OM Explorer, click the Advanced tab, and then click the icon
for the instance that the user group is in.

Under Columbus OM Security, click the type of group to which you want to
add the users:
To add users to

Click

the operators group

Other

Operator Privileges

the administrators group

Other

Administrator Privileges

COLUMBUS OM INSTALLATION AND CONFIGURATION

361

362

CHAPTER 14

Security

Access to administration functions

To add users to

Click

the implementors group

Other

other user groups

User Group, and then the name of


the group

Implementor Privileges

On the Security menu, click Modify.

To add users to the group


1

Under Allow Access to, click Users Named in List.

In the Add User box, type the name of the user.

To

Do this

add a single user

Type their name in the Add User box.

add groups within other groups

Type & (ampersand) and then the


name of the group, for example:
&accounts.

add a Windows user group

Type % (percentage sign), and then the


domain name and group name, for
example: %sales\europe.

add UNIX user groups

Type %, and then the name of the


group, for example: %accounts.

Click Add.

To remove users from the group

Click the user or group in the list at the right, and then click Remove.

Giving users and user groups access to a function


Add each user to the user group that has access to the functions that they need to
use. If you change the access rights for a user group, Columbus OM automatically
changes the access rights for all the users who are in the group.
1

In Columbus OM Explorer, click the Advanced tab, and then click the icon
for the instance that the function is in.

Under Columbus OM Security, click the group that contains the function.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to administration functions

In the Security list, click the function.

On the Security menu, click Modify.

Select the users that users you want to be able to use the function:
To allow access to

Do this

everyone

Select All Users.

no one

Select No Users.

selected users or user


groups

Select Users Named In List.


In the Add User box, type the users id or the
name of the user group. If it is the name of a user
group, type & (ampersand) at the start of the name
(for example, &accounts).
Click Add.

Click OK.

Creating additional user security groups


If the basic user security groups do not give you enough control, you can create
additional security groups.
1

In Columbus OM Explorer, click the Advanced tab, and then click the icon
for the instance.

Click Columbus OM Security.

On the Security menu, click Add Group.

In the Add Group dialog box, select User Group, and then type a name for
the group.

Click OK.

COLUMBUS OM INSTALLATION AND CONFIGURATION

363

364

CHAPTER 14

Security

Access to administration functions

Deleting a user group


1

In Columbus OM Explorer, click the Advanced tab, and then click the icon
for the instance that the user group is in.

Under Columbus OM Security, click User - Group.

Click the user group.

On the Security menu, click Remove Group.

Displaying user access rights


To

Use this command

display a users access rights for


Columbus OM features

uqallowed [username]

display the access rights for the


username that you are logged in as

uqallowed

Security files
File location
The security files are in the %UNIQDIR%\security\ folder.

The implementors, administrators and operators files must exist.


If a g_printer_group, p_printer and a_printer file does not exist, the
feature to which it relates can be used by anyone.
If any of the other access files does not exist, the feature to which it relates can
not be used by anyone.

File content
To enable users to access a feature, add one or more of these entries to the security
file for that feature:
To enable access by

Add

a user

Their user id.

members of a Windows or UNIX user


group

% (percentage sign), and then the name


of the user group. For example:
%BUILTIN\Administrators (on
Windows) or %sales (on UNIX).

members of a Columbus OM user group & (ampersand), and then the name of the
user group. For example, putting
&implementors in a security file gives
access to all users who are listed in the
implementors file.
no users

/No_Users/

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to administration functions

Security files for managing entries


File

Feature

a_printer

Submit jobs to the printer named. It can be either a specific


printer or a printer class.

aeq_mod

Modify entries for any user.

aeq_o

Add entries for other users.

aeq_p0 to aeq_p9 Use queue priorities 0 (lowest) to 9 (highest).


aeq_pc

Delete entries after finishing them (by setting the Retention


days to -1), instead of moving them to the completed queue.

aeq_sl1 to
aeq_sl99

Use security levels 1 (lowest) to 99 (highest). The security


levels are listed in the seclev.tab file.

group_mod

Modify entries belonging to others in their user group.

mod_at

Redirect a pending queue entry.

mod_at_c

Redirect a completed queue entry.

modq_full

Modify all attributes of a print request after submission. Users


without this authority can modify only a restricted subset of the
attributes.

nmhosts_mod

Modify the netmaster hosts table nmhosts.tab.

opq_a

Abort any printout.

opq_a_own

Abort only their own printouts.

opq_c

Cancel any printout.

opq_c_own

Cancel only their own printouts.

opq_n

Notify any paused stream to resume.

opq_n_own

Notify a paused stream to resume only if it is processing their


own entry.

opq_p

Pause any printout.

opq_p_own

Pause only their own printouts.

req_a

Remove archive queue entries.

req_ao

Remove any entries.

req_c

Remove completed queue entries.

req_o

Remove entries belonging to specified other users.

rsq_o

Resubmit entries as their own.

syq_u

Move their own entries from the pending queue to the


completed queue.

syq_u_all

Move any entries from the pending queue to the completed


queue.

syq_wa

Move any completed entries to the archive queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

365

366

CHAPTER 14

Security

Access to administration functions

Security files for displaying the archive queue


File

Feature

arq_ao

List all entries in the archive queue.

arq_det

Display any archive queue entry details.

arq_o

List a specified other users entries in the archive queue.

arq_view

Browse any document in the archive queue.

Security files for displaying the pending and completed queues


File

Feature

liq_ao

List all entries in the pending or completed queues.

liq_ap

List all entries in the pending queue, and their own entries in
the completed queue.

liq_det

Display any pending or completed queue entry details.

liq_g

List entries belonging to other users in their user group.

liq_o

List a specified other users entries in the pending or


completed queues.

liq_view

Browse any document in the pending or completed queues.

liq_view_g

Browse any document belonging to others in their user group.

Security files for managing printer servers


File

Feature

g_printergroup

Display the status of the printers, listed in


%UNIQDIR%\media\groups\printergroup, which are

members of that group.


opq_a

Abort any printout.

opq_a_own

Abort only their own printouts.

opq_c

Cancel any printout.

opq_c_own

Cancel only their own printouts.

opq_d

Disable a printer.

opq_e

Enable a printer.

opq_l

Line up a printer.

opq_m

Add paper to a printer.

opq_s

Split any printout.

opq_s_own

Split only their own printouts.

opq_t

Transfer any printout.

opq_t_own

Transfer only their own printouts.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to administration functions

File

Feature

opq_u

Remove paper from a printer.

opq_v

Change a printer device driver.

p_printer

Control the operation of the printer server named.

paper_mod

Modify paper type definitions.

paper_rem

Remove paper type definitions.

printer_ops

View the Printer Operations display.

ptype_mod

Modify printer types.

ptype_rem

Remove printer types.

wopq_ag

Display printers in any printer group.

Security files for managing other servers


File

Feature

logs_view

View server logs.

opq_i

Add a server to a class.

opq_k

Kill an unresponsive server.

opq_o

Duplicate a server.

opq_x

Remove a server from a class.

server_add

Create a new server.

server_mod

Modify a server.

server_rem

Delete a server.

syq_i

Start a server.

syq_s

View server status.

syq_tn

Stop a server.

uqkill

Force shutdown of Columbus OM server.

Security files for editing the system files


File

Feature

cshosts_mod

Edit the trusted hosts table, cshosts.tab.

lang_b

Build a new language table using langtab.

mod_secdest

Edit the destination security file (secdest.tab).

mod_seclev

Edit the security levels file (seclev.tab).

nmhosts_mod

Edit the netmaster hosts file (nmhosts.tab).

pwd_a

Add new users to the Columbus OM password file (pwd.tab)


using the csupwd command.

COLUMBUS OM INSTALLATION AND CONFIGURATION

367

368

CHAPTER 14

Security

Access to administration functions

File

Feature

pwd_f

Modify entries in the Columbus OM password file (pwd.tab)


without having to know the users existing passwords.

pwd_r

Use the cspwd -redirect command.

pwd_t

Use the csupwd -t command to change the expiry date for


passwords.

pwd_w

Use the csupwd -w command to change when the password


expiry warning messages appear.

remtab_mod

Edit the remote printers table remote.tab and the routes


table route.tab.

remtab_view

View the remote printers table remote.tab and the routes


table route.tab.

syq_dd

Display system defaults.

sysdef_mod

Modify system defaults.

Security files for maintaining the queues


File

Feature

syq_ea

Extend the archive queue.

syq_ec

Extend the completed queue.

syq_ep

Extend the pending queue.

syq_fa

Fix the archive queue.

syq_fc

Fix the completed queue.

syq_fp

Fix the pending queue.

syq_ja

Create a journal of the archive queue.

syq_jc

Create a journal of the completed queue.

syq_jp

Create a journal of the pending queue.

syq_pa

Purge the archive queue.

syq_pc

Purge the completed queue.

syq_pp

Purge the pending queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to documents

Access to documents
This section explains how to control who can view, change and delete documents
that are in the queue.
To

See

enable groups of users to manage each


others documents

Access to documents by group of users


on page 369

apply security levels to documents

Access to documents by security level


on page 370

prevent users from displaying the


Encrypting documents on page 374
contents of a document while it is in the
queue or being transferred

Access to documents by group of users


Users who are members of a user security group can view, change and delete entries
made by any other user in the group. For more information about user security
groups, see Access to administration functions on page 361.
To enable users to view entries made by other users, but change and delete only
their own entries, make them members of teams.
With teams, queue entries which are owned by the team itself are treated as being
owned by any member of that team. This does not apply to entries owned by
individual members of the team, which remain private. Entries owned by individual
members of a user group, which are treated as being owned by any member of the
group.
Team security can be used only from the command line. It cannot be used from
Columbus OM Explorer.
To use teams
1

Set up a user group, and then add the users who are to be in the team to it. See
Access to administration functions on page 361.

Set this parameter in the system defaults file (default.tab):


Team_Working

Yes

Set these access rights. For information about how to do this, see Access to
administration functions on page 361.
Function

Give access to

Add Entry to Queue Functions Add entries for other All users
user
List Queue Entry Functions List all in pending queue the user group
List Queue Entry Functions
4

List all in either queue

the user group

To add an entry as owned by a team, use the apq command with the -o option
set to the team name.

COLUMBUS OM INSTALLATION AND CONFIGURATION

369

370

CHAPTER 14

Security

Access to documents

Access to documents by security level


To control the actions that users can perform on individual documents, apply a
security level to the document when you submit it. For example, the security level
might prevent other users from displaying its contents, changing its properties, or
even seeing that it is in the queue. Different groups of users can be given different
access rights.
Default security levels can be specified to be applied to all documents that are
processed by a specific server or sent to a specific destination.
Configuring the document security feature
1

Specify the security levels (for example, Unrestricted or Confidential), and


what actions are prohibited at each security level, in the security levels file
(seclev.tab).
For more information, see seclev.tab: Security levels below.

Turn on the document security feature: Set the Document_Security


parameter (in default.tab) to specify the maximum security level that can be
used by any user.
To turn off the document security feature, set this parameter to No.

(Optional.) Control which users can use each of the security levels.

(Optional.) Set default security levels to be applied to documents which do not


have a specific security level set when they are submitted.
For more information, see below.

Setting default security levels


You can set default security levels to be applied to documents if they do not have a
security level set when they are submitted.
To set default security levels for

Do this

all documents processed by the


lpdserver, haslerfx or pfax servers

Set the servers Security_Level


parameter in its configuration file.

all documents sent to a specific


destination (for example, a printer)

Add an entry to the destination security


file
(%UNIQDIR%\config\secdest.tab),
and then set the
Destination_Security system
parameter (in default.tab) to Yes.

all documents processed by the instance Set the Security_Level system


parameter in default.tab.
The default level is 0 (that is, no
security).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to documents

Applying security levels to documents


To

See

use the command line (aeq, afq and apq Use the -Security_Level and
commands)
-Security_Group parameters.
For more information, see aeq
command on page 216.
use the lp command

Use the -o parameter. For example:


lp -o"sl1 -sg finance" ...

For the sl parameter, you must the


security levels number, not its
description. There must be no space
between sl and the number.
use the dispatch features

Use the SET action.


For more information, see SET on
page 302.

Precedence for security levels


Columbus OM applies the first security level that it finds in this list:

The security level applied to the document when it is submitted.


Child documents that are submitted by the dcs server have the same security
level as the parent document.

The security level for the server that is processing the document.

The security level for the destination that the document is sent to.

The default security level for the instance, set in the system defaults file
(default.tab).

If none of these values have been set, Columbus OM applies no security level to
the document.
If a user is not allowed to use the security level that Columbus OM calculates, it
applies the maximum level that they are allowed to use.

secdest.tab: Destination security file


The secdest.tab file specifies default security levels to be applied to documents
that do not have a specific security level set.
Location and file name
%UNIQDIR%\config\secdest.tab
Entry format

For each device for which you want to set a default security level like this:
destination level

COLUMBUS OM INSTALLATION AND CONFIGURATION

371

372

CHAPTER 14

Security

Access to documents

Parameter

Value

destination

A printer name, a printer class, a fax number and so on. To


include all destinations that start with the same characters, use *
(asterisk). For example, sales* includes all devices that start with
sales.
If the destination is a printer class, you must also include all the
printers that are in that class as separate entries in the file.

level

The default security level for documents that are sent to the
device. The security levels that you can use are stored in the
%UNIQDIR%\config\seclev.tab file (see seclev.tab: Security
levels below).
To turn off security for a destination, either delete the entry from
this table, or set the level to 0.

seclev.tab: Security levels


Location and file name
%UNIQDIR%\config\seclev.tab
Structure

For each security level, add an entry by using the entry format shown below. The
maximum number of entries is 99.
Each entry specifies a security level, and the actions that members of different user
groups are not allowed to perform on documents with that security level.
Entry format
level description actions actions actions actions
Field

Description

A number, 1 99.
The lowest level of security, usually for documents that all users can access,
is 1. Use as many other levels as you need, up to the highest level of 99.

Text that describes the level, for example: Unclassified or


Confidential. If the description includes spaces, enclose it in quotation
marks. Each level must have a different description.

The rest of the fields list the actions that members of different user groups are not
allowed to do to documents with the security level. Users who are not in any of
these groups cannot perform any actions on documents with the security level.
3

Actions that the members of the documents security group (specified by


using the -sg parameter) are not allowed to do to documents with the
security level.

Actions that operators user group are not allowed to do.

Actions that administrators user group are not allowed to do.

Actions that implementors user group.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to documents

The actions that you can specify are:


Action

Description

ALL

All actions are prohibited.


This action cannot be combined with any other actions.

BROWSE

Display the contents of a document.

DETAIL

Display the properties of a document. For other users, the properties


are displayed blank.

MODIFY

Change the properties of a document, including holding and


releasing the document.
Include this action for every level (except for those set to ALL or
NONE).

NONE

No restrictions; any user can perform any action.


This action cannot be combined with any other actions.

REPRINT

Reprint a document.

SUMMARY

Display a summary of the document. For other users, the document


does not appear in the queue.

To specify an action, use either the full name or the first three characters (for
example, MODIFY or MOD).
To specify multiple actions, separate them by using a comma.
Example security levels file

This file specifies four security levels:


# seclev.tab - Security levels table
#
# Level Name
Group
# ----- ------------ --------------1
Unclassified NONE
2
Restricted
MOD,BRO,REP
3
Confidential MOD,BRO,REP,DET
4
"Top Secret" ALL

Operator
--------------NONE
MOD,REPRINT
MOD,REP,DET
ALL

Administrator
------------NONE
MOD,REP
MOD,REP
ALL

Implementor
----------NONE
NONE
NONE
MOD,BRO,REP

Using this example:

If you apply the lowest security level, Unclassified, to a document, any user
can see it in the queue, change it, display its contents and so on.

If you apply the highest level of security, Top Secret, to a document, only
implementors can see the document in the queue, change it, and reprint it.
Other users cannot see it in the queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

373

374

CHAPTER 14

Security

Access to documents

Encrypting documents
You can store documents in encrypted format when they are on the queue or while
they are being transferred to another computer.

Encrypted documents that are on the queue cannot be browsed.

Encrypted documents that are on the queue cannot be unencrypted by any


user, and the encryption method cannot be changed.

Encrypted documents can be printed only on printers that use the xprinter
driver. (They cannot be printed on printers that use the printer driver.)
Filters cannot be used with encrypted documents.

To enable encryption

Set the following parameters in the system defaults table (default.tab):


Parameter

Value

AEQ_Index

Yes

Use_XReqs

Yes

If these parameters are not set to Yes, you can still encrypt documents by using the
parameters that are described below; however, you will not be able to use the
xselect command to select a printer for the encrypted documents, and
Columbus OM might not be able to count the number of pages that are in the
encrypted documents.
To encrypt a single document while it is in the queue

Add the document to the queue by using the -encrypt parameter with the aeq or
apq command, for example:
aeq -df MyReport.txt -at MyPrinter1 -encrypt
To encrypt all documents while they are in the queue

Set the Disk_Encrypt parameter in the system defaults file (default.tab) to one
of these values:
To

Set Disk_Encrypt to

use 128-bit encryption keys

AES128

use 192-bit encryption keys

AES192

use 256-bit encryption keys

AES256

not encrypt the documents

NO

To override encryption for a single document

If Columbus OM is configured to encrypt all documents (that is, the


Disk_Encrypt parameters is set as described above), you can change the
encryption method that is used for a single document by using the -encrypt
parameter with the aeq or apq command.
For example, to add a document without encrypting it, use:
aeq -df MyReport.txt -at MyPrinter1 -encrypt NO

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to documents

To encrypt all documents while they are transferred to another


computer

To encrypt all documents while they are transferred to another computer, set the
Net_Encrypt system parameter in default.tab to AES128, AES192 or AES192.
If you use this feature, Columbus OM encrypts the document, and then transfers it
across the network. When the document arrives at the new instance:

If the document was encrypted when it was on the original queue,


Columbus OM encrypts it, and then puts it on the new queue.
If the new instances Disk_Encrypt parameter is set, Columbus OM encrypts
the document, and then puts it on the new queue.
If the document was not encrypted on the original queue, and the new
instances Disk_Encrypt parameter is not set, Columbus OM puts the
unencrypted version of the document on the new queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

375

376

CHAPTER 14

Security

Access to printers

Access to printers
By default, a user who can access Columbus OM can use any of the printers that it
controls.
To

See

control who can access a specific printer Using printer security groups below
control access to printers from other
hosts

Controlling access from other hosts in a


distributed printing environment on
page 377

Using printer security groups


To restrict who can access a specific printer, you create printer security groups, and
then add users to the groups that they need to use.
If you use this, you must add every printer to a printer security group.
To create a group for a specific printer
1

In Columbus OM Explorer, click the Advanced tab.

Under the Columbus OM print instance, click the Columbus OM Security


folder.

On the Security menu, click Add Group.

In the Add Group dialog box, click the type of group you want to create.
To control who can

Create this type of group

use a printer to print documents

Use Address group


(Use Address groups can be
used with only a single printer;
they cannot be used with
printer groups.)

list and view the entries of the users in the


group

User Group

display the documents in a printers queue

Printer Group

operate a printer (enable it, disable, mount


paper types and so on)

Control Printer group

Type a name for the group.

Click OK.

To add users to the group, see Access to administration functions on page 361.

If you have created a Printer Group, turn on the printer security feature by
setting the Printer_Secfiles parameter in default.tab to Yes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Access to printers

To create Control Printer security groups automatically


1

Set the Printer_Secfiles parameter in default.tab to Yes.


From now on, Columbus OM automatically creates a printer group for every
printer that you add. If there are any printers already created for which you
want a printer group, you have to create it manually (see above).

To add users to a control printer group, see Access to administration functions


on page 361.

Controlling access from other hosts in a distributed printing


environment
In a distributed printing environment, you can control who can access the printers
that are controlled by the current Columbus OM instance from other
Columbus OM instances. To do this, you maintain a list of authorized users and
hosts in the trusted hosts file (%UNIQDIR%\config\cshosts.tab).
This procedure controls only who can access the printers by using Columbus OM
Explorer. It does not control who can access them by using the Columbus OM
commands on the command line.
To

Do this

allow all users to access the printers from Delete the trusted hosts file.
any other host
allow selected users access to the
printers from selected hosts

Add an entry to the trusted hosts file for


each host or IP address.

Entry format
Each entry must contain two fields:
Field

Value

Either the name or the IP address of the host on from which a


Columbus OM instance may try to access the current instance.
To enable access from all hosts, put * (asterisk) as the host name.

The users who can access Columbus OM from the host. Separate the user
names by using a comma or a space.
To specify all users, put * (asterisk).

Example cshosts.tab file


mars
10.1.4.15
*
jupiter

"root,jls, mab"
"fdd, nrt"
"aen"
"*"

In this example:

root, jls and mab can access the instance from the mars host
fdd and nrt can access the instance from the host which is on the 10.1.4.15
TCP/IP address

COLUMBUS OM INSTALLATION AND CONFIGURATION

377

378

CHAPTER 14

Security

Access to printers

aen can access the instance from any host

any user can access the instance from the jupiter host.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Additional security features

Additional security features


Using instances on both Windows and UNIX
If users might be accessing Columbus OM instances on both Windows and UNIX
hosts, you can specify whether to ignore the domain name part of a Windows user
name when selecting entries to display, by setting the Any_Domain parameter in
the system defaults file (default.tab).
To

Set Any_Domain to

ignore the domain name, and treat domain1\jsmith,


domain2\jsmith, and jsmith as the same user

Yes

treat domain1\jsmith and jsmith as different users

No

Specifying a guest login


To specify a guest user id, whose entries can be seen by any user, including users
who can usually see only their own entries, set the LIQ_Guest parameter in the
system default file (default.tab).

Locking files
To specify how files are locked, to prevent two users from accessing the same file at
the same time, set this parameter in the system defaults file (default.tab):
ULM_Method
To

Set this parameter to

use the extra level of protection on Windows

MUTEXES

use the extra level of protection on UNIX

SEMAPHORES

(Do not use SEMAPHORES on Windows, or MUTEXES on UNIX.)


The default value on Windows is MUTEXES. The default value on UNIX is
SEMAPHORES.
This is in addition to the operating systems file-locking functionality. You are
recommended to use this extra level of protection on all computers; it is
particularly useful on multi-processor computers.

COLUMBUS OM INSTALLATION AND CONFIGURATION

379

380

CHAPTER 14

Security

Additional security features

Controlling which users can unlock locked functions


Some of the administration functions can be accessed by only one user at a time.
When you use one of these functions, Columbus OM locks it so that no one else
can use it, and unlocks it when you have finished using it.
However, if Columbus OM is on a Windows host, and a users computer crashes
while they are using one of the locked functions, the lock remains. To enable the
function to be used, you must unlock it.
To enable a user to unlock a locked function

Add the users name to the %UNIQDIR%\security\lock_u file.


To unlock a locked function
1

Using Columbus OM Explorer, login to the instance that the function is in, as a
user whose name is in the %UNIQDIR%\security\lock_u file.

Try to access the function.


Columbus OM asks if you want to remove the lock.

Click Yes.

Functions which are locked when they are in use

Setting the system parameters

Configuring servers

Printer server and fax server maintenance

Modifying security

Paper types maintenance

Printer types maintenance

Printer classes maintenance

Changing a entry in the pending queue.

Creating and updating the users groups list file


Columbus OM stores the list of Windows groups that a user is in because for some
types of user group (that is, domain local and universal), it can find out if a user
is a member of those groups only when the user is logged in.
Columbus OM creates and updates the list of groups for each user whenever the
information is available, that is:

when a user logs in to Columbus OM Explorer

when it checks a security file that refers to a Windows user group (if it is logged
in as the user whose group membership is being checked).

If the file does not exist or it is out-of-date, Columbus OM can check whether a
user is a member of only the local and global groups; it cannot check whether they
are a member of domain local and universal groups.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Additional security features

Columbus OMs handling of the user group should be transparent. However, if


necessary, you can also update a users groups list file manually. The file for a user
is called: %UNIQDIR%\media\WinGroups\domain\userid.
Command syntax
To

Use this command

list or create the groups file for the


current user

listwingrps -c [-f]

list or create the groups file for an


interactive different domain\user

listwingrps domain\userid -i
[-p password] [-f]

list or create the groups file for a network listwingrps domain\userid -n


[-p password] [-f]
domain\user
list only the local and global groups for a listwingrps domain\userid
user
validate the groups file for a user

listwingrps userid -v

Parameter

Value

domain\userid

The users Windows domain and user name.

-p password

The password for the user.

-f

Creates or updates the users file with the list of groups.

Access control shell scripts


(This feature is available only on UNIX.)
For additional security, you can control access to Columbus OM features by using
your own shell scripts.
1

Find the name of the file that controls access to the function: see Security files
on page 364.

Create a shell script with the same name plus a .scr extension (for example,
aeq_mod.scr). Write the shell script so that it:

accepts the user name as a parameter

returns 0 if the user is allowed to access the function

returns any other value if the user is not allowed to access the function.

Put the shell script in the $UNIQDIR/security directory.

Set the Access_Scripts parameter in the system defaults file (default.tab)


file for the instance to Yes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

381

382

CHAPTER 14

Security

Reference section

Reference section
groupsec.tab: Administration of printer access control
The groupsec.tab file supports administration of access control to Columbus OM
printers.
File location
%UNIQDIR%\security\groupsec.tab

Entry format
The file contains one line for each security-controlled function or command. Each
line contains these fields:
Field

Value

A description of the function, enclosed in quotation marks "...".

The name of the access control file in %UNIQDIR%\security for this


function, listing the users who are authorized to perform the function.

The name of an administration group, one of:


implementors, administrators, or operators

Only users in that group (or a higher one) are authorized to update the list
of users in the access_file.
Notes
1

Columbus OM Explorer checks your user id against the contents of the


implementors, administrators and operators files in
%UNIQDIR%\security to establish your personal level of authorization.

The outcome of that evaluation determines which (if any) of the access_files
in %UNIQDIR%\security you are permitted to update.

The effect of updating an access_file is to change the list of users who are
authorized to perform the function controlled by that access_file.

security.tab: Administration of access control


The security.tab file supports the administration of access control to the basic
Columbus OM functions.
File location and name
%UNIQDIR%\security\security.tab

Content
The file contains one line for each security-controlled function or command. Each
line contains these fields:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Reference section

Field

Description

A description of the function, enclosed in quotes "...".

The name of the access control file in %UNIQDIR%\security for this


function, which lists the users who are authorized to perform the function.

The name of an administration group, one of:


implementors, administrators, operators

Only users in that group (or a higher one) are authorized to update the list
of users in the access file.
Notes
1

Columbus OM Explorer checks your username against the contents of the


implementors, administrators and operators files in
%UNIQDIR%\security to establish your personal level of authorization.

The outcome of that evaluation determines which of the access files in


%UNIQDIR%\security you are permitted to update.

The effect of updating an access file is to change the list of users who are
authorized to perform the function controlled by that access file.

uqserver server: Communication between hosts


The uqserver server enables instances that are on different computers to
communicate with each other. It listens on the TCP/IP port associated with a
network service (normally uniqcs) for incoming messages from other
Columbus OM hosts. Each Columbus OM host computer should run only one
copy of this server, even if there are multiple Columbus OM instances on it.
Configuration file
%UNIQDIR%\servers\server_name\config.tab
Configuration parameters
Local_Host host

The Local_Host parameter indicates the network card to which a server binds.
This parameter is required only if the computer has multiple network cards
(which means that it also has multiple host names).
The value can be:

the computer name, for example: MyServer01

the IP address, for example, 10.0.20.123

0.0.0.0, to bind to any network card that is on the host.

If the Local_Host parameter is omitted, Columbus OM uses the IP address of


the host.
Login_csuniq command

How to validate a users name and passwords when they log in to


Columbus OM Explorer or the Columbus IOP web interface. This parameter
must have the same value as the Login_csuniq parameter for xmlserver.

COLUMBUS OM INSTALLATION AND CONFIGURATION

383

384

CHAPTER 14

Security

Reference section

See Access to Columbus OM features on page 360.


Medium medium

The name of a communications protocol, normally tcp. See also the Service
parameter.
Scan_Interval number

The interval in seconds at which the server suspends its normal listening
function in order to perform any necessary housekeeping. The default is 10.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
Service service

The name of a service, normally uniqcs, which is defined in


%SystemRoot%\system32\drivers\etc\services (Microsoft Windows) or
/etc/services (UNIX), and used in conjunction with the specified Medium to
identify an incoming communications port.

System default parameters


These parameter can be set in the system defaults file, default.tab.
Use_su_id YES|NO

(UNIX only.) NO refers to the original user id (ignoring any change by means of
the su command) when checking an access file.
YES refers to the new user id su has been used.

The default value is NO.


UserID_Case_Sensitive Yes|No

(UNIX only.) No makes usernames case-insensitive; for example, if there are


separate entries belonging to John, john and JOHN, Columbus OM
treats these entries as all belonging to the same user.
The default value is Yes.
Validate_Remote_Owner YES|NO
YES checks whether the owner of a job received from a remote system is
authorised to use the selected printer (that is, they are in the printers security
file). This affects jobs that are received from uqserver or lpdserver.

For example, if Columbus OM is receiving jobs from a SAP system, this


parameter ensures that the security is checked against the job owner that was
set in SAP, not the job submitter (the user running the SAP commands).
The default value is NO.
Validate_UserID YES|NO|csupwd
YES validates user ids that are in the security files as Windows or UNIX logons.
NO perform no validation.
csupwd validates against the Columbus OM password file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 14

Security

Reference section

The default value is YES.


WinLocalGroups YES|NO

(Windows only.) YES searches for user groups specified in security files in both
local and global groups.
NO searches only global groups.

The default value is NO.

COLUMBUS OM INSTALLATION AND CONFIGURATION

385

386

CHAPTER 14

Security

Reference section

COLUMBUS OM INSTALLATION AND CONFIGURATION

387

C H A P T E R 15

Chapter 15

Working with multiple


instances

This section explains how to integrate two or more instances of Columbus OM.
To

See

enable Columbus OM instances to


communicate with each other.

Configuring the network


communications on page 388.

keep Columbus OM instances in step by Copying and deleting files in multiple


automatically copying files when they
instances on page 390.
change, and deleting unwanted files

COLUMBUS OM INSTALLATION AND CONFIGURATION

388

CHAPTER 15

Working with multiple instances

Configuring the network communications

Configuring the network communications


All the components in a Columbus OM system (that is the hosts, the instances and
the PCs on which Columbus OM Explorer is installed) must use the same service
to communicate with each other. The service is usually called uniqcs. For this
service, you must choose a port number. The number that is usually used is 2006,
but you can use any number, as long as it is not already used.
You must specify the same number in the services file on:

every host on which a Columbus OM instance is installed, and

on every PC on which Columbus OM Explorer is installed.

The server that uses the uniqcs service is called uqserver. uqserver is
automatically configured when you install Columbus OM.
Specifying the port number
1

Edit the services file.


Operating
environment

File location

Microsoft Windows host

%SystemRoot%\system32\drivers\etc

PC running Microsoft
Windows

the Windows folder

UNIX

/etc

Add a line like this, if something similar does not already exist:
service

port/tcp

# Columbus OM service

Replace:

service with a name for the Columbus OM service. The usual name is
uniqcs.
port with any port number that is not already being used: the usual
number is 2006.

Add the line anywhere in the file, except as the last line of the file. The usual
place to add the line is so that the port numbers are in order.
For example:
uniqcs
3

2006/tcp

# Columbus OM service

If you have used a name that is not uniqcs for the service, set the UQ_Service
parameter in the system defaults file (default.tab) to the name that you have
used.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Enabling instances to work together

Enabling instances to work together


To enable instances that are on the same computer to work together, add an entry
for each instance to each instances systems.tab file.
File location and name
%UNIQDIR%\systems.tab

Content
Add one entry for each instance, with these fields:
Field

Description

The name of the instance. Each instance on the host must have a different
name. The name can contain letters and numbers. The maximum length
of the name is 10 characters.

The full path of the folder in which the instance has been installed.

YES or NO:
YES : The instance is the same type (that is, PRINT, FAX, MAIL, DISPATCH,
and so on) as the one to which the systems.tab file belongs.
NO indicates a different product.

The type of instance: PRINT, FAX, MAIL, DISPATCH and so on.

Example
# Name
# ---------DISPATCH1
FAX1
PRINT2

Path
-------------------------------------------------C:\ColumbusOM\dispatch1
C:\ColumbusOM\fax1
C:\ColumbusOM\print2

COLUMBUS OM INSTALLATION AND CONFIGURATION

type?
----No
No
Yes

Product
--------DISPATCH
FAX
PRINT

389

390

CHAPTER 15

Working with multiple instances

Copying and deleting files in multiple instances

Copying and deleting files in multiple instances


When you have a Columbus OM system that includes two or more instances, it can
be important to keep the files in step. You can do this by using the repmaster
server. Repmaster can:

copy files that you change from one instance to another, so that you have to
change the files in only one place

clean folders by deleting unwanted files and subfolders.

Using repmaster
The instance that you want to copy the files from is the master instance. On the
master instance, you specify:

a list of the instances that you want to copy files to, and a list of the files that you
want to copy

a list of the folders that you want to be cleaned, and a list of the files and folders
that they are allowed to contain.

You can maintain different lists of files to be copied and folders to be cleaned for
each instance.
The instances that you want to copy the files to and clean folders on are the client
instances. Run repmaster on each client instance. At specified times, repmaster
checks:

if any of the files that you have specified on the master instance have changed,
and if they have, it copies them to the client instance

if any of the folders that you have specified contain files or subfolders that are
not on the list of allowed items, and if so, it deletes those items.

Repmaster works only on files and folders that are in the main Columbus OM
folder, %UNIQDIR%.
Copying files
You can specify which files on the master instance you want repmaster to monitor.
When one of these files is changed, repmaster copies it from the master instance to
the client instance.
Repmaster can copy either the file that is changed, or a file in a different location.
Copying a file from a different location is useful when:

the master instance and the client instance are on different operating systems
(for example, to transfer files from Windows to UNIX, or between different
types of UNIX)

the contents of the file need to be different (for example, the instances might
need different values in the system defaults file, default.tab).

repmaster can also handle file deletions: if a file on the master instance is deleted,
repmaster can also delete the file from the client instance.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Copying and deleting files in multiple instances

Cleaning folders
Repmaster can make sure that folders contain only the files you want, by
automatically deleting unwanted files.
You specify a folder, and a list of the files and subfolders that it is meant to contain.
At specified times, repmaster checks the folders, and then deletes any files and
subfolders that are not on the list. (Repmaster does not delete any files that have
been copied from the master instance, even if they are not on the list of allowed
files.)
You can configure repmaster to check the list of allowed items against either the
master instance or the client instance.

Choosing the master instance


Choose one instance as the master instance; that is, the instance on which you will
maintain the master set of files that will be copied to the client instances.
On this master instance, you specify:

a list of the client instances (see Specifying the client instances on page 391)

a list of the files to be copied to the client instances, and the folders on the client
instances to be cleaned (see Specifying the files and folders on page 392).

Specifying the client instances


To specify the client instances that you want to copy files to, use the
replicate.tab file on the master instance.
In this file, you also indicate whether you want to create different lists of files to be
copied and folders to be cleaned for each client instance, or use the same list for
more than one instance.
replicate.tab location
%UNIQDIR%\media\replicate\tables (on the master instance).

replicate.tab format
replicate.tab contains three columns, like this:
# Hostname
# -------------mars
mars
mars
mars
saturn
jupiter
*
1

Instance
-----------print1
print2
*
*
*
*
*

Identifier
-----------mars1
mars2
mars1,mars2
mars_general
saturn,general
jupiter,general
default

Specify the host and name of an instance, and one or more identifiers for the
instance. You will use the identifier later as part of the name of the file in which
you list the files and folders that you want to be copied and cleaned.

COLUMBUS OM INSTALLATION AND CONFIGURATION

391

392

CHAPTER 15

Working with multiple instances

Copying and deleting files in multiple instances

The maximum length of each identifier is 20 characters. The maximum


number of identifiers on each line is 10. Separate multiple identifiers by using a
comma.
Columbus OM also uses the identifier to create a folder, so the identifier must
conform to the operating systems requirements for folder names.
2

You can use the same list of files and folders for more than one instance:
To

Do this

use the same list for two or more


instances

Specify the same identifier.

use the same list for all the instances on Specify the hostname, set the instance
a host
to * (asterisk), and then specify an
identifier.
use the same list for all other hosts and Set both the hostname and the
instances that are not otherwise
instance to * (asterisk), and then
mentioned in this file
specify an identifier.
Example
Using the file shown above, you would create:

a list called mars1, that contains the files that you want copied to the print1
instance on the mars host

a list called mars2, for the print2 instance on mars

a list called mars_general for all the instances on mars, except print1 and
print2

a list called general for all the instances on both saturn and jupiter, and
also lists called saturn and jupiter, for when you want to apply changes to
only one of those hosts.
a list called default for all other instances on all other hosts.

Specifying the files and folders


For each identifier that you have specified in the replicate.tab file (see
Specifying the client instances on page 391), you must create a list of the files to be
copied and folders to be cleaned on the instances that the identifier refers to.
File location
%UNIQDIR%\media\replicate\tables (on the master instance).

File name
id_identifier.tab.

Replace identifier with the identifier that is specified in the replicate.tab file,
for example, id_mars1.tab or id_general.tab.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Copying and deleting files in multiple instances

File format
1

You can specify default values for the entries in the file that follow, for
example:
DEFAULT CLEAN FILES

For more information, see Specifying default values below.


2

Create a section for each folder, for example:


DIR servers

For more information, see Specifying the folders below.


3

In each folder section, list the files that you want to copy and the files that you
do not want do be deleted by using entries like this:
FETCH servers.tab
FETCH alias.tab
ALLOW myfile.txt

For more information, see Specifying the known files and subfolders on
page 394 and Specifying the files to be copied on page 395.
Example
DIR myfolder CLEAN ALL
FETCH myfile.txt
FETCH myfile2.txt

This example ensures that the myfolder folder contains only copies of
myfile.txt and myfile2.txt, and no other files or subfolders.

Specifying
default values

To specify default values for the rest of the entries in the file, add one or more lines
using the syntax shown below. The default values apply to the entries that follow in
the file, so you can change the default values further down the file by putting more
DEFAULT entries in the appropriate places.
Syntax
DEFAULT CLEAN|ALLOW|WHERE|WHENCE|DELOK value
Parameter

Value

CLEAN|ALLOW|
WHERE|WHENCE|
DELOK

The item for which you want to set the default value. For
more information about the keys and the possible values, see
the sections indicated.
Keyword

See

CLEAN

Deleting unknown files and folders on


page 394.

ALLOW

Specifying the known files and subfolders on


page 394.

WHERE

Specifying the known files and subfolders on


page 394.

COLUMBUS OM INSTALLATION AND CONFIGURATION

393

394

CHAPTER 15

Working with multiple instances

Parameter

Specifying the
folders

Copying and deleting files in multiple instances

Value
WHENCE

Specifying the files to be copied on page 395.

DELOK

Specifying the files to be copied on page 395.

To specify a folder that you want repmaster to get files from or to clean, add a line
like this:
DIR folder
Parameter

Value

folder

The name of the folder within the Columbus OM folder


(%UNIQDIR%). For example, if Columbus OM is installed in
c:\ColumbusOM, specify the c:\ColumbusOM\servers folder
by using: servers.
To specify the Columbus OM folder itself, use . (period or dot).

Example
To copy a file from the Columbus OM servers\printermaster folder, use:
DIR servers\printmaster

Deleting
unknown files
and folders

To delete unknown files and folders from the folder that is specified by the DIR
parameter, include the CLEAN option:
DIR folder [CLEAN FILES|FOLDERS|ALL|NONE]
Parameter

Value

CLEAN FILES

Delete unknown files.

CLEAN FOLDERS

Delete unknown folders.

CLEAN ALL

Delete unknown files and folders.

CLEAN NONE

Do not delete anything. This is the default value.

To specify what the known files and subfolders are, use an ALLOW line (see
Specifying the known files and subfolders on page 394).
Example
To clean the Columbus OM servers\printermaster folder, use one of:
DIR servers\printmaster FILES
DIR servers\printmaster FOLDERS
DIR servers\printmaster ALL

Specifying the
known files and
subfolders

To specify the files and subfolders that are allowed in the folder specified by DIR,
that is, the ones that you do not want to be deleted, add one or more ALLOW lines:
ALLOW name [FILE|FOLDER|ALL [MAIN|ALT|CLIENT]]

Repeat the ALLOW lines as required.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Copying and deleting files in multiple instances

Parameter

Value

name

The name of a file or folder that is allowed. The name can


include wildcard characters ? and *.

FILE|FOLDER|ALL

Defines whether the name is a file or a folder, or both:

MAIN|ALT|CLIENT

FILE

Keep name if it is a file.

FOLDER

Keep name if it is a folder.

ALL

Keep name if it is a file or a folder. This is the


default value.

Specifies where the file or folder must exist to be


considered known:
MAIN

In the Columbus OM folder (%UNIQDIR%) on


the master instance.

ALT

In the alternative location on the master


instance (that is, in
%uniqdir%\media\replicate\files\iden
tifier). See also Using an alternative source

for files on page 396.


CLIENT

In the Columbus OM folder on the client


instance. The corresponding file need not exist
on the master instance.

Example
DIR myfolder CLEAN ALL
ALLOW *.doc

This example ensures that the myfolder folder contains only files with the file
name extension of .doc. All other files and subfolders are deleted.
To specify the files that you want to be copied from the folder specified by the DIR
Specifying the
files to be copied line, add one or more FETCH lines, like this:
FETCH name [TEXT|BIN [MAIN|ALT [YES|NO] [nnnn|COPY|IGNORE]]]]
Parameter

Value

name

The name of a file to be copied. The name can include


wildcard characters (? and *).

TEXT|BIN

The format of the files: TEXT for text format; BIN for binary
format.
The default value is TEXT.

MAIN|ALT

Where the files are copied from:


MAIN

COLUMBUS OM INSTALLATION AND CONFIGURATION

From the Columbus OM folder, or a


subfolder of it.

395

396

CHAPTER 15

Working with multiple instances

Parameter

Copying and deleting files in multiple instances

Value
ALT

From the alternate location (that is,


%UNIQDIR%\media\replicate\files\iden
tifier). See also Using an alternative source

for files on page 396.


The default value is MAIN.
YES|NO

YES deletes the file from the client instance if it is not on the
master instance.

The default value is NO.


nnnn|COPY|IGNORE

How the read/write attributes of the file on the client


instance are to be set:
nnnn

Set the attributes to the specified octal code


(for example, 2775). For more information
about the codes, see the operating system
documentation.

COPY

Set the attributes to match those of the file on


the master instance.

IGNORE

Do not set the attributes.

The default value is IGNORE.

Using an
alternative
source for files

Repmaster usually copies the files from the folder specified in the DIR line to the
same folder on the client instance. However, you can copy the files from a different
folder. For examples of why you might do this, see Copying files on page 390.
To copy the files from a different folder
1

On the master instance, put the source files in this folder, or a subfolder of it:
%uniqdir%\media\replicate\files\identifier

For example, to copy the servers.tab file (which is in the Columbus OM


servers folder) to an instance with identifier of mars1, the alternative location
is:
%UNIQDIR%\media\replicate\files\mars1\servers\servers.tab
2

In the FETCH line in the id_identifier.tab file, use the ALT parameter (see
ALT on page 396).

Example
DIR servers
FETCH servers.tab ALT

This example copies the servers.tab file from the alternative folder on the master
instance to the servers folder on the client instance.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Copying and deleting files in multiple instances

Checking repmasters actions


On the master instance:

Log files for each identifier are stored in this folder:


%uniqdir%\media\replicate\reports\clinnnn.
nnnn is the number of the identifier, as shown in the instances file
(%UNIQDIR%\media\replicat\tables\instances.tab).

For a list of the files copied, see the


%UNIQDIR%\media\replicate\history\histnnnn.tab files.

On the client instances:

Repmasters day log files (%UNIQDIR\servers\repmaster\daynn.log)


contain the information specified by its Report_Level parameter.
For a list of the files copied, see the
%UNIQDIR%\servers\repmaster\history.tab file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

397

398

CHAPTER 15

Working with multiple instances

Communicating with remote instances on different ports

Communicating with remote instances on different


ports
To use different ports to communicate with different remote instances that are on
the same computer as each other, configure the hiserv.tab. This might be
necessary if a single remote computer has instances of both Columbus OM and
Columbus Central listening on different ports: use this file to specify the service
(and therefore the port) that each instance uses.
This differs from the nmhosts.tab file, which specifies a single service to
communicate with all instances on a remote computer (see Configuring individual
remote hosts on page 116).
File location and name
%UNIQDIR%\config\hiserv.tab

Entry format
Add one entry for each remote computer that uses a different service. The format
of each entry is like this:
hostname[:instance]

service

Parameters
hostname[:instance]

The name of a remote computer and instance.

If there is more than one instance on the computer, you must include the
instance name.

service

The name of the service on which the instance listens for messages.
Example
# Host/instance
# ---------------myhost1:print1
myhost1:print2
myhost2:print3
myhost3

Service
---------uniqcs1
uniqcs2
uniqcs3
uniqcs1

This example tells Columbus OM that:

The print1 instance on the myhost1 computer can be reached by using a


service that is called uniqcs1.

The print2 instance on the myhost1 computer uses the uniqcs2 service.

The print3 instance on the myhost2 computer uses the uniqcs3 service.

All instances on the myhost3 computer use the uniqcs1 service.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Accepting users from remote hosts

Accepting users from remote hosts


To enable users to access a Columbus OM instance from a remote host, add an
entry for the remote host to this file:
%UNIQDIR%\config\cshosts.tab

Entry format
Each entry contains two fields:
Field

Description

A remote host: either its name or IP address.

host

One line can contain an asterisk (*) in this field, signifying all other
remote hosts not explicitly mentioned.
2

users

A list of users who are authorized to use Columbus OM from the


remote host. Separate the users by using a comma; enclose the
entire list in quotation marks.
To enable all users on the host to access Columbus OM, specify *
(asterisk).

Example
# Host
# ---hostA
hostB

Users
----"john, mary, pat"
*

This file enables three users on host A to use Columbus OM, and all users on host
B to use it.

COLUMBUS OM INSTALLATION AND CONFIGURATION

399

400

CHAPTER 15

Working with multiple instances

Reference

Reference
System default parameters
These parameters can be set in the system defaults file (default.tab):
Client_Mode CSUNIQ

In a distributed environment, the method by which host computers


communicate. This parameter must be set to CSUNIQ.
Host_Name host[,host,...]

The names of other computers that have a Columbus OM system. An apq


command will try each in turn until successful.
Local_Bind IP_address|hostname

Specifies the network card to be used by servers that listen for connections (for
example, uqserver and lpdserver). This feature might be useful where a one
network card controls intranet connectivity (internal) and another controls
internet (external) connectivity, and enables sites to prevent external users from
accessing the print environment.
You can specify the network card by using either its IP address or hostname.
Local_Host host

In cases where this computer has more than one host name (possibly due to
multiple network connections): the definitive local name as far as this
Columbus OM instance is concerned (so should not be set to 0.0.0.0). The
default is to use the computers operating system name.
No_Login_Data YES|NO
YES prevents the instance in which it is set from requesting system parameter
information when communicating with an instance at or below V3.2.0e; NO (the
default) to allow the instance in which it is set to request system parameter
information when communicating with an instance.

The instance in which it is set to Yes is also be prevented from requesting


system parameter information from any other instances with which it is
communicating: in this situation, some loss of functionality occurs. Whenever
possible therefore, you should retain the default setting and upgrade the
early-version instance.
Service uqnet

Obsolete: superseded by UQ_Service.


UQ_Service uniqcs

The service used for communication between host computers. uniqcs must
match the name of an entry in the services file defining the port (normally
2006).
UQ_Timeout numberA/numberB|off

Timeouts used by uqserver to handle incoming connections from clients.


This parameter has two values, separated by a slashmark, for example:
UQ_Timeout 45/500.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Reference

numberA: Package busy timeout: The maximum time (measured in

seconds) that a package may remain active after returning a reply to the
client. Use this option if packages occasionally stop responding, and need
to be tidied up.
The minimum value is 10. To keep the packages always active (that is,
disable this timeout), specify 0. The default value is 300.

numberB: Client idle timeout: The maximum time (measured in seconds)


that Columbus OM stays connected to a client that is not being used. Use
this option if network connections are unreliable, or to disconnect
Columbus Desktop sessions that are not being used.

The minimum value is 10. To keep connections always open, specify 0.


The default value is 600.
If no timeouts are required, set the value of this parameter to off (that is,
UQ_Timeout off).

repmaster configuration parameters


Configuration file
%UNIQDIR%\servers\servername\config.tab
servername is usually repmaster.

Mandatory parameters
Fetch_Time [hh:mm [, hh:mm]...]

When you want repmaster to contact the master instance to see if any files have
changed. By default, repmaster does this every day at the times specified; to do
this on only specified days, use the Fetch_Days parameter (see below).
The maximum number of times that you can specify is 25.
The default value is not to contact the master instance.
Master_Host text

The name of the computer that the master instance is on.


Master_Instance text

The name of the master instance.


Other parameters
Action_On_Shutdown text

See Operating system actions during processing on page 417.


Dry_Run [Yes|No]

To find out what actions repmaster would take, without actually taking the
actions, set this parameter to Yes. Repmaster puts a report of the actions that it
would take in its day log file.
The default value is No.

COLUMBUS OM INSTALLATION AND CONFIGURATION

401

402

CHAPTER 15

Working with multiple instances

Reference

Fetch_Days number[,number]...

Specifies one or more days of the month on which you want repmaster to
perform its tasks. For example:
To

Set Fetch_Days to

the first day of every month

four times a month

7,14,21,28 (or similar dates)

Specifying 31 performs the task in only months that contain 31 days: for
example, January and March, but not February.
To specify the time on these days at which repmaster performs the task, use the
Fetch_Time parameter.
Fetch_Immediate [Yes|No]

To fetch files or clean folders immediately, instead of waiting until one of the
times specified by Fetch_Time, set this parameter to Yes while repmaster is
running.
Repmaster contacts the master instance, copies the files and cleans the folders
as required, and then sets this parameter back to No.
Fetch_Startup [Yes|No]
Yes makes repmaster contact the master instance when it starts. This is in
addition to the times that are specified by the Fetch_Time parameter.

The default value is No.


Medium text

The name of a medium. You can use any medium, for example: print.
Repmaster does not use the medium, but some other programs expect every
server to have a medium.
Remote_User [text]

A user name to log on to the master instance.


The default value is uniq.
Report_Level [0|1|2|3]

The level of information to report. Columbus OM writes the information in the


servers day log file.
0 records the least information; 3 records the most information.
Level

Description

Minimum information: the start and end of each fetch, any errors
encountered, and the overall result (success or failure).

Same information as 0, plus changes successfully made (files fetched;


permissions changed; files or folders deleted).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 15

Working with multiple instances

Reference

Level

Description

Same information as 1, plus the names of all files replicated and


folders cleaned, even if no change is made.

Same information as 2, plus specifically reports if a file is left


unchanged, or a folder is already clean (so nothing is deleted).

The default value is 1.


Server text

The name of the server, usually repmaster. Once set up, this must not be
changed.
Timeout n

The network timeout (measured in seconds). For no timeout, specify 0.


The default value is 180 (3 minutes).
Wait_Time n

The interval (measured in seconds) at which repmaster checks whether one of


the fetch times has occurred.
The default value is 10.

uqserver server: Communication between hosts


The uqserver server listens on the TCP/IP port associated with a network service
(normally uniqcs) for incoming messages from other Columbus OM hosts.
Usually, a Columbus OM host should run only one copy (irrespective of the
number of instances) for each Columbus OM service used by the host.
Using IPv6 addresses on Windows XP and Windows Server 2003

If you are using Columbus OM on Microsoft Windows XP or Microsoft Windows


Server 2003, and you want to use both IPv4 and IPv6 addresses, you must start two
uqserver processes: one that listens for IPv4 callers, and one that listens for IPv6
callers. This is because these operating systems do not support dual-stack TCP/IP.
Configuration file
%UNIQDIR%\servers\server_name\config.tab
Configuration parameters
Local_Host host

The network card to which a server binds. This parameter is required only if
the computer has multiple network cards (which means that it also has multiple
host names).
The value can be:

the computer name, for example: MyServer01

the IP address, for example, 10.0.20.123

0.0.0.0, to bind to any network card that is on the host.

COLUMBUS OM INSTALLATION AND CONFIGURATION

403

404

CHAPTER 15

Working with multiple instances

Reference

If the Local_Host parameter is omitted, Columbus OM uses the IP address of


the host.
Login_csuniq command

How to validate a users name and passwords when they log in to


Columbus OM Explorer or the Columbus IOP web interface. This parameter
must have the same value as the Login_csuniq parameter for xmlserver.
See Access to Columbus OM features on page 360.
Medium medium

The name of a communications protocol, normally tcp. See also the Service
parameter.
Scan_Interval number

The interval in seconds at which the server suspends its normal listening
function in order to perform any necessary housekeeping. The default is 10.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
Service service

The name of a service, normally uniqcs, which is defined in


%SystemRoot%\system32\drivers\etc\services (Windows) or
/etc/services (UNIX), and used in conjunction with the specified Medium to
identify an incoming communications port.
Timeout number

How long (measured in seconds) uqserver should wait to receive messages


from other components (for example, Columbus OM Explorer). This might be
useful if the network connection is unreliable; it prevents uqserver from
waiting forever.
Operating system

Minimum value

Maximum value

Windows

3600

UNIX

0 (never times out)

600

COLUMBUS OM INSTALLATION AND CONFIGURATION

405

C H A P T E R 16

Chapter 16

Monitoring the system

This section explains the features that you can use to monitor the use of
Columbus OM.
To

See

display the status of printers in


Columbus OM Explorer

Getting status information from


printers on page 406

run operating system commands when


selected events happen

Operating system actions during


processing on page 417

display information about use of printers Log files on page 419


and servers
create a report about the entries that are Writing journal information on
in a queue
page 418
record selected events in logfiles or as
SNMP traps

COLUMBUS OM INSTALLATION AND CONFIGURATION

Recording information about events on


page 421

406

CHAPTER 16

Monitoring the system

Getting status information from printers

Getting status information from printers


Status information is collected from printers by the statserver server. It contacts
each printer at regular intervals and requests status information by running a
command. You can view the status information in Columbus OM Explorer.
Configuring statserver
Statserver is created and configured when you install Columbus OM. Its default
configuration is suitable for most environments.
Configuring printers to return status information
Different printers provide their status information by using different commands.
You specify the command that a printer uses by setting its BackChannel and
Query_Printer parameters. For more information about how to find out the
command to use, see Getting the status information from a printer below.
Displaying the status information
See Displaying the printer status in Columbus OM Explorer on page 412.
Status information from remote printers
For status information from remote printers in a distributed printing environment,
see page 118.
Using status monitoring
To minimize resource usage, turn on printer status monitoring only if you need to
use the information that it provides. To turn it off, stop statserver, and then set
the BackChannel parameter in the system defaults file (default.tab) to OFF.

Getting the status information from a printer


To get status information from a printer, you specify a command that
Columbus OM sends to the printer. Different printers use different commands. To
find out which one to use, see below.
Different printers provide different amounts of information about their status:

Most printers can return a basic, one-line status report (for example, Offline
or Paper Low). To get this information, set the printer servers BackChannel
parameter, and make sure that the BackChannel parameter in the system
defaults file (default.tab) is not set to OFF.)

Some printers can also return a more detailed, multi-line status report. To get
this information, set the printer servers Query_Printer parameter.

If you do not which of these reports your printer can return, you can set both
parameters.
To find out the status information command
1

Find out if the printer supports a printer MIB (Management Information Base).
To do this, see the printers documentation, or see Checking for printer MIB
support on page 407.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Getting status information from printers

If the printer does support a printer MIB, you get the status information from it
by using Columbus OMs uqsnmpinfo command: see Using the printer MIB
to get status information on page 408.
2

If the printer does not support a printer MIB, check the printers
documentation for a command that the manufacturer has supplied.
If there is a command supplied, set the BackChannel and Query_Printer
parameters to its value.

If the printer does not have its own command, you can use one of the other
commands that Columbus OM supplies:
Printer type

Columbus OM command to use

Printers that use a network card

ncrdinfo (see page 409)

Printers that are lpd-enabled

lprinfo (see page 410)

OCE printers

oceinfo (see page 411)

PJL-enabled printers that are set up for pjlinfo (see page 412)
assured delivery by using the pjlout
driver

Checking for
printer MIB
support

Zebra label printers

zplinfo

other printers

kwikinfo (see page 409)

When you have set the printers status information command, start statserver,
and then see Displaying the printer status in Columbus OM Explorer on
page 412.

This section describes how to find out if a printer supports a printer MIB. There are
two types of printer MIB:

the common printer MIB: a standard interface common to printers from


different manufacturers

a private printer MIB: used with printers from a specific manufacturer.

Most printers support either the common printer MIB or a private printer MIB;
some printers support both. If the printer supports both, you can check which
provides the most useful information.
To check if the printer supports the common printer MIB
1

At the command line, type:


uqsnmpinfo printerid

Replace printerid with either the network name of the printer or its IP
address.
If the printer supports the common printer MIB, a response like this appears:

COLUMBUS OM INSTALLATION AND CONFIGURATION

407

408

CHAPTER 16

Monitoring the system

Getting status information from printers

Description - Xerox DocuPrint N17 Network Laser Printer 1.59-01


Device Status - Running
Status - Idle
Error Code - None
Default Input - 1
Console 1 - Ready
Console 2 Backchannel - Ready
To check if the printer supports a private printer MIB
1

Open the Columbus OM config\oids.tab file.


The entries in the file contain the status information made available by a
private printer MIB. (The last entry contains the status information made
available by the common printer MIB.)

If there is a private printer MIB entry for the printer, make a note of its
ENTERPRISE_NO.

To choose between the common and private printer MIB

If the printer supports both the common printer MIB and a private printer MIB,
you can choose which MIB provides the most useful status information. To do this,
compare the information for the printer MIBs in the oids.tab file.
Using the printer MIB to get status information
Set the printer servers BackChannel and Query_Printer parameters as follows.

To set the BackChannel parameter, use:


uqsnmpinfo [-c community:port] [-n enterprise_no] printerid
backchannel

To set the Query_Printer parameter, use:


uqsnmpinfo [-c community:port] [-n enterprise_no] printerid

Options
[-c community:port]

(Used with printers that have external JetDirect cards with multiple ports.)
Specify the SNMP community and the port number (usually 1, 2 or 3).
printerid

Either the network name of the printer or its TCP/IP network address.
enterprise_no

(Used only if you want to get status information from a private printer MIB.)
The ENTERPRISE_NO of the private printer MIB.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

kwikinfo

Monitoring the system

Getting status information from printers

Set the printer servers BackChannel and Query_Printer parameters to use the
following command:
Syntax
kwikinfo printerid

Parameter
printerid

Either the network name of the printer or its IP address.

ncrdinfo

Find the type of network card that the printer uses by typing:
ncrdinfo -c detect printerid [community]

where printerid is the printers IP address.


2

If Columbus OM can identify the network card, it displays a message like this:
Printer Card Detection
----------------------- This product has an enterprise-specific number of 253.
-- This product calls itself: HP Ethernet Multi-Environment, JetDirect
--- The card is made by Hewlett-Packard.
or
AXIS
-- Which means you have a choice of:
-hpjd
-axishp

If the network card is axishp or hpjd, you can use information in the
ncrdinfo command. See ncrdinfo on page 409.
If the network card is axis, hr1514 or lexmark, you have to specify
additional information. See Finding the additional information required
below.

Finding the additional information required


If the network card is axis, hr1514 or lexmark, you have to specify additional
information in the ncrdinfo command. For example, if the printer has multiple
ports, you have to specify which one the network card is on.
1

Type:
ncrdinfo -x -c cardtype printerid

Replace cardtype with axis, hr1514 or lexmark, and replace printerid


with the printers IP address.
The printer responds with a message like this:
Index Type Description
----- ---- ----------1
p Xerox DocuPrint N17 Network Laser Printer - 1.59-01
2
IEEE 1284 port
3
Ethernet port
4
Serial port
4 devices found
1 printer found
Use the -e option with the index number.

COLUMBUS OM INSTALLATION AND CONFIGURATION

409

410

CHAPTER 16

Monitoring the system

Getting status information from printers

The message shows the additional information that you need to specify in the
ncrdinfo commands -e parameter. In this example, the message shows that
the network card uses port 1, so the command you specify looks like this:
ncrdinfo -c hr1514 -e 1 10.20.0.244

Specifying the ncrdinfo command


Set the printer servers BackChannel and Query_Printer parameters to use the
following command.
Syntax
ncrdinfo -c cardname [-e extras] [-t timeout] [-v]
printerid [community]
Parameters
-c cardname

Specifies the card. Replace cardname with one of these:


Value

Description

axishp

Axis emulation of HP JetDirect

axis

Axis

hpjd

HP JetDirect

hr1514

RFC1514 Host Resource

lexmark

Lexmark

-e extras

Use if the network card is axis, hr1514 or lexmark: see Finding the
additional information required above.
-t

Specifies the timeout period in seconds.


-v

Displays exactly what the printer returns to the request for status.
printerid

The network name or IP address of the printer.


community

The community name of the device. The default name is public.

lprinfo

Set the printer servers BackChannel and Query_Printer parameters to use this
command:
Syntax
lprinfo host [queue] [options]

or
lprinfo -p printer [options]

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Getting status information from printers

Parameters
host

The name of the host (as specified in the etc/hosts file) that is running the lp
daemon (lpd) or, if the network card supports the lpd protocol, the name of
the printer.
queue

The lpd queue name. If it is the same as the host, then you can omit this
parameter.
-p printer

The name of the Columbus OM printer.


options

One or more of:

oceinfo

Option

Description

-a

Returns all information.

-b

Suppresses leading blank lines.

-c number

Suppresses the first number characters.

-l number

Displays a maximum of number lines.

-m number

Displays a maximum of number characters.

-q service

Uses service instead of the printer.

-r

Ignores carriage return characters when counting the


number of lines (use this with -l option, if required).

-s

Returns short status information (if the lp daemon


supports this mode).

-t timeout

Sets the maximum seconds that the command should wait


for a response. The default is 1 second.

-u character

Suppresses display until the character is found.

-x string

Suppresses lines containing string.

-zz

Switches on a debugging trace.

To get status information from Oce printers, set the printer servers BackChannel
and Query_Printer parameters to:
oceinfo host

Replace host with either the name of the printer as specified in the etc/hosts file,
or its TCP/IP address.

COLUMBUS OM INSTALLATION AND CONFIGURATION

411

412

CHAPTER 16

pjlinfo

Monitoring the system

Getting status information from printers

To get status information from PJL-enabled printers that use the pjlout driver, set
the printer servers BackChannel and Query_Printer parameters to use the
following command.
Printer type

Command

Local printer

pjlinfo -p printer [-a] [-c port]

Remote printer

pjlinfo host [-a] [-c port]

Parameters
host

The name of the host that the Columbus OM instance that controls the printer
is on.
-p printer

The name of the printer, as defined in Columbus OM.


-a

Returns the information as a text message instead of just a number.


-c port

The port number.


The status information is put into the
%UNIQDIR%\servers\printer\pjlstat.log file.
To exclude a host from the status feedback feature

Add the name of the host to this file:


%UNIQDIR%\config\nofb.tab

Displaying the printer status in Columbus OM Explorer


To

Do this

display the information returned by the See Displaying the information from
printers BackChannel command or
statserver on page 413.
Query_Printer command
create a list of printers that are reporting See Printer Warnings folder on
a problem
page 414.
display a printers web page

Right-click the printer icon, and then


click Printer Administration.

send status information to the


accounting database

See Integration with


Columbus Accounting on page 572

automatically update the status


information that is displayed

See Scanning printers for status


changes on page 416.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Getting status information from printers

Displaying the information from statserver

To

Do this

display the information that is provided Click the Advanced tab, and then click
by the statserver command
Printers. The status information is
displayed in the Back Channel column.
display the BackChannel column

Click Options on the View menu. In


the Preferences dialog box, click the
Columns button (not the Columns tab).
Select Back Channel, and then click
OK.

change what information is displayed in See Configuring the Back Channel


the BackChannel column
column below.
display the status information from the
Query_Printer command

Click the Advanced tab, and then click


Printers. Click a printer, and then click
the Printer Status toolbar button
.
The Detailed Status window appears.

Configuring the Back Channel column


You can change the information that is displayed in the Back Channel column in
Columbus OM Explorer if the printer supports a common or private printer MIB
(see Checking for printer MIB support on page 407).
To change what is displayed in the Back Channel column
1

Edit the %UNIQDIR%\config\oids.tab file, and then find the section for the
printer MIB that Columbus OM uses to get status information from the printer.
This can be either a private printer MIB or the common printer MIB: which
Columbus OM uses depends on the value that you set the BackChannel
command to (see Using the printer MIB to get status information on
page 408).
For example, the common printer MIB might look like this:

COLUMBUS OM INSTALLATION AND CONFIGURATION

413

414

CHAPTER 16

Monitoring the system

Getting status information from printers

# 1
Common Printer MIB
#
ENTERPRISE_NO
"Common Printer MIB" 1
#
# Key
Description
Oid
# ----------------------------------- -------------------------------DESCRIPTION
Description
1.3.6.1.2.1.25.3.2.1.3.1
DEVICESTATUS
"Device Status"
1.3.6.1.2.1.25.3.2.1.5.1
PRINTERSTATUS
Status
1.3.6.1.2.1.25.3.5.1.1.1
PRINTERERROR
"Error Code"
1.3.6.1.2.1.25.3.5.1.2.1
DEFAULTINPUT
"Default Input"
1.3.6.1.2.1.43.5.1.1.6.1
CONSOLEBUF1
"Console 1"
1.3.6.1.2.1.43.16.5.1.2.1.1
CONSOLEBUF2
"Console 2"
1.3.6.1.2.1.43.16.5.1.2.1.2
BACKCHANNEL
Backchannel
"%CONSOLEBUF1%"
END_ENTERPRISE
# ------------------------------------------------------------------------

The information that Columbus OM displays in the BackChannel column is


specified by the value in the Oid column for the BACKCHANNEL key in this file.
In this example, Columbus OM displays the contents of the CONSOLEBUF1 key.
2

Change the Oid value for the BACKCHANNEL key.


You can either change it to a different key, for example: "%DEVICESTATUS%",
or add to the current value, for example: "%CONSOLEBUF1% &
%PRINTERERROR%".
To make the printer status information easier to read, you can include space
characters and other characters such as & (ampersand).

Save the file.

In Columbus OM Explorer, click Refresh on the View menu.


The Back Channel column now contains the additional status information.

Printer Warnings folder


The Printer Warnings folder displays printers that have a problem such as Out of
Paper or Offline. It provides an easy way of checking that a printer is available
before you send a document to it. You can control which printers might be
included, and what types of problem cause them to be included.
To include a printer in the Printer Warnings folder
1

For the printer, make a list of all the printer messages that could be displayed in
the Back Channel column. To find out the possible messages, do one of the
following:

Check the printers documentation.

Simulate the various error conditions (by, for example, removing the paper
trays and taking the printer offline), and then make a note of the text that
appears in the Back Channel column.

Decide which of the printer messages you want Columbus OM to consider as


warnings that indicate the printer should be added to Printer Warnings
folder.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Backchannel text
---------------------"Close"
"Jammed"
"Down"
"Offline"
"Load"
"Paper"
"Unavailable"
"Warning"
"Other"
"Unknown"
"Toner"
"NoResponse"

Add a row to the file:

Getting status information from printers

Edit the %UNIQDIR%\config\backchan.tab file.


# Status
# ----------COVER_OPEN
COVER_OPEN
OFFLINE
OFFLINE
PAPER_OUT
PAPER_OUT
UNAVAILABLE
WARNING
WARNING
WARNING
WARNING
WARNING

In the Backchannel text column, specify one of the words that is


displayed in the BackChannel column when the error occurs. For example,
if when you remove a paper tray, the text Insert Tray 1 is displayed, you
might specify Insert.
In the Status column, indicate the type of error by specifying one of these
words: COVER_OPEN, OFFLINE, PAPER_OUT, UNAVAILABLE or WARNING.
Columbus OM displays this word as the printers status.

Save the file.

Example

If, when you remove a paper tray, the text Insert Tray 1 appears in the Back
Channel column, add a row like this to the backchannel.tab file:
PAPER_OUT

"Insert"

When you remove the tray, Columbus OM displays the printer in the Printer
Warnings folder.

COLUMBUS OM INSTALLATION AND CONFIGURATION

415

416

CHAPTER 16

Monitoring the system

Getting status information from printers

Scanning printers for status changes


To check if the printer status has changed, click the Refresh toolbar button

To refresh the printer statuses automatically, do the following:


1

On the View menu, click Options.

In the Columbus OM Preferences dialog box, click the Printers tab, and then
click Refresh.

Set the Scan Rate to the interval (measured in minutes) at you want
Columbus OM Explorer to scan printers looking for problems.

Click OK.

This feature scans only enabled printers; it does not scan disabled printers.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Operating system actions during processing

Operating system actions during processing


To help monitor the use of Columbus OM (when servers are started or stopped, the
progress of documents and so on), you can set all the printer servers, all the fax
servers and most of the servers to run an operating system command when these
events occur and at the different stages of processing documents.
To set up these commands, use the Action_On parameters for each server. For
example, to display a message when a server is started, set the servers
Action_On_Start parameter to:
echo Server started at %TIME

The commands can include substitution variables, for example %DOCUMENT for the
current document and %DATE for the current time. For a list of the substitution
variables that can be included, see Substitution variables on page 603.
To

Do this

set the Action_On parameters for a


printer server

See Configuring the printer on


page 164. Click the next to Action
On, and then click the parameter.

set the Action_On parameters for a


server

See Configuring servers on page 99.

Parameter

Executed when

Action_On_Completion

After successfully processing a queue entry. For a


master queue entry, this parameter applies when all
of its child entries have completed successfully.

Action_On_Failure

When processing of a queue entry is unsuccessful.


For a master queue entry, this parameter applies
when all of its child entries have failed.

Action_On_Incomplete

After processing a master queue entry, when some of


its child entries have completed successfully, and
some have failed.

Action_on_New

A child entry is added to the queue.

Action_On_Postponement A queue entry is postponed.


Action_On_Processed

After processing a master queue entry, before the


eventual status determined by its children.

Action_On_Shutdown

The server terminates normally.

Action_On_Start

At the start of processing a queue entry.

Action_Pre_Completion

Immediately before completing a queue entry.

COLUMBUS OM INSTALLATION AND CONFIGURATION

417

418

CHAPTER 16

Monitoring the system

Writing journal information

Writing journal information


To create a report about the entries that are in a queue, use these commands:
Pending queue
syq -JOURNAL_PENDING|-jp [entry_id] [file]
syq -JOURNAL_PENDING_APPEND|-jpa [entry_id] [file]
syq -JOURNAL_PENDING_OVERWRITE|-jpo [entry_id] [file]

Completed queue
syq -JOURNAL_COMPLETE|-jc [entry_id] [file]
syq -JOURNAL_COMPLETE_APPEND|-jca [entry_id] [file]
syq -JOURNAL_COMPLETE_OVERWRITE|-jco [entry_id] [file]

Archive queue
syq -JOURNAL_ARCHIVE|-ja [entry_id] [file]
syq -JOURNAL_ARCHIVE_APPEND|-jaa [entry_id] [file]
syq -JOURNAL_ARCHIVE_OVERWRITE|-jao [entry_id] [file]
To

Do this

write journal information for a single


entry

Include its entry number (entry_id)

write journal information for all the


entries on the queue

Omit the entry_id

specify the file name

Include file
The default names are pending.jnl,
completed.jnl, and archive.jnl

add the information to the end of an


existing file

Use the ..._APPEND option

replace an existing file

Use the ..._OVERWRITE option

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Log files

Log files
Columbus OM records information about what the servers and printer servers do
in log files.
Command line
The log files are in the %UNIQDIR%\servers\servername folder.
Columbus OM Explorer
Navigate to: Documents tab
Logs

instance icon

Maintenance menu

Browse

Log files
File

Location and description

General processing
activity

%UNIQDIR%\servers\server\dayDD.log
DD is the day of the month that the log file covers
(day01.log, day02.log, and so on, up to day31.log).

Each days log file is retained for one month.


When a printer was
last enabled or
disabled

%UNIQDIR%\servers\server\operator.log

Standard output
messages

%UNIQDIR%\servers\server\driver.log

The file is overwritten each time the printer server is


started.

Standard error stream %UNIQDIR%\servers\server\driver.err


messages
The file is overwritten each time the printer server is
started.
Summarizing printer activity: uqrep command
To create a report from the information that is in a printers day log files, use the
uqrep command.
To create a report that covers one day

At the command line, type:


uqrep [date] [>file]

[date] is the date for which you want information, one of:
dd

The day (01, 02 ... 31) of the current month.

ddmm

The day (01, 02 ... 31) of the specified month (01, 02 ... 12).

(if date is omitted) Today.

>file puts the information into the file that is specified. If you do not include

this parameter, Columbus OM displays the information onscreen.

COLUMBUS OM INSTALLATION AND CONFIGURATION

419

420

CHAPTER 16

Monitoring the system

Log files

To produce a report that covers several days


1

Produce reports for each of the individual days by running several


uqreq date > file commands.

Summarize the reports by using this command:


uqreq -SUMMARISE file file [file]...

Replace file... with a list of the report files that you produced.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Recording information about events

Recording information about events


To track the use of Columbus OM, you can record when users perform operations
such as starting a server or fixing a queue. You can specify the events that you want
to monitor, and then:

record information about the event in log files


To display the log files, see Log files on page 419.

send information about the event as an SNMP trap, to be collected by another


application

send information about the event to another application.

This feature is called event logging.

Setting up event logging


The event logging feature is controlled by a server called evserver. evserver is
created and configured for you when you install Columbus OM. For more
information about its configuration, see evserver configuration parameters on
page 438.
To specify which events you want to record, and what to do with the information,
edit the event logging configuration file (%UNIQDIR%\config\eventlog.tab).
File format
In the eventlog.tab file, specify the events that you want to record by using one
or more blocks in the following formats. The file can contain as many blocks as you
need.
Logging type

Block format (see also "Parameters" below)

File logging

FILE filename
events
FORMAT format

SNMP logging

SNMP host:port
events
CONFIG config

Custom logging

CUSTOM filter
events
FORMAT format
CONFIG config

Parameters
filename

(For file logging.) The path and name of the file in which the events are to be
recorded.
The name can include environment variables, and the date and time (by using
substitution variables). For example:
FILE ${UNIQDIR}\media\events\events-%DATE(YYMMDD).log

COLUMBUS OM INSTALLATION AND CONFIGURATION

421

422

CHAPTER 16

Monitoring the system

Recording information about events

host

(For SNMP logging.) The computer to which the SNMP traps are to be sent:
specify either its hostname or its IP address.
See also SNMP enterprise numbers on page 436.
port

(For SNMP logging.) The port number or service name to which the SNMP
traps are to be sent. Most enterprise management systems listen on port
snmp-traps, trapd or 162.
filter

(For custom logging.) The name of the application that is used to process
events.
events

The events that are to be recorded:


To

Do this

record all events

Specify ALL

record no events

Specify NONE

a single event

Specify its code (see Event codes on


page 430)

two or more events

Specify the event codes by using a


comma, for example:
C25, C100, P10

a range of event numbers

Specify the range, separated by a


comma, for example: P10-15

all events for a product

For all common events, specify C*.


For all print events, specify P*.
For all fax events, specify F*.

all events of a specific class

Specify the class (see Event classes on


page 429).

You can combine these methods, for example:


AUDIT,P10-15,C25,C100,F*

For a shortcut to specify groups of events that you want to use more than once
in the file, see Specifying groups of events on page 425.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Recording information about events

format

The format in which the event information is recorded in the log file. Use these
substitution variables (they are different from the standard substitution
variables). For basic information about an event, use %LOGDATA.
Substitution
variable

Description

%%

A single percent character (that is: %).

%CLASS

Event class, for example: "Admin" (see Event classes on


page 429).

%CODE

Event code (decimal format), excluding the product letter.


For example, if the event code is C1, %CODE is 1.

%DATE

Date of event. The default format is: "DD MON YY".

%DESCRIPTION

Event description text, enclosed in quotation marks (for


example: "Purge Queue").

%EVENTD

Event number (decimal format), including the product


identification.

%EVENTX

Event number (6 digit hexadecimal number), including the


product identification.

%LOGDATA

Information comprising:

the date and time when the event occurred

the product letter (see Event codes on page 430)

the event number and description (see Event codes: C


(Common: All products) on page 430)

additional information, for example, the name of the


server that was started.

This is the format used in the event logging feature that was
available in versions before Columbus OM 4.4.
%MICRO

Time of event (the number of microseconds since the time


given by %SECONDS).

%NPARAM

The number of parameters that the event has. This is a


number from 0 to 20.

%PARAMn

The value of event parameter n (1-20).


If the parameter contains spaces, it is enclosed in quotation
marks.
If the parameter does not exist (for example, you specify
PARAM4 for an event that has only 3 parameters), the value
is: (null)

%PRODC

Product code (one of B, C, D, F, M, P, R or T: see Event


codes on page 430).

%PRODD

Product code (decimal number).

COLUMBUS OM INSTALLATION AND CONFIGURATION

423

424

CHAPTER 16

Monitoring the system

Recording information about events

Substitution
variable

Description

%PRODS

Product code (the same as %PRODC, except that "Common"


events are indicated by a space, instead of C).

%PRODX

Product code (6 digit hexadecimal number).

%SECONDS

Date and time of event, given as the number of seconds


since 1 January 1970.

%TIME

Time of event. The default format is: "HH:MM:SS".

%TYPEn

Type of parameter n ("Product", "User" and so on).

${name}

Environment variable name.

config

(For SNMP logging and custom logging.) Configuration data, specified by using
one or more of the following items:
Data

Description

max_events=number

The maximum number of events to be processed


at once.
After this number has been processed,
Columbus OM stops the event filter program,
and then restarts it if necessary. This can be used
to check at intervals that events are being
processed successfully.
If you do not want to use this feature, specify 0.
For SNMP logging, the default value is 100.
For custom logging, the default value is 0.

max_time=seconds

The maximum time to spend processing events.


After this time, Columbus OM stops the event
filter program, and then restarts it if necessary.
This can be used to check at intervals that events
are being processed successfully.
If you do not want to use this feature, specify 0.
For SNMP logging, the default value is 300.
For custom logging, the default value is 0.

restart=number|Yes|No

The maximum number of attempts to restart the


filter program if an error occurs.
To not restart the filter program, specify No.
To keep trying to restart the filter program until
it works, specify Yes.
The default value is No.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Recording information about events

Data

Description

stderr=Yes|No

To check for errors in the standard error file after


closing the event filter program, specify Yes.
The default value is Yes.

stopcmd=command

The command to send to the event filter to stop


it.
For SNMP logging, the default value is q.
For custom logging, the default value is just to
close the connection.

verify=Yes|No

To run event filter once, without sending it any


events, before starting to process events, specify
Yes.
This is useful to make sure that the filter is
configured correctly.
The default value is Yes.

To specify multiple items, separate them by using a semicolon.


If any of the values contains a semicolon, use any non-alphanumeric character
(for example, a plus sign) as the separator instead of a semicolon. To indicate
which character you are using, also include it at the start of the values.
Example 1:
CONFIG max_time=120 ; stopcmd=q

Example 2:
In this example, the separator character is + (plus sign):
CONFIG +max_events=20 + stopcmd=save;quit

Specifying groups of events


To create a shortcut that refers to a group of events:
1

Add an entry at the start of the file using this syntax:


GROUP name list

name is a name to identify the group elsewhere in the file.

list is a list of events. Separate the events by using a comma. To specify a

range of events, use a hyphen for example, P145-155. To specify all events
that start with the same code, use the code followed by * (asterisk). To nest
groups, use &name.
2

To refer to a group later in the file, use &name.

COLUMBUS OM INSTALLATION AND CONFIGURATION

425

426

CHAPTER 16

Monitoring the system

Recording information about events

For example:
GROUP
GROUP
GROUP
GROUP

print
common
user
other

P145-155
C76,C77,C86,C102
U*
&common,&user

# Filter 1
# -------FILE ${UNIQDIR}\media\events\printlog.%DATE(YEAR-MO-DD).tab
&print
#
# Filter 2
# -------FILE ${UNIQDIR}\media\events\otherlog.%DATE(YEAR-MO-DD).tab
&other

Redefining standard events


You can change how the standard events are recorded, that is, the description and
the arguments. Specify the new format in the following file:
File location and name
%UNIQDIR%\config\userevent.tab

(This file is also used for defining your own events. For more information, see
Defining additional events to be recorded on page 427.)
File format
1

In the userevent.tab file, start the section specifying the standard events that
you want to redefine with this keyword:
STANDARD_EVENTS

List the events as in this example:


# Event
# ----C76

Description
-----------------"Added new entry"

C77

"Add held entry"

P145
P147

"Entry started"
"Entry completed"

Arguments
--------%UID %DOCUMENT_PATH
%DESTINATION %OWNER %PRIORITY
%UID %DOCUMENT_PATH
%DESTINATION %OWNER %PRIORITY
""
""

Field

Description

Event

Event number, including its letter prefix. For a list of the


numbers, see Event codes on page 430 .

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Recording information about events

Field

Description

Description

A new description for the event. To use the standard


description, specify "".

Arguments

A list of arguments, given as substitution variables. The


maximum number of arguments is 20. To use the standard list
of arguments, specify "".

To validate the file, see Validating the user events file on page 428.

Defining additional events to be recorded


In addition to the standard events that Columbus OM can record, you can define
other events in which you are interested. First define the events, and then run a
program to create the events.

Defining the
events

Define the events in this file:


%UNIQDIR%\config\userevent.tab

(This file is also used for redefining standard events. For more information, see
Redefining standard events on page 426.)
File format
The userevent.tab file contains these sections:
Section

Description

ARGUMENT_TYPES

The types of arguments used for the additional events.

USER_EVENTS

The extra events that you want to record.

STANDARD_EVENTS

See Redefining standard events on page 426.

ARGUMENT_TYPES: Specifying the arguments


In the ARGUMENT_TYPES section, define the argument types that are used only for
user-defined events. If all the user-defined events use only the standard argument
types (see Standard argument types below), omit this section.
Start the arguments section with ARGUMENT_TYPES, and then list the codes and
descriptions as in this example:
ARGUMENT_TYPES
# Code Description
# ---- ----------51
Errcode
52
Errtext
53
Stats

Code
A number to identify the argument type, 51 100.
Description
A description of the argument. This text is returned by the %TYPEn substitution
variable. The maximum length of the description is 15 characters.

COLUMBUS OM INSTALLATION AND CONFIGURATION

427

428

CHAPTER 16

Monitoring the system

Recording information about events

Standard argument types


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

Product
User
Priority
Uid
Queue
Server
Paper
Program
Other
Type
Licence
Medium
Instance
Class
Destination
Security
Chars
Attempts
Pages
Status
Revision
PageNo

USER_EVENTS: Specifying user events


Start the section specifying the extra events that you want to record with
USER_EVENTS, and then list the events as in this example:
USER_EVENTS
# Event Class
# ----- ----21
FATAL
22
STATS

Arguments
--------51,52
53,53,53

Description
---------------------"Fatal system error"
"Statistical data record"

Event
Event number, 1 9999.
Class
Event class, one of: Admin, Audit, Detail, Error, Fatal, Security, and Stats.
See also Event classes on page 429.
Arguments
A list of argument types (as specified in the ARGUMENT_TYPES section). Separate
multiple argument types with commas. There must be no spaces between the items.
Description
Text describing the event.

Validating the
user events file

To validate the userevent.tab file, use this command:


logevent -validate

Columbus OM checks the file, and then reports any errors.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Generating
user-defined
events

Monitoring the system

Recording information about events

To generate user-defined events, use the logevent program. logevent can be run
from scripts or other applications as required.
logevent can also be used to generate standard events.

Syntax
logevent number arguments

Parameters
number

The number of the event to be generated, as defined in the USER_EVENTS


section of the userevent.tab file, preceded by U (for example, U51).
You can also record standard events by specifying their code, for example,
P145 or C76. For a list of the event codes, see Event codes on page 430.
arguments

The values of the arguments to be recorded.


Example
Some events can be defined in the userevent.tab file like this:
ARGUMENT_TYPES
51
Errcode
52
Errtext
53
Stats
USER_EVENTS
21
FATAL
22
STATS

51,52
53,53,53

"Fatal system error"


"Statistical data record"

To generate events for these, use these commands:


logevent U21 99 "Database corruption detected"
logevent U22 1000 96 2401

Event classes
To record information about event of a specific type, use these classes in the events
parameter (see events on page 422):
For information about

Use

events that prevent Columbus OM from proceeding, for example:


System error, License expired, Printer offline

FATAL

errors such as Servers active cannot fix, Queue fixed - still corrupt ERROR
use of the administration functions

ADMIN

auditing events, for example: Server starting and Queue fixed - now AUDIT
OK
when a user tries to access a function that they are not authorized to use SECURITY

COLUMBUS OM INSTALLATION AND CONFIGURATION

429

430

CHAPTER 16

Monitoring the system

Recording information about events

For information about

Use

the Printing entry page message

DETAIL

use of the document queues, for example: Added new entry to


queue, Job completed OK. (This option is available only for the
Columbus OM print facility.)

STATS

Event codes
Event codes comprise a letter that indicate the product (C for Common, F for Fax,
or P for Print), and a number, as shown in the sections below.
Event codes: C (Common: All products)
No

Class

Description

Arguments

C1

Audit

Server starting

Program, Other

C2

Audit

Server termination complete

Program

C3

Fatal

System error

Program, Other

C7

Security Auth fail: Modify other users queue entry

User

C8

Security Auth fail: Add queue entry for other user

User

C9

Security Auth fail: List queue entries for other users

User

C10

Security Auth fail: View queue entries for other users User

C11

Security Auth fail: List arch. entries for other users

C12

Security Auth fail: View arch. entries for other users User

C13

Security Auth fail: Remove entry for other user

User

C14

Security Auth fail: Resubmit entry as own

User

C15

Security Auth fail: Add entry

User, Priority

C16

Security Auth fail: Download any file

User

C17

Security Auth fail: Download file from queue

User, Queue

C18

Security Auth fail: List queue entries for all users

User, Queue

C19

Security Auth fail: List details of queue entries

User

C20

Security Auth fail: Kill server

User

C21

Security Auth fail: Initiate server

User

C22

Security Auth fail: Terminate server

User

C23

Security Auth fail: Query server configuration

User

C24

Security Auth fail: Duplicate server

User

C25

Security Auth fail: Add server

User

C26

Security Auth fail: Modify server

User

C27

Security Auth fail: Remove server

User

User

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Recording information about events

No

Class

Description

C28

Security Auth fail: Remove from queue

User, Queue

C29

Security Auth fail: Display system defaults

User

C30

Security Auth fail: Purge queue

User

C31

Security Auth fail: Extend queue

User

C32

Security Auth fail: Fix queue

User

C33

Security Auth fail: Journal queue

User

C34

Security Auth fail: Display queue status

User

C35

Security Auth fail: Display server status

User

C36

Security Auth fail: Write from completed to archive User

C37

Security Auth fail: Run command on server system

User

C38

Security Auth fail: Fetch file from server to client

User

C39

Security Auth fail: Send file from client to server

User

C40

Security Auth fail: Send queue entry to server

User

C41

Security Auth fail: Send script to server and execute User

C42

Security Auth fail: Run uq on server system

User

C43

Admin

Copy server

Server, Server

C44

Admin

Kill server

Server

C45

Admin

Query server configuration

Server

C46

Admin

Check queue

Queue

C47

Admin

Compress queue

Queue

C48

Error

Queue corrupt

Queue

C49

Audit

Queue OK

Queue

C50

Admin

Display system defaults

C51

Admin

Extend queue

Queue

C52

Admin

Fix queue

Queue

C53

Admin

Force fix queue

Queue

C54

Error

Servers active- cannot fix

Queue

C55

Audit

Queue OK- no fix needed

Queue

C56

Admin

Initiate server

Server

C57

Admin

Terminate server

Server

C58

Admin

Initiate all servers

C59

Admin

Terminate all servers

C60

Admin

Produce journal of queue

COLUMBUS OM INSTALLATION AND CONFIGURATION

Arguments

Queue

431

432

CHAPTER 16

Monitoring the system

Recording information about events

No

Class

Description

Arguments

C61

Admin

Purge queue

Queue

C62

Admin

Force purge queue

Queue

C63

Admin

Display queue status

C64

Admin

Display server status

C65

Admin

Display status for all servers

C66

Admin

Write from completed to archive queue

C67

Audit

Queue fixed- now OK

Queue

C68

Error

Queue fixed- still corrupt

Queue

C69

Admin

Force write from completed to archive


queue

C70

Admin

Add other server

C71

Admin

Display status for active servers

C72

Admin

Remove a server

C73

Admin

Modify system defaults

C74

Admin

Serial line definition

C75

Audit

Recreate a queue, empty

Queue, User

C76

Stats

Added new entry to queue

Program, User,
Uid

C77

Stats

Added held entry to queue

Program, User,
Uid

C78

Stats

Released held entry in queue

Program, User,
Uid

C79

Stats

Paused pending entry in queue

Program, User,
Uid

C80

Stats

Redirected entry to new destination

Program, User,
Uid, Other

C81

Stats

Moved entry to new queue

Program, User,
Uid

C82

Stats

Removed entry from the queue

Program, User,
Uid

C83

Stats

Resubmitted new entry to the queue

Program, User,
Uid, Other

C84

Stats

Resubmitted held entry to the queue

Program, User,
Uid, Other

C85

Stats

Queue entry has been modified

Program, User,
Uid, Other

Server

Server

Server

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Recording information about events

No

Class

Description

Arguments

C86

Stats

Document has been browsed

Program, User,
Uid, Other

C87

Stats

Job completed OK

Program, User,
Uid, Other

C88

Stats

Job completed but failed

Program, User,
Uid, Other

C89

Stats

Job has been cancelled

Program, User,
Uid, Other

C90

Stats

Queue Job has been aborted

Program, User,
Uid

C91

Stats

Queue Job has been cancelled

Program, User,
Uid

C92

Stats

Queue Job has been postponed

Program, User,
Uid

C93

Stats

Queue Job has been paused

Program, User,
Uid

C94

Stats

Queue Job has been resumed

Program, User,
Uid

C95

Stats

Job has been received from an external


source

Program, User,
Uid, Other

C96

Admin

Add server to class

Server, Class

C97

Admin

Remove server from class

Server, Class

C98

Security Auth fail: Add server to class

User

C99

Security Auth fail: Remove server from class

User

C100 Fatal

Server bad configuration

Program, Server

C101 Audit

Server shutdown requested

Server, User,
Other

C102 Stats

Job finished but incomplete

Program, User,
Uid, Other

C103 Stats

Document has been downloaded

Program, User,
Uid, Other

C104 Stats

Queue entry has been modified

Uid, User

C105 Audit

Queue entry has been auto-extended

Queue, Count

C106 Audit

Queue entry has been auto-purged

Queue, Count

C107 Audit

Queue entry has been auto-archived

Queue, Count

COLUMBUS OM INSTALLATION AND CONFIGURATION

433

434

CHAPTER 16

Monitoring the system

Recording information about events

Event codes: F (Fax)


No

Class

Description

Arguments

F5

Admin

Fax server started

Server

F6

Admin

Sending a fax

Server, Destination

F7

Admin

Receiving a fax

Server

F8

Error

Entry postponed

Destination,
Owner, Uid, Other

F9

Error

Entry failed

Destination,
Owner, Uid, Other

F10

Fatal

Fatal error

Server, Other

F11

Audit

Fax server shutdown

Server, Other

Event codes: P (Print)


No

Class

Description

Arguments

P1

Fatal

Printer offline

Server

P2

Fatal

Printer busy

Server

P3

Fatal

Printer door open

Server

P4

Fatal

Printer out/low toner

Server

P5

Fatal

Printer paper out

Server

P6

Fatal

Printer paper jam

Server

P7

Fatal

SNMP not supported

Server

P8

Fatal

Unknown status returned

Server

P9

Fatal

No such SNMP variable

Server

P10

Fatal

Printer problem

Server

P11

Fatal

Printer parallel port unplugged

Server

P12

Fatal

Printer serial port unplugged

Server

P13

Audit

Printer starting

Program, Revision

P14

Audit

Printer termination complete

Program

P15

Audit

Initiate printer

Server

P13, P14 and P15 are used only if the Use_Print_Events parameter in
the system defaults file (default.tab) is set to Yes.
P100 Security Auth fail: Abort current printout

User

P101 Security Auth fail: Cancel current printout

User

P102 Security Auth fail: Disable printer

User

P103 Security Auth fail: Enable printer

User

P106 Security Auth fail: Lineup printout

User

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

No

Class

Monitoring the system

Recording information about events

Description

Arguments

P107 Security Auth fail: Mount paper on printer

User

P108 Security Auth fail: Unmount paper on printer

User

P109 Security Auth fail: Pause current printout

User

P110 Security Auth fail: Resume paused printer

User

P111 Security Auth fail: Split printout to another printer

User

P112 Security Auth fail: Trans. printout to another printer User


P113 Security Auth fail: Change printer device string

User

P114 Admin

Abort current printout

Server

P115 Admin

Cancel current printout

Server

P116 Admin

Change printer device string

Server

P117 Admin

Disable printer at end

Server

P118 Admin

Disable printer now

Server

P119 Admin

Disable printer when idle

Server

P120 Admin

Enable printer

Server

P121 Admin

Lineup printer

Server

P122 Admin

Unmount paper from printer

Server, Paper

P123 Admin

Mount paper on printer

Server, Paper

P124 Admin

Pause current printout

Server

P125 Admin

Resume paused printer

Server

P126 Admin

Split printout to another printer

Server, Server

P127 Admin

Transfer printout to another printer

Server, Server

P128 Admin

Add a printer

Server

P129 Admin

Modify a printer

Server

P131 Admin

Create new paper type

Paper

P132 Admin

Delete paper type

Paper

P133 Admin

Modify paper type

Paper

P134 Admin

Create new printer type

Type

P135 Admin

Delete printer type

Type

P136 Admin

Modify printer type

Type

P137 Admin

Modify other server

Server

P138 Admin

Modify print scheduler

P139 Audit

Print scheduler started

P141 Audit

Print scheduler stopped

COLUMBUS OM INSTALLATION AND CONFIGURATION

435

436

CHAPTER 16

Monitoring the system

No

Class

Recording information about events

Description

Arguments

P142 Audit

Printer started

Server

P144 Audit

Printer stopped

Server

P145 Audit

Starting to print entry

Server, Uid

P147 Audit

Finished printing entry

Server, Uid

P148 Error

Entry postponed

Server, Uid

P149 Error

Entry failed

Server, Uid

P150 Audit

Entry transferred

Server, Uid

P151 Audit

Entry received ACK

Server, Uid

P152 Error

Entry received NAK

Server, Uid

P153 Audit

Entry blocked

Server, Uid, Paper

P154 Audit

Entry processed

Server, Uid

SNMP enterprise numbers


In SNMP traps that are created by the event logging feature, the Columbus OM
products are identified by these enterprise numbers:
Product

Enterprise number

Common

1.3.6.1.4.1.2196

Print

1.3.6.1.4.1.2196.1

Fax

1.3.6.1.4.1.2196.3

Dispatch

1.3.6.1.4.1.2196.7

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

Monitoring the system: Reference


Status reporting system parameters
These parameters can be set in the system defaults file (default.tab).
Ack_Command NO|CSUNIQ|command

The use of Ack_Command is deprecated; it is better to handle


acknowledgements using the Status_Feedback setting.
BackChannel ON|OFF|statserver

ON turns on status reporting for all printers.

OFF turns off all status reporting for all printers.

statserver turns on status reporting only when the statserver program is

running.
FB_Action_On_Complete script

Specifies a user supplied script or program to be called when a print transaction


is complete.
This parameter is effective only when Columbus OM status feedback is
configured.
FB_Action_On_Failure script

Specifies a user supplied script or program to be called when a print transaction


has failed.
This parameters is effective only when Columbus OM status feedback is
configured.
Log_SFB_Errors Yes|No
Yes records errors that occur in the status feedback reporting system, for
example, if there an error writing to the file in which the status feedback is
recorded, or Columbus OM cannot connect to a remote system.

The errors are recorded in these logfiles:


%UNIQDIR%\media\cache\dayDD.log, where DD is the number of the day of
the month on which the error occurred. Each logfile is retained for one month.
The default value is Yes.
Status_Feedback number|YES|NO
0 or NO disables the status feedback mechanism. Use this setting if you do not

require detailed information on the progress of print jobs. In this case, set
Ack_Command to invoke the traditional ACK/NAK mechanism which reports

status back to an originating (remote) host only when a print job succeeds or
fails.
To return detailed status information to a remote host, also set
Status_Feedback to a number (of 5 or greater) or YES (equivalent to a number

of 10). The effect then is to report status back to the remote host as soon as it
changes from New > Starting > Printing > Complete/Failed/Postponed, and
also to report supplementary information (for example, Printing Page n) every
number seconds.

COLUMBUS OM INSTALLATION AND CONFIGURATION

437

438

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

To reduce network overhead, the SFCache server should be running, and


Status_Feedback must be set to 5 seconds or greater.
Use_Print_Events Yes|No
Yes records events about printers (that is, printer servers and xprinter servers)
starting and stopping as specific events: P13, P14 and P15.
No record events about printers starting and stopping under the general server
events, C1, C2 and C56.

The default value is No.

evserver configuration parameters


Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Action_On_Shutdown command

A command to be run when the server stops. For more information, see
Operating system actions during processing on page 417.
Error_Continue Yes|No

When the server starts, it checks the configuration of the filter programs.

Yes tells evserver to ignore any errors, and continue working. Events for

the filters that contain errors are cached; they can be processed by
correcting the errors, and then restarting evserver.

No tells evserver to stop.

Flush_Filter Yes|No

Events are written first to a common file, and then copied to a separate file for
each event filter.
To

Do this

copy each event as soon as it is available, so that it is


immediately available to the event filter

Specify Yes.

copy events in groups, when enough events have been


processed to force the file to be flushed to disk

Specify No.

The default value is No.


Flush_Logfile Yes|No

Each FILE filter reformats event records, and then writes the record in a logfile.
To write each record to the logfile as it is available, specify Yes.
To write records in groups, when enough events have been processed to force
the file to be flushed to disk, specify No.
The default value is No.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

Max_Reads number

The maximum number of times that evserver tries to read an event.


If a record is incomplete when the evserver reads it, the evserver tries again
after one second. If the record is still incomplete after the number of seconds
that is specified by this parameter, evserver discards the record.
The default value is 10.
Medium

Not used.
Server text

The name of the server.


Shutdown_Wait number

When you stop evserver, it stops the filter programs. This parameter tells it
how long (measured in seconds) to wait for them to stop. If a filter program is
still running after this time, evserver forces it to stop.
If you want evserver to wait forever for the filter programs to stop (and never
force them to stop), specify 0.
The default value is 0.
Wait_Time number

How long (measured in seconds) that the server sleeps when there are no
events for it to process.

statserver configuration parameters


Statserver monitors the status of printer servers.
It can send this information to a database, if the accounting feature is being used. It
can update the device_status table with information about the status, the date,
and the status code. It can also add information about new devices that have been
added to Columbus OM to the devices table and the device_types tables.
For more information about configuring printer servers to provide status
information, see Getting status information from printers on page 406.
Configuration file
%UNIQDIR%\servers\statserver\config.tab
Configuration parameters
Accounting_DB_Method DIRECT|OFF
DIRECT sends the status information to the accounting database.
Accounting_Refresh_Secs number

(Used if Accounting_DB_Method is set to DIRECT.) The interval (measured in


seconds) at which statserver sends information to the database. Statserver also
sends the information when the status of a printer changes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

439

440

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

BcCollector YES|NO
YES uses the multi-threaded bccollector program to get status information.
NO uses the less efficient (single-threaded) BackChannel method to get status

information.
The default value is YES.
Device_Callback [stat_mon]

Set to stat_mon only when a print instance is integrated into the SAP R/3
environment, using R/3 access method E: callback. Otherwise, leave blank
(the default).
Ignore_Disabled YES|NO
YES prevents statserver trying to collect the status of printers that are disabled.
Doing this might help to reduce network traffic.
Max_Sessions number

The maximum number of concurrent polling sessions. Keep this number as


low as possible to minimize the use of system resources.
This value should not exceed any system-imposed maximum number of
processes.
Medium medium

The medium name which marks a queue entry as suitable for processing by this
server.
Notify_Instance host:instance

(Usually used when Columbus OM is integrated with Columbus Central.) The


instance to which you want statserver to report the printer status. Specify the
name of the computer that it is on, and the name of the instance itself.
The default instance is the current one.
Notify_User text

(Usually used when Columbus OM is integrated with Columbus Central.) A


user id on the host computer that is specified by the Notify_Instance
parameter that will enable statserver to access the instance.
Scan_Interval number

The period, in seconds, between polling cycles. The default is 10.


See also Setting the Scan_Interval and Stagger_Time parameters on page 441.
Send_Traps YES|NO
YES to report abnormal status by sending SNMPv1 traps to the network
management tool specified by Trap_Manager and Trap_Manager_Port; NO
(the default) not to send traps.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

Stagger_Time number

The delay (measured in milliseconds) between status polls to individual


printers. For a small number of devices (less than 20), this parameter can be set
to null. The delay between polling cycles is specified by Scan_Interval.
See also Setting the Scan_Interval and Stagger_Time parameters on page 441.
Trap_Listener_Port port

The local port number on which statserver listens for SNMPv1 traps. Can be
specified as a port number or service name; standard values are either 162 or
snmp-trap.
Trap_Manager host

A remote host running a network management tool which is to be sent


SNMPv1 traps.
Trap_Manager_Port port

The port on the remote host specified by Trap_Manager where a network


management tool is listening for incoming SNMPv1 traps. Can be specified as a
port number or service name; standard values are either 162 or snmp-trap.
UQ_Service text

The name of the service that statserver uses to send the information. This is
used if statserver is sending the information to a different instance (specified by
using the Notify_Instance parameter).
The default service is uniqcs.
Setting the Scan_Interval and Stagger_Time parameters
The best values to use for Scan_Interval and Stagger_Time depend on the
number and type of printers and the speed of the computer.

For a system with relatively few printers (perhaps 10 or fewer), you can reduce
Stagger_Time, or even set it set to zero.

For a system with a lot of printers (100 or more), you might need to increase
both Scan_Interval (for example, to 20) and Stagger_Time (for example, to
20 if most printers have printer MIB support, or 100 otherwise).

uqsfcache server: Caching status feedback


uqsfcache caches status feedback information to improve Columbus OM
performance. Use the uqsfcache server in preference to the ACK/NAK
mechanism.
uqsfcache saves status information in a cache file. At intervals (specified by the
Process_Level parameter and the Scan_Interval parameter), it deletes

information that has been superseded, and then sends the rest all at once to the
appropriate host. This means that it has to login only once to the host for each
group of messages.
To use this feature, you must also set the Status_Feedback parameter in the
system defaults file (default.tab) to 5 seconds or more.

COLUMBUS OM INSTALLATION AND CONFIGURATION

441

442

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Action_On_Shutdown command
Action_On_Start command

Commands to be run in response to events. For more information, see


Operating system actions during processing on page 417.
Backup_Cache No|Yes
Yes makes a copy of the cache file before processing it. This makes sure that
statuses are retained if uqsfcache stops abnormally.

Columbus OM deletes the backup copy after it has processed the statuses, or
when uqsfcache stops normally.
The default value is Yes.
BlackList_Secs number

If uqsfcache cannot login into a host, this parameter tells it how long to wait
(measured in seconds) before it tries again (instead of repeatedly trying to
login). uqsfcache accumulates the statuses for the host until it becomes
available again.
If you set this parameter, make sure that its value is the same as or more than
the value of the Scan_Interval parameter.
The default value is 60 seconds.
Feedback_Actions YES|NO
YES tells uqsfcache to perform the actions that are specified by the
FB_Action_On_Complete and FB_Action_On_Failure parameters in the
system defaults file (default.tab).
NO tells uqsfcache to ignore those parameters.
Log_Bad_Instance YES|NO

This parameter might be useful if you are using uqsfcache with another
instance that is on the same computer, and that instance is not in the
systems.tab file.
In this situation, uqsfcache sends the status messages by the network (instead
of writing them directly to the instances cache file), and then puts an error
message in its logfile.
If you do not want these error messages recorded (because, for example, you
have deliberately omitted the instance from the systems.tab file), set this
parameter to No.
The default value is Yes.
Process_Level number

When the number of records in the cache file reaches this level, uqsfcache
starts processing them. Processing can also start after the interval that is
specified by the Scan_Interval parameter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

The default value is 10 records.


Remote_User text

A userid that Columbus OM can use to login to a remote host computer that it
needs to send feedback to.
The default userid is uniq; if there is no user called uniq on the remote host
computer, set this parameter.
Scan_Interval number

The interval (measured in seconds) at which uqsfcache starts processing the


records in the cache file. Processing can also start when the size of the cache file
reaches the number of records specified by the Process_Level parameter.
The default value is 30 seconds.
Send_All hostname [hostname] ...

Sends every status change to the hostnames listed, not only the latest status
change.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
Threshold_Secs number

The maximum time (measured in seconds) to retain the memory that is


allocated for the cache records (see Threshold_Size). After this time, the
memory is freed, and then re-allocated as required.
The default value is 600 seconds (ten minutes).
Threshold_Size number

The maximum number of cache records to keep in memory: if the cache file
exceeds this number for more than the time specified by the Threshold_Secs
parameter, the memory is freed and then re-allocated as required.
The default value is 1000 cache records.

COLUMBUS OM INSTALLATION AND CONFIGURATION

443

444

CHAPTER 16

Monitoring the system

Monitoring the system: Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

445

C H A P T E R 17

Chapter 17

Processing email
messages

This section describes how send email messages and process incoming email
messages by using Columbus OM.
Sending email messages
To send a document as an email message, you add it to the queue in the same way
as any other type of entry. The document can be sent as either the text of the email
message or as an attachment to the email message.
The entries are processed by the Columbus OM mailer server. It transfers the entry
to your email application (such as Microsoft Exchange), and then the email
application sends it to its destination (that is, an email address).
For more information, see Configuring Columbus OM to send email messages on
page 446.
Processing incoming email messages
Columbus OM can monitor a mailbox for incoming email messages, and then add
them to its queue for processing such as printing.
Columbus OM can apply special processing to:

the attachments to an email message, according to instructions that in the


message text

messages that indicate a delivery failure received in reply to email messages


sent by the mailer server.

For more information, see Processing incoming email messages on page 451.

COLUMBUS OM INSTALLATION AND CONFIGURATION

446

CHAPTER 17

Processing email messages

Configuring Columbus OM to send email messages

Configuring Columbus OM to send email messages


1

Add a new server, with these properties:


Property

Value

Server Name

Any characters, except spaces.

Program

Select mailer.

For more information, see Adding servers on page 98.


2

Set these properties:


Property

Value

SMTP_Server

The name of a server running a suitable SMTP mail server,


such as Microsoft Exchange.

Domain

The domain name, for example mycompany.com.

Sender

The email address of the person that will be using this


server.
To enable different users to send messages that are
indicated as having been sent by them, create and
configure a mailer server for each user. Alternatively, you
can use only one mailer server, and then allow users to
specify their email address when they add an entry to the
queue.

Message File

Default text for the body of the email messages. The file
must be in the %UNIQDIR%\servers\server_name
directory.

Select Autostart and Autostop.

For information about the other configuration parameters for the mailer server, see
mailer server configuration parameters on page 458.

Sending documents as email messages


To send an email message by using the mailer server, add an entry to the queue
with its medium set to mail.
Create file that contains the text that you want to appear as the body of the email
message. You can add other files as attachments to the email message; put these
files on the same computer as the Columbus OM instance that you are using.
Sending an email message by using Columbus OM Explorer
1

Add the entry in the same way as printing a document.


For more information about adding an entry, see Adding entries by using
Columbus OM Explorer on page 212.

On the Document tab, set the entrys Medium to Mail, and then type the
email address in the To box.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Configuring Columbus OM to send email messages

To change the document details, click the Details tab.

To

Do this

send more than one copy

Change the Copies option. Each copy


is sent as a separate email message,
and appears as a separate entry in the
document queue.

add CC recipients

Type the email addresses in the CC


box. Separate multiple email
addresses by using a comma.

change the subject line of the email


message

Type the text in the Subject box.

add a file as an attachment to the


message

Click Attach, and then type the full


path and name of the file.

The default subject line is Mail from


Columbus OM.

The file must be on the same


computer as the Columbus OM
instance.
Sending documents by using the command line
To send a document as an email message by using the command line, use an aeq
command with these parameters:
-m mail

Include this parameter so that the document is processed by the mailer server.

COLUMBUS OM INSTALLATION AND CONFIGURATION

447

448

CHAPTER 17

Processing email messages

Configuring Columbus OM to send email messages

-at address

The email address to which you want to send the message.


Optional parameters

To use these parameters, use the -st parameter:


-st "[-cc address] [-fa filename] [-fb filename] [-sn address]"
-cc address

Sends the email message to other email addresses as a CC (carbon copy).


-fa filename

Includes the file specified as an attachment to the email message. For example:
aeq message.txt -at john.smith@mycompany.com -m mail
-st "-fa"

This command sends an email message with the message.txt file as an


attachment.
-fb

Includes the file specified as the text of the email message. For example:
aeq message.txt -at john.smith@mycompany.com -m mail -st "-fb"

This command sends an email message with the content of the message.txt
file as its text.
-sn address

Specifies the senders email address, overriding the value of the mailer servers
Sender parameter. For example, to send an email message from
mary.brown@mycompany.com, use:
aeq -at john@mycompany.com -dt "Your file %UID has completed"
-st "-sn mary.brown@mycompany.com" -m mail

Examples
To send a document as an attachment to an email message
1

Set the mailer servers Message_File parameter to an empty value.

Add an entry using a command like this:


aeq -at john@mycompany.com -rt "Your file"
-dt "Your file %UID is attached"
-st "-fa c:\report.txt" -m mail

The -at parameter specifies the address to which the email message is sent.
-dt specifies the body of the message. -st specifies the document file to be
attached. -m mail ensures that the entry is processed by the mailer server.
To send an email message without an attachment
1

Set the mailer servers Message_File parameter to an empty value.

Add an entry by using a command like this:


aeq -at john@mycompany.com -rt "Meeting" -dt "Meeting at
10am." -m mail

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Configuring Columbus OM to send email messages

The -dt parameter specifies the body of the message.


To specify a standard text for the body of the email message
1

Put the text that you want to be used as the body of the email message into a
file.

Set the mailer servers Message_File parameter to the location and name of
the file.

Add an entry by using a command like this:


aeq -at john@mycompany.com -rt "Your file is attached"
-df c:\report.txt -m mail

To send a document as the text of the email message


1

Set the mailer servers Message_File parameter to an empty value.

Put the text that you want to be used as the body of the email message into a
file called, for example, mymessage.txt.

Add an entry by using a command like this:


aeq -at john@mycompany.com -rt "Meeting" -df c:\mymessage.txt
-m mail

To include a file in the text of the email message

To include the contents of a file in the text of the email message, use -fb in the -st
parameter text, For example:
aeq message.txt -at mary@mycompany.com -m mail -st "-fb -cc
john@mycompany.com"
To specify the senders email address

To specify the senders email address, set the mailer servers Sender parameter.
To specify a different senders email address when you add an entry, use the -st
parameter. For example, to send an email message from
mary@mycompany.com, use:
aeq -at john@mycompany.com -rt "File completed"
-dt "Your file %UID has completed"
-st "-sn mary@mycompany.com" -m mail
To send carbon copies

To send the email message to other email address as CC (carbon copies), use -cc
address in the -st parameter text, for example:
aeq message.txt -at john@mycompany.com -m mail
-st "-cc mary@macro4.com -cc pat@macro4.com"

This command sends the email message to John, and carbon copies to Mary and
Pat.
To change the format of documents

To specify a format to which all documents are to be converted, use the mailer
servers Convert_To parameter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

449

450

CHAPTER 17

Processing email messages

Configuring Columbus OM to send email messages

To convert individual documents to a different format, include -at program in the


-st parameter text (see -at address on page 448).

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Processing incoming email messages

Processing incoming email messages


To process incoming email messages, use the mailin server.
Features of the mailin server
The mailin server scans a mailbox for incoming email messages. When an email
message arrives, the mailin server can add its contents as an entry in the
Columbus OM queue. You can control how the entry is processed by specifying
the medium property that is applied to it.
The mailin server can apply special processing to specific types of email message:

It can process the attachments to an email message, by using the instructions


that you put in the email message itself.

It can process delivery failure messages that have been received in reply to
email messages sent by the Columbus OM mailer server.

After the mailin server has processed an email message, it deletes it from the
mailbox.
To monitor two or more mailboxes, you can create multiple mailin servers.

Configuring the mailin server


To configure the mailin server, add a new server with the following properties.
For more information about how to add a server, see Adding servers on page 98.
General properties
Property

Value

Server Name

A name to identify the server.

Program

Select mailin.

Accessing the mailbox


Property

Value

POP3_Server

The name of the computer that the mailbox that the server
is to process is on.

POP3_User

The name of the user that the mailbox belongs to.

POP3_Pass

The encrypted version of the password to access the


mailbox (see To encrypt the password below).

To encrypt the password

At the command line, type:


uqencrypt password

where password is the text to be encrypted.


Columbus OM displays the encrypted version of the password.

COLUMBUS OM INSTALLATION AND CONFIGURATION

451

452

CHAPTER 17

Processing email messages

Processing incoming email messages

Sending replies to email messages


Property

Value

SMTP_Server

The name of a server running a SMTP mail server, such as


Microsoft Exchange.

SMTP_User

The user account from which the replies are to be sent.

SMTP_Domain

The domain name, for example mycompany.com.

For information about the other configuration parameters for the mailin server,
see mailin server configuration parameters on page 459.

Default handling of email messages


All email messages that are not processed automatically (see Automatic mode:
Processing attachments on page 453) or as delivery failures (see Handling delivery
failures on page 455) are handled by the mailin servers default mode.
In default mode, Columbus OM:

adds the text of the email message as a entry in the queue

copies any attachments from the email message, and then puts them in the
queue\document folder

sends a reply to the email message.

Queue entry properties


The queue entry that is generated has these properties:
Property

Description

Alias

Mail from sender


sender is the email address from which the email message
was sent.

Destination

Same value as the mailin servers Destination parameter.

Medium

Same value as the mailin servers Medium parameter.

Owner

Same value as the mailin servers Owner parameter.

Program Id

Same value as the mailin servers Program parameter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Processing incoming email messages

Property

Description

Remark

Subject field of the email message.

Server Info

-sl level -sg group n file1 file2 ... filen

(-sl and -sg appear only if the document-level security


feature is in use.)
level is the value of the mailin servers Security_Level
parameter.
group is the value of the mailin servers Security_Group
parameter.
n is the total number of attachments.
file1 ... filen are the names of the attachments.

Attachment files
Columbus OM puts the attachment files in the queue\document folder. Their
filenames are included in the Server Info property, and they have this format:
xentryid_n.att

entryid is the 7-digit entry id of the entry.

n is the number of the attachment (the first attachment is number 1).

For example, if the original email message has three attachments, and its entry
number is 456, the attachment files are called x0000456_1.att, x0000456_2.att
and x0000456_3.att.

Automatic mode: Processing attachments


To process attachments automatically, you send an email that contains the
attachments and instructions specifying how you want them to be processed. For
example, the instructions might tell Columbus OM to print the first attachment,
and then print and fax the second attachment. Columbus OM can send a reply to
the sender confirming the actions that it has performed.
To process attachments
1

Create an email message, and then set its Subject field to:
ColumbusOM Auto

In the text of the email message, add one section for each attachment to specify
how you want the attachment to be processed, using the syntax shown below.

Send the email message to the mailbox that the mailin server uses (that is, the
user specified by the POP3_User parameter).

COLUMBUS OM INSTALLATION AND CONFIGURATION

453

454

CHAPTER 17

Processing email messages

Processing incoming email messages

Syntax
ATTACHMENT n
DESTINATION text
MEDIUM text
[ALIAS text]
[REMARK text]
[RESPOND]

Repeat this section for each attachment that you want to process. To process a
single attachment in two or more ways, you can specify two or more sections with
the same ATTACHMENT number.
Parameters

Value

ATTACHMENT

The number of the attachment that the instructions apply to. The
first attachment to the email message is number 1.

DESTINATION

The destination of the attachment, for example, the name of a


printer.

MEDIUM

The medium to be applied to the entry, for example, PRINT.

ALIAS

The alias to be applied to the entry.

REMARK

The remark to be applied to the entry.

RESPOND

Include this if you want Columbus OM to send an email


message back to the sender, containing information about the
actions that it performed.

Example

This email message has two attachments and contains this text:

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Processing incoming email messages

ATTACHMENT 1
MEDIUM PRINT
DESTINATION myprinter1
RESPOND
ATTACHMENT 1
MEDIUM MAIL
DESTINATION john@mycompany.com
RESPOND
ATTACHMENT 2
MEDIUM PRINT
DESTINATION myprinter1
RESPOND

From this email message, the mailin server creates these entries in the queue:

Attachment 1 (report1.txt) is added as a print entry, and as a mail entry.

Attachment 2 (SalesNews.doc) is added as a print entry.

It also sends an email message back to the sender, confirming that it has add the
entries to the queue, and indicating the entry numbers.

Handling delivery failures


The mailin server can handle email messages that indicate delivery failures. This
feature works with delivery failures that have been received in response to email
messages that have been sent by the Columbus OM mail server (see Configuring
Columbus OM to send email messages on page 446).
The mailin server handles a delivery failure like this:

It adds the text of the message as an entry in the queue.

It copies the attachments to the queue folders. This means that the attachments
can be accessed by, for example, the Columbus OM dispatch features. The files
are listed in the entrys Server Info property.

It sends a reply to the sender with information about what it has done.

COLUMBUS OM INSTALLATION AND CONFIGURATION

455

456

CHAPTER 17

Processing email messages

Processing incoming email messages

Identifying delivery failures


The mailin server identifies delivery failures by looking in the subject line for two
items:

text such as Undelivered: at the start of the subject line


and

UQ (

(that is, hyphen space UQ space open-parenthesis) anywhere in the subject line. This
indicates that the original email message was sent by the Columbus OM mailer
server. To configure the mailer server so that it adds this text, set its
Check_Delivery parameter to Yes.
Configuring the mailin server to handle delivery failures
Set these parameters:
Parameter

Value

Process_Undeliverable

Yes

Undeliverable_Subject

Specify the text that in the Subject line that marks the
email message as a delivery failure, for example:
Undelivered Message: To specify two or more
items of text (for example, to handle other
languages), separate them by using a semicolon. The
default text is Undeliverable:

Subject_Case_Sensitive Specify Yes or No to indicate whether the check for

the text is case-sensitive or not. The default value is


Yes.
Undeliverable_Dest

Specify the destination value to be assigned to the


entries that fail.

Undeliverable_Medium

Specify the medium value to be assigned to the


entries that fail.

Queue entry properties


The queue entry that is generated has these properties:
Property

Value

Alias

Mail from sender


sender is the email address from which the notification
message was sent.

Destination

Same value of the mailin servers Undeliverable_Dest


parameter.

Medium

Same value of the mailin servers Undeliverable_Medium


parameter.

Original UID

The entry id of the original queue entry.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Processing incoming email messages

Property

Value

Owner

The owner of the original email message. (This value is


available only if the original email message is in the
Completed queue.)

Program Id

Same value as the mailin servers


Undeliverable_Program parameter.

Remark

Subject field of the notification message.

Server Info

-sl level -sg group n file1 file2 ... filen

(-sl level and -sg group are included only if the


document-level security feature is in use, and the original
email message is in the Completed queue.)
level is the original email messages Security_Level

property.
group is the original email messages Security_Group

property.
n is the total number of attachments.
file1 ... filen are the names of the attachments.

COLUMBUS OM INSTALLATION AND CONFIGURATION

457

458

CHAPTER 17

Processing email messages

Processing email messages: Reference

Processing email messages: Reference


mailer server configuration parameters
Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Action_On_Completion command
Action_On_Failure command
Action_On_InCompletion command
Action_On_Postponement command
Action_On_Shutdown command
Action_On_Start command
Action_Pre_Completion command

Commands to be run in response to events. For more information, see


Operating system actions during processing on page 417.
Attempts_Limit number

The maximum number of attempts to process a queue entry before setting its
status to Failed. 0 prevents postponement, failing after the first attempt. The
interval between attempts is set by Postpone_Time.
Check_Delivery Yes|No
Yes adds the text - UQ (entry_id) to the subject line of the email message.

This text can be used by the mailin server to identify the original email message
that caused a delivery failure message to be returned.
Convert_To type

The document type to which the attachments are to be converted, for example
PDF. The implementor must ensure that the suitable conversion utility exists.
Domain domain

The local domain name.


Fail_on_Missing_Atts Yes|No

This parameter controls what happens if an attachment file that has been
specified for an entry cannot be found:

To not send the entry (and set its status to Failed), set this parameter to
Yes.
To send the entry in any case, set this parameter to No.

Message_File filename

The name of a file that contains the text to be used as the body of the email
message.
If this parameter is empty, or the file specified does not exist, Columbus OM
uses the contents of the file that is specified by the entrys -df parameter (or the
text that is specified by the or -dt parameter) as the body text.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Processing email messages: Reference

Postpone_Time number

The delay in seconds between successive attempts to process a queue entry, up


to the maximum determined by Attempts_Limit. The default is 60.
Scan_Interval number

The interval in seconds between successive scans of the queue. The default is
10.
Sender address

The senders email address.


To specify a different senders address when you add an entry, use the -st
parameter (see To specify the senders email address on page 449).
SMTP_Server server

The name of a server running a suitable SMTP mail server, such as Microsoft
Exchange.

mailin server configuration parameters


Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Action_On_Shutdown text

A command to be run when the server is shut down. For more information, see
Operating system actions during processing on page 417.
Destination text

The destination value to be assigned to entries generated in default mode.


The default value is dispatch.
Medium text

The medium value to be assigned to entries generated in default mode.


The default value is dispatch.
Owner text

The owner to be assigned to entries generated in default mode or


Columbus OM Auto mode.
The default value is the user who started the server.
POP3_Pass text

The password for accessing the mailbox.


POP3_Server text

The name of the server that the mailbox is on.


POP3_User text

The name of the user of the mailbox.

COLUMBUS OM INSTALLATION AND CONFIGURATION

459

460

CHAPTER 17

Processing email messages

Processing email messages: Reference

Process_Undeliverable Yes|No

See Configuring the mailin server to handle delivery failures on page 456.
The default value is No.
Program text

The program ID value to be assigned to an entry generated in default mode.


The default value is mailin.
Scan_Interval integer

The frequency (measured in seconds) at which the server scans the mailbox for
incoming email messages.
The default value is 10.
Security_Level integer

The document security level to be assigned to entries generated in default


mode or Columbus OM Auto mode, when the document security feature is
in use.
The default value is the value of the system default Security_Level
parameter.
Security_Group text

The document security group to be assigned entries generated in default mode


or Columbus OM Auto mode, when the document security feature is in use.
The default value is the value of the system default Security_Level
parameter.
Server text

The name of the server. This must be the same as the name of the folder that
the configuration file is in (%UNIQDIR%\servers\server\config.tab).
SMTP_Domain text

The domain name to be used for replies to email messages.


SMTP_Server text

The name of the host that the SMTP daemon or service to be used for sending
replies is on.
SMTP_User text

The user who is the sender of replies.


Subject_Case_Sensitive Yes|No

To make the match against the text that is specified by the


Undeliverable_Subject parameter case-sensitive, specify Yes.
The default value is Yes.
Undeliverable_Dest text

See Configuring the mailin server to handle delivery failures on page 456.
The default value is dispatch.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 17

Processing email messages

Processing email messages: Reference

Undeliverable_Medium text

See Configuring the mailin server to handle delivery failures on page 456.
The default value is dispatch.
Undeliverable_Program text

The program ID value to be assigned to entries generated in Undelivered


mode.
The default value is undevmail.
Undeliverable_Subject text[; text]...

See Configuring the mailin server to handle delivery failures on page 456.
The default value is Undeliverable:

COLUMBUS OM INSTALLATION AND CONFIGURATION

461

462

CHAPTER 17

Processing email messages

Processing email messages: Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

463

C H A P T E R 18

Chapter 18

Configuring a fax
environment

A fax environment works in a similar way to a print environment: you submit a


document to Columbus OM fax instance, and then a fax server sends the
document to a fax modem for processing.
Columbus OM can also receive incoming faxes and distribute them to the
recipients.
Sending faxes

Columbus OM
Explorer

Columbus OM
pending queue

fax modem

telephone
system

fax server
completed
queue

printer for
confirmation copies

You add an entry to the pending queue by using Columbus OM Explorer or the
command line, specifying the document you want to send and the telephone
number that you want to send it to. The medium applied to the entry must match
the medium used by the server that you want to process it.
The fax server checks the pending queue to see if there are any requests that it is to
process. When it finds one, it passes the request to the fax modem, dials the
telephone number and sends the fax. Then it moves the entry to the completed
queue, with its status set to indicate whether it was successful or not.
You can configure Columbus OM to print a copy of the faxes that you send. The
copies are printed by the faxprint server.

COLUMBUS OM INSTALLATION AND CONFIGURATION

464

CHAPTER 18

Configuring a fax environment

Additional features

Reduce the cost of sending a fax by using the least-cost faxing feature. For more
information, see Least-cost faxing on page 467.

Redirect and blacklist fax numbers: For more information, see Redirecting and
blacklisting fax numbers on page 466.

Process fax documents from third-party applications: Fax documents from


third-party applications can be processed by a Columbus OM fax instance by
transferring them from the application to a Columbus OM print instance,
which transfers them to a Columbus OM fax instance. (Documents from
third-party applications cannot be transferred directly to a Columbus OM fax
instance.)

Receiving faxes
To
From

fax modem
receives fax, and
then transfers it to
Columbus OM

Columbus OM
fax server
pending queue

faxmaster

message to
recipient

faxprint

printer

When a fax modem receives a fax, the fax server that controls the modem receives
the document and puts it in the pending queue, marked as an incoming fax.
The document can then be printed, sent onto to the recipient, or both.

Printing is controlled by the faxprint server. It scans the queue for incoming
faxes, and then prints them.
Distribution is controlled by the faxmaster server. When it finds an incoming
fax in the queue, faxmaster compares the fax number that the document was
sent from against a list that you set up. The list tells faxmaster who the
recipient should be (for example, if the fax is from 0123 - 444 555, then the
recipient is Mary Smith). Then faxmaster sends an email to the recipient,
and it can also pass the document to faxprint for printing.

Supported fax modems


Columbus OM these modem types:

Ascom Hasler Fax Gateway

Ascom Hasler AM2496F

Multitech modems

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

D&CE Faxbox or Faxbox30

Class 2 (Rockwell chipset) US Robotics Sportster modems.

COLUMBUS OM INSTALLATION AND CONFIGURATION

465

466

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

Configuring Columbus OM to send faxes


1

Add a fax server for each fax modem that you want Columbus OM to use.
Make sure that Outgoing Allowed option is selected.
See Adding servers on page 98.

Create a file called out_commands that contains the commands to initialize the
modem for sending a fax. For more information about the commands to use,
see the modems documentation.

Configuring the connection


To

Do this

set a dial prefix

Set the Dial_Prefix parameter.


Columbus OM puts the prefix in front of
every fax number (for example, 9 for an
outside line): users cannot remove it.
Set the Attempts_Limit parameter. To
use the default retry strategy as
described below, set it to 0.

specify the maximum number of


attempts to be made to send a fax

specify the control codes that might be Set the Lost_Exchange parameter. To
received from the modem to indicate
specify two or more control codes,
that it has lost contact with the exchange separate them by using a space
character.
control attempts to reset the modem

Set Max_Resets to the maximum


number of attempts to make, and
Reset_Interval to the interval (in
minutes) at which the attempts are to be
made.

Redirecting and blacklisting fax numbers


Faxes can be redirected to different fax numbers, for example, if the recipient has
changed their fax number.
You can also make certain fax numbers unavailable (for example, international
numbers or premium rate numbers), so that if a user tries to send a document to
one of these numbers, Columbus OM rejects it.
To redirect or blacklist fax numbers
1

In the %UNIQDIR%\media\fax folder, create a file called blacklist.

In the file, create one entry for each fax number that you want to redirect or
blacklist. Each entry comprises three fields, separated by spaces.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

Field

Value

The fax number that you want to redirect or blacklist.

To redirect the fax to a different number, specify the number.


To reject the document, leave this field empty

Any text to be added to the entrys Remark field, for example:


Redirected to 012 987 6543.

Example entries
09875556666 01237778888
0123334444

"Redirected to new fax number"


"Fax not sent: Number blacklisted"

In this example:

faxes that a user sends to 0987 555 6666 are redirected to 0123 777 8888

faxes that a user sends to 012 333 4444 are not sent.

Least-cost faxing
Least-cost faxing enables requests sent from one Columbus OM fax instance to be
processed by a different Columbus OM fax instance one that has the lowest
telephone call cost to the final destination of the fax. For example, to send a fax
from France to the USA, the document could be added to a Columbus OM fax
instance in France; Columbus OM transfers the request to the instance in the USA;
and then that instance faxes the document. A national (or even local) call is used
instead of an international one.
To configure Columbus OM for least-cost faxing
1

Edit the remote.tab file in the Columbus OM fax instances config folder. (If
the file does not already exist, you can create it.)

Add an entry for each remote host. See the entry format and example below.

In the Columbus OM fax instance, set each fax servers Ack_Medium parameter
to Print.

Add a netmaster server to the Columbus OM fax instance. Columbus OM


automatically configures it for you. If you need to change the configuration, see
Configuration for distributed printing on page 113.

Entry format for remote.tab

Each entry comprises two fields, separated by spaces.


Field

Value

A dialling code. To mark the end of the dialling code, use *. For example,
001* identifies all faxes send to a number starting with 001.

The Columbus OM print instance: the hostname and the instance name,
separated by a colon.

COLUMBUS OM INSTALLATION AND CONFIGURATION

467

468

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

Example remote.tab file


001*
0033*
*

usa:fax1
france:fax1
uk:fax1

This example shows a least-cost faxing solution that might be used by a company in
the UK, that also has offices in New York and Paris.

Documents sent to fax numbers that start with 001 are transferred for
processing by the fax1 instance on the usa host, from where they can be sent
at local or national callrates.

Similarly, documents set to fax numbers that start with 0033 are transferred to
the fax1 instance on the france host.

All other documents are processed by the fax1 instance on the uk host.

Polling (Faxback)
To support polling (also known as faxback), where someone calls your fax
number and in response, you fax back a document, set these parameters:
Parameter

Value

Poll_Doc

The path and name of the document to send.

Poll_Type

The format of the document:

Poll_Wait_Ack

Format

Set Poll_Type to

ASCII text

Text

Hasler T4

T4

The maximum time in minutes that the server will wait for an
acknowledgement signal after responding to the poll request.
The minimum value is 1.

Printing confirmation copies


This feature is available for fax devices that use either the pfax or the haslerfx
server.
Set these parameters:
Server

Parameter

Value

the fax server

Print_Outgoing

Yes

Medium_for_Print

FaxPrint

Medium

FaxPrint

faxprint

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

Print-only fax documents


This feature is available for fax devices that use either the pfax or the haslerfx
server.
To only print documents that are added to the Columbus OM fax queue, and not
send them, do the following:
1

Set these parameters:


Server

Parameter

Value

the fax server

Medium_for_Print

FaxPrint

faxprint

Medium

FaxPrint

When you send the fax, include the -po parameter.

Redirecting documents from a print instance to a fax instance


If, for some reason, documents can be added to a Columbus OM print queue but
they cannot be added directly to a Columbus OM fax queue, you can send faxes by
setting up the print instance to redirect documents to the fax instance.
For example, some third-party applications can integrate with a Columbus OM
print instance but they cannot integrate with the Columbus OM fax instance. To
enable documents from these applications to be sent as faxes, use the method
described below.

third-party
application

Columbus OM
print instance

Columbus OM
fax instance

fax modem

To use this feature, the print and fax instances must be on the same host.
To add a printer server that redirects documents to a Columbus OM
fax instance
1

Using Columbus OM Explorer, add a new printer server to the Columbus OM


print instance. See Adding a printer server on page 143.

In the Add New Printer dialog box, select Fax.

Click the Details tab.

Set the Instance the name of the Columbus OM fax instance to be used.

To specify a default fax number to be used if one is not specified with an entry,
set Fax number.

Click OK.

In the Columbus OM fax instance, create a server that uses the netmaster
program, and set its Medium parameter to print.

COLUMBUS OM INSTALLATION AND CONFIGURATION

469

470

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

Make sure that the Columbus OM fax instances


%UNIQDIR%\media\media.tab file contains an entry for print.

Creating graphics for faxed documents


To embed a graphics file into a faxed document, it must be in the T4 format that is
supported by the fax server that you are using. Columbus OM includes programs
for converting a graphic file to the T4 format of each modem type. The programs
are in the programs\tools folder.
The recommended method for getting best results when creating graphics to
include in a faxed document is as follows:
1

Create the graphic, and print it at the required size.

Fax the page to a Columbus OM fax modem that supports incoming calls.

Look in the Columbus OM fax queue for the fax, and make a note of its entry
number.

Look in the queue\document folder for a file called xnnnnnnn.bd where


nnnnnnn is the number of the queue entry, and make a note of this filename.
(It might have zeroes in front of it to make it seven digits long, for example:
0001234.bd.)

At the command line, type:


has2pcx filename -D

where filename is the filename noted in step 4.


This program is in the programs\tools folder.
Columbus OM creates a PCX-format file called xnnnnnnn.pcx.
6

Check and modify the file as required by using a graphics program (for
example, PaintBrush).
If the file needs to be transferred to another computer for modification, it must
be transferred as a binary file.

Return the modified file to the host.


The file can be renamed if required, but you must keep retain the .pcx
extension.

Type:
pcx2has file.pcx file.has [-F][-M rows]

where file is the name of the PCX-format file, without the .pcx extension.
Columbus OM creates a Ascom Hasler T4-format file called file.has.

Include the -F flag if the graphic is the correct aspect ratio for fine mode.
Use the -M rows option to truncate the end of the graphic when trailing
white space is included.

The next step depends on what sort of modem the file is to be used for:
For an Ascom Hasler HFU modem

Copy the file to the %UNIQDIR%\media\fax\logo folder.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

For a Class 2 modem


1

Convert the Ascom Hasler T4 format file to the Class 2 T4 format by typing:
has2pfax file.has

Columbus OM creates a file called file.g1.


2

Copy file.g1 to the %UNIQDIR%\media\fax\logo folder.

For a D&CE Faxbox modem


1

Convert the Ascom Hasler T4 format file to the D&CE T4 format by typing:
has2dce file.has

Columbus OM creates a file called file.dce.


2

Copy file.dce to the %UNIQDIR%\media\fax\logo folder.

Converting graphic files to fax formats


Converting from Hasler T4 fax format
To convert raster graphics files from Hasler T4 fax format to other formats, use
these commands:
To convert to

Command syntax

Name of
converted file

D&CE T4 fax format

has2dce file

file.dce

PCX format

has2pcx file [-D]

file.pcx

Class 2 T4 fax format

has2pfax file

file.g1

Parameters
file

The name of the file that you want to convert.


-D

Convert from coarse to fine format by doubling the number of rows and
halving the height of the pixels.
Converting from PCX format
To convert a raster graphic file from PCX format to Hasler T4 fax format, use this
command:
pcx2has file.pcx file.has [-F] [-Mnumber]
Parameters
file

The name of a file that is to be converted. The converted file is called


file.has.
-F

If the PCX file is in Fine format, include this parameter.

COLUMBUS OM INSTALLATION AND CONFIGURATION

471

472

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

-Mnumber

Truncate number rows of training white space.

Formatting the document


To

Do this

set the size of the left margin

Set the Left_Margin parameter to the


width required, in units: 1 unit =
1/200inch. For example, one-inch is 100
units.
This feature is supported only on pfax
modems.

print line numbers at the start of each


line

Embedding
commands in
documents

Set the Line_Number parameter to Yes.

Embedded commands in a document enable you to apply overlays; insert graphics


and font information; set the Remark field (text that is displayed with the document
in Columbus OM Explorer, but is not sent).
You can use embedded commands if the document is in ASCII format.
Using the commands

In the document, each command must be on a line on its own.

ALIAS: Changing the alias

Support

Class 2 and Ascom Hasler HFU.

Syntax

.ALIAS text

Replace text with the new alias


.DESTINATION: Setting the fax number

Support

Class 2 and Ascom Hasler HFU.

Syntax

.DESTINATION fax_number

Replace fax_number with the number of the fax machine that the
document is to be sent to.
.FONT: Changing the font

Support

Class 2 and Ascom Hasler HFU.

Syntax

.FONT font_file

Replace font_file with the name of a font configuration file,


without its filename extension. The file must be:

in the Columbus OM fax instances


media/fonts/pfaxfonts folder on the host computer
have the filename extension: .cfn

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

.GRAPHIC: Including a graphic

Support

Class 2, Ascom Hasler HFU, and D&CE Faxbox

Syntax

.GRAPHIC graphics_file

Replace graphics_file with the name of the graphics file. The


graphics file must be:

in the native T4 format for the fax machine (Columbus OM


includes a program that can convert PCX files into T4 format)
in the Columbus OM fax instances media/fax/logo folder
on the host computer
have a filename extension that matches the type of fax
machine:

Fax machine

Filename extension

pfax

.pfax

haslerfx

.has

faxbox

.dce

.OVERLAY: Applying an overlay

Support

Class 2

Syntax

.OVERLAY file

Replace file with the name of the file to be applied. The overlay
file must:

be in the Columbus OM fax instances media/fax/logo


folder
have the file extension .pfax.

.OWNER: Setting the Owner property

Support

Class 2 and Ascom Hasler HFU

Syntax

.OWNER login_id

Replace login_id with the login id of the owner.


.PROGRAM: Setting the Program property

Support

Class 2 and Ascom Hasler HFU

Syntax

.PROGRAM source_program

Replace source_program with the name of source program.


.REMARK: Setting the Remark property

Support

Class 2 and Ascom Hasler HFU

Syntax

.REMARK "text"

Replace text with the remark to be assigned.

COLUMBUS OM INSTALLATION AND CONFIGURATION

473

474

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

Using substitution variables in documents


Substitution variables enable you to include information such as the date and time,
in a document. These are some of the substitution variables that you can use when
sending a fax:
Substitution variable

Replaced with

%DATE(MON DD YEAR)

The date when the document is sent, for example:


Jan 31 2012.

%TIME

The time when the document is sent, for example:


12:30:00.

%DATE_CREATED

The date when the document was added to the queue.

%OWNER

Your Columbus OM username.

For information about other date and time formats, and other substitution
variables, see Substitution variables on page 603.
Example

This example shows how embedded commands and substitution variables can be
used in an document file:
.OVERLAY logo
SENT:

%DATE(MON DD YEAR) %TIME(HH:MM)

TO:
FROM:

John Smith
Mary Brown

TOTAL: %PAGES pages


Dear Mr Smith,
Please find attached a copy of the document you asked for.
Regards
.GRAPHIC marysign
M. Brown

Adding coversheets
You can add a one-page coversheet to the front of a document. Users can add a
different coversheet when they send a fax, which will replace the default one.

Creating a
coversheet file

Create a file that contains the information you want on the coversheet. See
Creating a coversheet file below.

Set the Coversheet parameter for the fax server to the path and filename of
the coversheet.

File format
The coversheet file must be in ASCII (plain text), PCL or T4 format.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring Columbus OM to send faxes

File location
The coversheet file must be on the same host computer as the Columbus OM fax
instance.
Filename extension
The coversheet file must have one of these filename extensions, to identify what
format it is:
ASCII

Any extension, except .pcl, .pfax and .has.

PCL

.pcl

pfax T4

.pfax

haslerfx T4

.has

Substitution variables
A coversheet that is in ASCII format can include substitution variables to enable
entry-related information to be added when the coversheet is sent. For a list of the
substitution variables, see Substitution variables on page 603.
Embedded commands
A coversheet in ASCII format can include embedded commands to include
graphics, change fonts and so on. For more information about embedded
commands, see Embedding commands in documents on page 472.

For the pfax program, the coversheet can include any of the Columbus OM
fax facilitys embedded commands.
For the haslerfx program, the coversheet can include only the .GRAPHIC and
.FONT commands.

COLUMBUS OM INSTALLATION AND CONFIGURATION

475

476

CHAPTER 18

Configuring a fax environment

Sending fax documents

Sending fax documents


To send a document as a fax, add it as an entry to the Columbus OM queue by
doing one of the following:

Use Columbus OM Explorer. For more information, see Sending faxes using
Columbus OM Explorer below

Use the command line. for more information, see Sending faxes using the
command line on page 477.

Document formats for faxing


You can send documents that are in any format, if the format is supported by the
type of fax machine that you are using:
Fax machine types
Format

Class 2

Ascom
Hasler HFU

D&CE Faxbox

ASCII

Bitmap

HP PCL3

HP PCL5

Paintbrush (PB format)

Paintbrush (PCX format)

PostScript

Sending faxes using Columbus OM Explorer


To send a document by fax, add it in the same way as a print document: connect to
the Columbus OM fax instance that you want to use, and then click Add Entry on
the File menu.
The Add New Entry dialog box appears.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Sending fax documents

Document properties
Property

Description

Destination

The fax number to which you want to send the document.

Medium

The medium associated with the server which you want to


process the document; usually fax.

Changing the document details


h

To

Do this

add a coversheet (pfax and haslerfx


only)

Click the Attributes tab. In the


Parameters box, type:
-co filename

Replace filename with the name of the


coversheet to be added.
apply an overlay to selected pages (pfax See page 478.
and haslerfx only)
print the document, but not send it

On the Attributes tab, type -po in the


Parameters box.

Sending faxes using the command line


To add or change entries in the fax queue by using the command line, use the afq
command.
Syntax for adding an entry
afq [documents] destination [option...] [qualifier...]

Syntax for changing an entry


afq entry_id option... [qualifier...]

Specifying the documents


To specify the documents that you want to process, see Specifying the documents
on page 216.
Specifying the destination
Use one of these keywords to specify the destinations to be used. Columbus OM
adds a separate queue entry each destination. For multiple documents and multiple
destinations, Columbus OM sends the first document to all destinations, then the
second document, and so on.
-ADDRESS_FILE|-af file

The telephone numbers to which you want to send the documents are listed in
the file that you specify. In the file, each telephone number must be on a
separate line.

COLUMBUS OM INSTALLATION AND CONFIGURATION

477

478

CHAPTER 18

Configuring a fax environment

Sending fax documents

-ADDRESS_TEXT|-at fax_number

The destination is the specified fax number.


Specifying the options
-COVER_SHEET|-cs file

The path and name of a file that contains a coversheet which is to be sent at the
head of each source document. If the file is in the
%UNIQDIR%\media\fax\covers folder, you can omit the path.
-FILE_TYPE|-ft encoding

The encoding of the source document, one of:


Encoding

Supported by these servers

TEXT

Plain text

pfax

haslerfx

faxbox

PS

PostScript

pfax

haslerfx

faxbox

PCL

HPs PCL v.3

pfax

haslerfx

HP

HPs PCL v.5

pfax

haslerfx

faxbox

-MEDIUM|-m medium

The transmission medium, normally FAX.


-OVERLAY|-ovn file|OFF

Overlays to be applied to pages of the document.


To

Use

apply an overlay to page n, and all


pages that follow it

-ovn [file]

change the overlay at page n

-ovn [file]

Make sure that there is no space


between -ov and the number.
You can repeat the -ov parameter up
to a maximum of ten times. Each new
overlay replaces any overlay already
in use.

turn off the overlay

-ov OFF

file is the full path and name of the file that contains the overlay.

If the file is in the %UNIQDIR%\media\fax\logo folder, and its name is


file.pfax or file.has (depending on the fax server being used), you can
omit the path and filename extension.
For example:
-ov1 draft.img

Sends the document with draft.img overlaid on every page.


-ov1 logo.img -ov2 draft.img -ov5 OFF -ov7 logo.img

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Sending fax documents

Sends the document with logo.img on page 1; draft.img on pages 2, 3 and 4;


no overlay on pages 5 and 6; logo.img on page 7 and the rest of the pages to
the end of the document.
-PRINT_ONLY|-po

The entry is to be printed, not transmitted.


-SOURCE_HOST|-sh host

The machine on which the entry originated.


For more information about the following options, see Specifying the options on
page 217:
-ALIAS|-as string
-CHAIN|-c [entry_id]
-CHILD
-COPIES|-cp number
-FROM_PAGE|-fp number
-HELP|-h
-HOLD|-h
-NO_COPY|-nc
-ORIGINAL_UID|-ou entry_id
-OWNER|-o user_id
-PAGE_LENGTH|-pl number
-PRIORITY|-p number
-PROGRAM|-pg string
-RELEASE|-r
-REMARK_FILE|-rf file
-REMARK_TEXT|-rt string
-REPORT_UID|-ru file
-RETENTION_DAYS|-rd number
-SECURITY_LEVEL|-sl {number|text}
-SECURITY_GROUP|-sg text
-TIME|-t time
-TO_PAGE|-tp number

Specifying the qualifiers


For more information about these parameters, see Common parameters on
page 602.
-ARCHIVE|-ar [number]
-COMPLETE_QUEUE|-cq
-NO_BANNER|-nb
-NO_WARNING|-nw
-QUEUE_NAME|-qn instance
-SILENT|-si

COLUMBUS OM INSTALLATION AND CONFIGURATION

479

480

CHAPTER 18

Configuring a fax environment

Receiving faxes

Receiving faxes
Configuring Columbus OM to receive faxes
1

Set these parameters for faxmaster:


Parameter

Value

Incoming_Allowed

Yes.

Action_on_Start

An operating system command to send a message to


the recipient.

Add a fax server for each fax modem that might receive faxes. Make sure that
the Incoming Allowed option is selected.

Configure what you want the fax server to do with the incoming faxes:

To

See

print the document

Printing incoming faxes below

send a message to a user to tell them


that the fax is available

Distributing incoming faxes on


page 481

Create a file called in_commands that contains the commands to initialize the
modem for receiving a fax (see the examples below). For more information
about the commands to use, see the modems documentation.

To specify the in commands

Specify these commands in the fax servers in_commands file.

For pfax (class 2):


ATE0N0L1M1&K4S0=0
AT+FCLASS=2;+FCR=1;+FBOR=0;+FDCC=1,3,0,0,0,0,0,3

For Multitech (class 2):


ATE0L1M1&E4S0=0
AT+FCLASS=2;+FCR=1;+FBOR=1;+FCQ=1;+FDCC=1,5,0,0,0,0,0,5

For US Robotics (class 2.0):


ATE0N0L1M1S0=0
AT+FCLASS=2.0;+FCR=1;+FBO=1;+FCC=1,5,0,0,0,0,0,7
AT+FNR=1,1,1,1

Printing incoming faxes


1

Check what value the faxprint servers Medium parameter is set to, and then
set the fax servers Medium_for_RX parameter to the same value.

Set faxprints Attributes parameter to the print command to be used. The


command can include substitution variables. To identify the fax document, use
the %s variable, for example: lp -dlaser1 -n %s.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Receiving faxes

Example
This example configuration file for faxprint shows values that product suitable
output for printing faxes on a HP LaserJet 4050 printer that supports 600dpi.
# Key
# ---------#
Server
Medium
Attributes
New_Page
Pre_Doc

Value
Disp?
-------------------------------- -----

faxprint
No
Faxprint
Yes
"aeq -at hp4 -df %s -qn print"
Yes
\f\033*p0X\033*p8Y\033*b1M\r\n
Yes
\033E\0339\033&l0L\033&l0E\033*t600R\033*p0X\
033*p8Y\033*b1M\r\n
Yes
Post_Doc
\033*rB
Yes
Strtgraf
\033*b%dW
Yes
Prntmode
Horizontal
Yes
Trunc_White Yes
Yes
Hdots
4760
Yes
Hdensity
2
Yes
Vdensity
3
Yes
Char_len
8
Yes
Parity
None
Yes
Scan_Dir
Down
Yes
LaserjetII No
Yes

(The value for the Pre_Doc parameter should be on a single line in the actual file.)

Distributing incoming faxes


1

Check what value the faxmaster servers Medium parameter is set to, and then
set the fax servers Medium_for_RX parameter to the same value.

In the %UNIQDIR%\servers\faxmaster folder, create a file called


sender.tab.

In the file, add one line for each source of incoming faxes, as described below.

Entry format
For each entry, specify these fields, separated by spaces.
Field

Value

The originating fax number, by which the sender can be recognized. To


cover all the fax numbers that are not otherwise mentioned, create an entry
for default.

The senders name. If it contains spaces, enclose it in quotes "...".

The user id who will be the owner of faxes from this source.

The medium to be used for faxes received from this source (usually
FaxPrint).

COLUMBUS OM INSTALLATION AND CONFIGURATION

481

482

CHAPTER 18

Configuring a fax environment

Receiving faxes

Field

Value

The recipients name. If it contains spaces, enclose it in quotes "...".

The path where incoming faxes from this source are to be copied. You can
include substitution variables. If the path or file name contain spaces,
enclose it in quotes.

Example
"0123 444 555" "John Smith" mab FaxPrint "Mary Brown" C:\Faxes
default
""
rec FaxPrint "Reception" C:\RecFaxes

In this example:

faxes received from 0123 444 555 are distributed to the user mab, and copied to
C:\Faxes.
faxes received from all other numbers are distributed to the user rec, and
copied to C:\RexFaxes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Configuring a fax environment: Reference


fax server types
Fax modem

Server

See

Ascom Hasler

Haslerfx

faxbox servers:
Faxbox modems
below

Ascom Hasler AM2496F

Pfax

page 490

Multitech modems

Pfax

page 490

D&CE Faxbox or Faxbox30

Faxbox

page 483

Class 2 (Rockwell chipset)

Pfax

page 490

faxbox servers: Faxbox modems


The faxbox server implements a connection to a D&CE Faxbox or Faxbox 30
modem: it (a) monitors the queue for entries with a medium of FAX, and transmits
them, and (b) receives incoming faxes, and adds entries with a medium of FAX_IN
to the queue.
Configuration file
%UNIQDIR%\servers\server_name\config.tab
Configuration parameters
Action_On_Completion command
Action_On_Failure command
Action_On_Postponement command
Action_On_Shutdown command
Action_On_Start command

Commands to run in response to events. See Operating system actions during


processing on page 417.
Command_Char character

The command character recognized by the modem; usually set to a caret (^).
Default_File_Type TEXT|HP
TEXT (the default) to assume that fax documents without an explicit type are
encoded as plain ASCII text; HP to assume that the encoding is HPs PCL5.
Device string

The connection to the output device; one of:


device

a direct connection to a local device, for


example /dev/ttyN.

NETWORK host port linger

a network connection via TCP/IP and a


terminal server to a remote device.

COLUMBUS OM INSTALLATION AND CONFIGURATION

483

484

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Dial_Prefix code...

A sequence of control codes sent to the modem prior to the fax_number, for
example to select an external telephone line.
Faxbox30 YES|NO
YES (the default) if the modem is a Faxbox 30 model; NO if it is a Faxbox model.
Flow_Control TRANSPARENT|NORMAL
TRANSPARENT if the modem has been configured for Transparent flow control;
NORMAL (the default) otherwise.
Incoming_Allowed YES|NO
YES to accept incoming documents and process them as specified by
Incoming_To; NO (the default) to ignore such entries.
Incoming_Format FINE|COARSE|ANY
FINE to accept faxes in fine T4 format; COARSE to accept coarse T4 format; ANY
(the default) to accept either format.
Incoming_Speed 2400|4800|9600

The maximum baud rate at which to accept incoming faxes. The default is
9600.
Incoming_To HOST|MONITOR|BOTH

Specifies how incoming documents are processed:


Value

Description

HOST

Adds incoming documents to the pending queue with the medium


specified by Medium_For_RX.

MONITOR

Prints incoming documents on the printer that is attached to the


modem.

BOTH

Prints the incoming documents, and adds them to the queue.

The default value is HOST.


LFCR YES|NO
YES to transpose the CR LF code sequence to LF CR; NO (the default) to leave it
unchanged.
Line_Numbers YES|NO
YES to insert a number at the start of each line of text, ensuring that no material
is lost in transmission; NO (the default) otherwise.
Max_Tries number

The maximum number of attempts to send a fax before setting the entrys
status to Failed.
Medium FAX

The medium name that identifies the queue entries that the server processes.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Medium_For_RX FAX_IN

The medium name for queue entries which are automatically created to handle
incoming documents.
Monitor_Format 8|24

The modem has an attached Epson dot-matrix monitor printer, whose


resolution is either 8 or 24 pins. The default is no monitor printer.
Monitor_Outgoing YES|NO
YES to print copies of outgoing faxes on the monitor printer attached to the
modem; NO (the default) otherwise.
Outgoing_Allowed YES|NO
YES to process queue entries with the medium specified as FAX; NO (the default)

to ignore such entries.


Resolution FINE|COARSE
FINE to send faxes in fine T4 format; COARSE (the default) to use coarse T4

format.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
Timeout number

The delay (measured in minutes) after which a modem connection attempt is


deemed to have failed. A value of zero or null implies no limit.

faxmaster servers: Handling incoming fax entries


The faxmaster server monitors the queue for entries with a medium of FAX_IN,
and handles their distribution. For more information, see Receiving faxes on
page 480
Configuration file
%UNIQDIR%\servers\server_name\config.tab
Configuration parameters
Action_On_Completion command
Action_On_Start command

Commands to run in response to events. See Operating system actions during


processing on page 417.
Incoming_Allowed YES|NO
YES to process queue entries with the medium specified by Medium; NO (the

default) to ignore such entries.


Medium FAX_IN

The medium name which marks a queue entry as suitable for processing by this
server.

COLUMBUS OM INSTALLATION AND CONFIGURATION

485

486

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Outgoing_Allowed YES|NO
YES to periodically scan the folder specified by Outgoing_Directory and
process files of appropriate format that are found there; NO (the default) to
ignore the Outgoing_Directory parameter.
Outgoing_Directory folder

The full path of a folder which is periodically scanned under the control of the
Outgoing_Allowed parameter. The folder can include substitution of
operating system variables ${name} and Columbus OM variables %name.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
Wait_Time number

The interval in seconds between successive scans of the queue.

haslerfx servers: Ascom Hasler modems


The haslerfx server implements a connection to an Ascom Hasler HFU Class 3
modem. It:

monitors the queue for entries with a medium of FAX, and transmits them, and
receives incoming faxes, and adds entries with a medium of FAX_IN to the
queue.

Configuration file
%UNIQDIR%\servers\server_name\config.tab
Configuration parameters
Ack_Medium PRINT

The name of the medium used for returning acknowledgements to remote


hosts as part of a least-cost scenario.
Action_On_Completion command
Action_On_Failure command
Action_On_Postponement command
Action_On_Shutdown command
Action_On_Start command

Commands to be run in response to events. For more information, see


Operating system actions during processing on page 417.
Attempts_Limit number

The maximum number of attempts (099), to process a queue entry before


setting its status to Failed. The interval between attempts is set according to
telecommunications industry recommendations.
To use the default retry strategy, specify 0: Columbus OM tries to send the fax
at intervals for the next 48 hours. If it still cannot send the fax after 48 hours, it
sets the documents status to Failed, and moves it to the completed queue.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Coversheet file

The name of a file in %UNIQDIR%\media\fax\covers containing a page which


is sent at the front of outgoing documents which do not specify an explicit
coversheet.
Default_File_Type TEXT|HP
TEXT (the default) to assume that fax documents without an explicit type are
encoded as plain ASCII text; HP to assume that the encoding is HPs PCL5.
Device string

The connection to the output device; one of:


device

a direct connection to a local device, for


example /dev/ttyN.

NETWORK host port linger

a network connection via TCP/IP and a


terminal server to a remote device.

Dial_Prefix code...

A sequence of control codes sent to the modem prior to the fax_number, for
example to select an external telephone line.
Incoming_Allowed YES|NO
YES to accept incoming documents and add them as queue entries with the
medium specified by Medium_For_RX; NO (the default) to ignore such entries.
Left_Margin number

The distance by which the text of an outgoing fax is shifted to the right,
establishing a blank left-hand margin. A value of 200 represents one inch; the
default is zero.
Line_Numbers YES|NO
YES to insert a number at the start of each line of text, ensuring that no material
is lost in transmission; NO (the default) otherwise.
Lost_Exchange code code...

A space-separated list of control codes, any of which might be received from


the modem to indicate that contact with the exchange has been lost. If any of
the codes is received while a document is being transmitted, the server is shut
down.
Max_Resets number

The maximum number of consecutive attempts to reset the modem, for


monitoring purposes, before shutting down the server. The interval between
attempts is set by Reset_Interval. A value of zero or null invokes the default
of 6.
Medium FAX

The medium name which marks a queue entry as suitable for processing by this
server.
Medium_For_Print FAXPRINT

The medium name for queue entries which are automatically created to handle
printed confirmation of outgoing documents.

COLUMBUS OM INSTALLATION AND CONFIGURATION

487

488

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Medium_For_RX FAX_IN

The medium name used when incoming documents are queued.


Outgoing_Allowed YES|NO
YES to process queue entries with the medium specified as FAX; NO (the default)

to ignore such entries.


Output_Filter command

An operating system command to post-process documents before they are


transmitted; otherwise, the documents are sent unchanged. The command can
include substitution of operating system variables ${name} and Columbus OM
variables %name, and must work as a pipe, reading data on stdin and writing
filtered data on stdout.
Poll_Doc file

The full path of a file transmitted in response to a poll request from the modem.
The file can include substitution of operating system variables ${name} and
Columbus OM variables %name. See also Poll_Type.
Poll_Type TEXT|T4
TEXT (the default) if the file specified by Poll_Doc is encoded as plain ASCII
text; T4 if the encoding is Hasler T4 format.
Poll_Wait_Ack number

The delay (measured in minutes) after which a poll response attempt is deemed
to have failed. The default is 2.
Print_Outgoing YES|NO
YES to create a queue entry, with the medium specified by Medium_For_Print,
to print a confirmatory copy of each outgoing document; NO (the default)
otherwise.
Reset_Interval number

The delay (measured in minutes) between successive attempts to reset the


modem, for monitoring purposes, up to the maximum determined by
Max_Resets. A value of zero or null suppresses monitoring attempts.
Security_Level number

The security level to be applied to entries. The security levels that you can use
are stored in the seclev.tab file.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
Update_Time YES|NO
YES (the default) to periodically adjust the modems internal clock to reflect
system time on the Columbus OM host; NO otherwise.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

haslerpr servers: Printing fax documents


The haslerpr server monitors the queue for entries with a medium of FAXPRINT,
and sends them to a printer.
Configuration file
%UNIQDIR%\servers\server_name\config.tab
Configuration parameters
Attributes command

An operating system command which prints a queue entry. The command can
include substitution of operating system variables ${name} and Columbus OM
variables %name, and also the special value %s (the document file).
Char_Len 7|8

Use 7 if the printer requires binary data to be sent in seven-bit chunks; use 8
(the default) otherwise.
Hdensity 1/3|1/2|1|2|3

The horizontal scaling factor.


Hdots number

The maximum number of dots that the printer can output horizontally across a
page.
LaserJetII YES|NO
YES if the printer is compatible with an HP LaserJet II; NO (the default)

otherwise.
Medium FAXPRINT

The medium name which marks a queue entry as suitable for processing by this
server.
New_Page code...

The sequence of control codes to cause the printer to start a new page.
Parity ODD|EVEN|NONE

Controls the parity bit on data sent to the printer.


Post_Doc code...

The sequence of control codes to reset the printer after printing a document.
Pre_Doc code...

The sequence of control codes to initialize the printer prior to printing a


document.
PrntMode HORIZONTAL|VERTICAL
HORIZONTAL (the default) if raster graphics are printed as a horizontal line;
VERTICAL if raster graphics are printed in the vertical direction specified by
Scan_Dir.

COLUMBUS OM INSTALLATION AND CONFIGURATION

489

490

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Scan_Dir UP|DOWN

If PrntMode is VERTICAL: UP if scanning is upwards; DOWN if scanning is


downwards.
Security_Level number

The security level to be applied to entries. The security levels that you can use
are stored in the seclev.tab file.
Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.
StopGraf code...

The sequence of control codes to deselect raster mode at the end of a graphical
line.
StrtGraf code...

The sequence of control codes to select raster mode at the start of a graphical
line.
Trunc_White YES|NO
YES to truncate trailing white space on a page; NO (the default) otherwise.
Vdensity 1/3|1/2|1|2|3

The vertical scaling factor.

pfax servers: Ascom Hasler and US Robotics fax modems


The pfax server connects to an Ascom Hasler AM2496F or US Robotics Class 2
modem.
Configuration file
%UNIQDIR%\servers\server_name\config.tab

Configuration parameters
Ack_Medium PRINT

The name of the medium used for returning acknowledgements to remote


hosts as part of a least-cost scenario.
Action_On_Completion command
Action_On_Failure command
Action_On_Postponement command
Action_On_Shutdown command
Action_On_Start command

Commands to be run in response to events. For more information, see


Operating system actions during processing on page 417.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Attempts_Limit number

The maximum number of attempts, in the range 032767, to process a queue


entry before setting its status to Failed. The interval between attempts is set
according to telecommunications industry recommendations. A value of zero
or null causes the entry to be failed after the first attempt.
Banner text

(If Banner_Reqd is YES.) Text to be printed at the top of each page. You
include operating system variables ${name} and Columbus OM substitution
variables %name. For example, %UID prints the entry number and %TIME prints
the current time.
Banner_Reqd YES|NO
YES print a banner line at the top of every page. The format of the banner, with
text specified by the Banner parameter, is:
date

text

Page N of M

The default value is YES.


Banner_Width number

The page width in characters within which the banner line is created. The
default is 80, although 92 is a better fit if using the default banner font.
Coversheet file

The name of a file in %UNIQDIR%\media\fax\covers containing a page which


is sent at the front of outgoing documents which do not specify an explicit
coversheet.
Default_File_Type TEXT|HP
TEXT (the default) to assume that fax documents without an explicit type are
encoded as plain ASCII text; HP to assume that the encoding is HPs PCL5.
Device string

The connection to the output device; one of:


device

a direct connection to a local device, for


example /dev/ttyN.

NETWORK host port linger

a network connection via TCP/IP and a


terminal server to a remote device.

Dial_Prefix code...

A sequence of control codes sent to the modem prior to the fax_number, for
example to select an external telephone line. The default is T.
Incoming_Allowed NO
NO (the default) to ignore incoming documents.
Left_Margin number

The distance by which the text of an outgoing fax is shifted to the right,
establishing a blank left-hand margin. A value of 200 represents one inch; the
default is zero.

COLUMBUS OM INSTALLATION AND CONFIGURATION

491

492

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Line_Numbers YES|NO
YES to insert a number at the start of each line of text, ensuring that no material
is lost in transmission; NO (the default) otherwise.
Max_Resets number

The maximum number of consecutive attempts to reset the modem, for


monitoring purposes, before shutting down the server. The interval between
attempts is set by Reset_Interval. A value of zero or null invokes the default
of 6.
Medium FAX

The medium name which marks a queue entry as suitable for processing by this
server.
Medium_For_Print FAXPRINT

The medium name for queue entries which are automatically created to handle
printed confirmation of outgoing documents.
Out_Commands file

The name of a file in %UNIQDIR%\servers\server containing a sequence of


control codes which is sent to the modem to initialize it to transmit outgoing
faxes. The default is out_commands.
Outgoing_Allowed YES|NO
YES (the default) to process queue entries with the medium specified as FAX; NO
to ignore such entries.
Output_Filter command

An operating system command to post-process documents before they are


transmitted; otherwise, the documents are sent unchanged. The command can
include substitution of operating system variables ${name} and Columbus OM
variables %name, and must work as a pipe, reading data on stdin and writing
filtered data on stdout.
Pad_A4 YES|NO

To pad out short pages (that is, pages that are not completely filled) with spaces
to the full A4 page length (297mm), specify YES.
The default value is YES.
Print_Outgoing YES|NO
YES to create a queue entry, with the medium specified by Medium_For_Print,
to print a confirmatory copy of each outgoing document; NO (the default)
otherwise.
Reset_Interval number

The period (measured in minutes) between successive attempts to reset the


modem, for monitoring purposes, up to the maximum determined by
Max_Resets. A value of zero or null suppresses monitoring attempts.
Security_Level number

The security level to be applied to entries. The security levels that you can use
are stored in the seclev.tab file.

COLUMBUS OM INSTALLATION AND CONFIGURATION

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

Server server

The name of the server, which must be the same as the name of the folder
holding %UNIQDIR%\servers\server\config.tab.

COLUMBUS OM INSTALLATION AND CONFIGURATION

493

494

CHAPTER 18

Configuring a fax environment

Configuring a fax environment: Reference

COLUMBUS OM INSTALLATION AND CONFIGURATION

495

C H A P T E R 19

Chapter 19

Intelligent Office Printing


(IOP)

This section describes how to set up a Columbus OM Intelligent Office Printing


(IOP) deployment, and then use it to print and manage documents.
For more information about

See

the IOP features

Introduction to Intelligent Office


Printing on page 496

an overview of how to create an IOP


system

Configuring the IOP deployment on


page 500

how to access the IOP interface

Accessing the IOP administration


features on page 501

creating zones (groups of printers)

Working with zones on page 502

adding printers

Working with printers on page 506

displaying information about the queues Displaying the queues on page 521
managing servers

Monitoring servers on page 522

managing users

Managing users on page 515

creating business rules to control how


and where documents are printed

Working with enforcements on


page 517 and Working with diversions
on page 519

print and manage documents

Printing documents in an IOP


deployment on page 524

This section provides general information about setting up an IOP deployment for
zone printing, OnCall (pull) printing, and Scan2Print (quota-based scanning and
printing). Exact procedures depend on the hardware that you are using, and might
require more specific information from the hardware supplier or Macro 4.
To install an IOP deployment, see Installing a Columbus Intelligent Office
Printing (IOP) deployment on page 37.

COLUMBUS OM INSTALLATION AND CONFIGURATION

496

CHAPTER 19

Intel