Print Server Presentation and Operation Guide

The SAFE X3 print server processes the print requests coming from the different entities of one or more SAFE X3 solutions in a concurrent manner. Depending on global system availability, each print request saved at the server level is addressed in a dedicated print process. The entity that has submitted a request can ask the print server to either recover its current status, modify certain attributes, or delete it at any moment.

The following table shows the different sections of this document:

Installation / Uninstallation

Prerequisites

Before starting the installation of a print server, check the configuration requirements.

Installation

The installation program allows you to place the executable files, libraries, and other resources necessary for the correct execution of the print server in the folder of your choosing. The following tree structure is then created in the installation folder:

• Root folder: Contains all the server binary codes.
• Config folder:
  Contains a set of XML files. These files are automatically updated and maintained by the internal administration component of the server (Tools\AdxAdmin folder), which is run by a SAFE X3 administration console. Never update these files manually.
  These files are used:
  • During server startup (startup parameters).
  • Upon automatic creation of the ODBC data sources (external descriptions of the ODBC pilots).
  • During the implementation cycle (description parameters for the SAFE X3 solutions attached to the server).
• Data folder: Contains all the internal server cache files. It stores, among others, the "Crystal Report" reports coming from the SAFE X3 applications attached to the server.
• Log folder: Contains:
  • The activity log and the exception log ("*.log").
  • The recovery files used after an unexpected server shutdown ("*.bin").
  • The report for the server shutdown ("_AdxSrvShutdown_Inf.htm").
• Lan folder: Contains the localization files. If required, these files are updated during patch list installation.
• Temp folder: Collects the temporary files. It must be emptied regularly, depending on its volume.
  Caution: The server has to be stopped when emptying the folder.
• Tools folder: Contains the server administration components driven by the SAFE X3 administration console, as well as the associated utilities.

Uninstallation

Before uninstalling the print server, you first need to unpublish the SAFE X3 solutions attached to the print server by using the SAFE X3 administration console. You can then go to the control panel and click Add/Remove programs.

Configuration

Like the other Server components of a SAFE X3 solution, the print server is configured using the SAFE X3 administration console. Users should not manually modify the configuration files produced and updated by the administration console.

For more information, refer to the administration console documentation.

Startup setup

These parameters allow the configuration of the technical execution environment of the print server. They are stored in the adxeditionserverconfig.xml file in the Config folder. They include:

• Operating language code: Language used by the server to display messages. The server can print multilanguage reports regardless of this language code.
• TCP/IP listening port number: Port number the print server uses to listen to incoming connections.
• Size of the printing requests stack: Maximum number of requests that can be stacked by the print server. This parameter must be adjusted depending on the current maximum load of the print server.
• Maximum number of processes: Maximum number of print processes the print server is authorized to launch in parallel. This parameter must be adjusted depending on the average number of requests to be submitted and the global availability desired for the system.
  When the maximum number of processes is reached, the server stacks up the new print requests in the pending request stack. These requests are then processed when one of the print processes is available.
• Characteristics of the server activity and exception log files: Corresponds to a series of parameters that activate and, if needed, set a size for the server activity and exception log files.
  The sizing consists in setting the number of archive volumes for the log files, and their maximum size (in bytes). Each volume is physically associated with a file stored in the Log subfolder of the server. When the current volume has reached its maximum size (or when the server starts), the archive volumes are swapped to free a volume. It archives the current volume in the process.
• Setup of "Recovery" mode: Used to set the default management policy for the "Recovery" mode when the server quits unexpectedly. For more details on the "Recovery" mode, refer to Server startup / stop.
• Shared memory size: Describes how the print server uses shared memory segments to exchange data with its print processes. The maximum size of the shared memory segments must be set during server startup (you cannot dynamically extend them).
  If the size allocated at startup is not sufficient for the standard use context, the print server displays an error 266. In this case, you need to stop the server, modify the value of this parameter (VPALLOC) through the SAFE X3 administration console, and restart the server.
  The default value assigned to this parameter ("40") should be high enough to avoid this type of error under normal conditions of use.

Parameters for the description of the attached SAFE X3 solutions

The print server can only process print requests coming from a SAFE X3 technology application that belongs to a published solution. The parameters used to describe the SAFE X3 solutions attached to the print server are stored in the adxeditionserversolutions.xml file in the Config subfolder. This file is updated by the SAFE X3 administration console after the publication of a solution.

The tree structure of the file describes a solution profile. This notion is reserved for future use. Currently, only the "ADMIN" profile code is used.

Each profile has 1 to n solutions, and each solution contains:

• The applications associated with the solution.


• The parameters for the connection to the SADFSQ file server of the solution (including the authentication mode that needs to be used).


• The parameters for the connection to the database server of the solution.

Advanced settings

To be able to run a print server Windows service with a non-administrator user, you can add or modify the REG_DWORD registry entry with a suitable value:

• Availability: EDT.208 or higher
• Description: controls the print server behavior regarding TCP port and ODBC datasource management
• Subkey: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ADONIX\SRVIMP\0,1,5,0\GENERAL
  • Entry: AdvancedSrvOpt
  • Value Type: REG_DWORD, number
  • Valid values range: [0-3]
    • 0: The TCP port is registered in the "etc/services" file, and the ODBC source is created as a "System" DSN.
    • 1: The TCP port is no longer registered in the "etc/services" file.
    • 2: The ODBC source is created as a "User" DSN.
    • 3: Combination of values 1 and 2. With this setting, the print server Windows service can be run with a non-administrator user.

    The default value is 0.
    
    Caution: You must create the registry sub key with value 3 before you configure the component through the administration console in order to allow the print server to run with a non-administrator user.

  
  

To be able to turn on debug mode for the Crystal Report U212Ltext.dll embedded functions, you can add or modify the REG_SZ registry entry with a suitable value :

• Availability: EDT.102 or higher
• Description: Turns on/off the debug mode for the Crystal Report U212Ltext.dll embedded functions.
• Subkey: HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\ADONIX\SRVIMP\0,1,5,0\REPORT
  • Entry: U2LTEXT_TraceMode
  • Value Type: REG_SZ, string
  • Valid values Range: [ON-OFF]
    • OFF: Debug is turned off
    • ON: Debug is turned off, and the trace file is generated in "%TEMP%\u212ltext.log"

    The default value is OFF.

  
  

Server startup / stop

A print server can be started in "Console" mode or in "Windows service" mode. The function of the server is strictly identical in both modes. The only difference is that in "Console" mode, server activity is displayed on the screen in the Windows panel.

During the first server configuration from the SAFE X3 administration console, the console automatically creates a "Windows Service", associated with the server by default. You can start and stop this service from the administration console. You can also use standard tools in the Windows system to administer and control the service.

Note that the print server startup options described below are available both in "Console" and "Windows Service" modes.

• Launch of the server in Recovery mode: "/recovery:status":
  In case a print server unexpectedly shuts down during processing, the stack of print requests that are pending or in progress is serialized in a binary file. The content of this file can be reviewed in the shutdown report stored in the log subfolder ("_AdxSrvShutdown_Inf.htm" file).
  The "Recovery" mode is used to tell the server to start loading the previously stored stack of requests before starting the listening service. The print requests that were stopped during the involuntary shutdown are automatically recovered and submitted to the print system. When this option is activated, the recovered requests are stored in the activity log of the server.Note that this option can be used to force the "Recovery" policy set up in the administration console:
  • Set the status value to 1 to force the activation of the "Recovery" mode.
  • Set the status value to 0 to force the deactivation of the "Recovery" mode".
• Activation of the log file: "/d":
  This option produces a file ("AdxSrvlmp_Trace.log") that logs the activity of the print server and of the printing processes that are launched. This file is stored in the temporary folder of the print server.
  This option must be used in case of problems to facilitate the analysis and correction of the incidents submitted to the Sage customer care services.
• Launch in console mode: "/noservice":
  This option is used to force the print server to run in "Console" mode, instead of "Windows service" mode.
• Deactivation of the control and configuration of the ODBC sources: "/noodbc":
  The print server uses ODBC data sources to connect to the data servers of the SAFE X3 solutions linked to it. When you launch the server with this option, it does not manage the creation, control and configuration of these data sources. As a result, the user has to create and correctly configure the ODBC data sources, based on the characteristics of the different SAFE X3 solutions attached to the server.
• Launch using a configuration profile different from the default profile: "/cfg:cdprofil": Reserved for future use.
• Deletion of a previously created Windows service: "/rmsvc:cdservice":
  The print server automatically stops after deleting the required service.
• Display of the print server version: "/v":
  Available in Console mode only.

Monitoring

You can follow the server activity by consulting the activity log file, the Windows Events Viewer, or by accessing the "Print Monitor" function available in each SAFE X3 folder, even if the server has not been started with the "/d" log file option.

Monitoring window

Connect to the print monitor function (PSIMP) in Classic mode to display this window. Enter the name and port of the print server to display data related to the server activity.

From this screen, you can:

• View the server startup parameters (Configuration section)
• View the current TCP/IP sessions (Clients connected section)
• View and modify the parameters associated with the requests that are either stacked or in progress (Tasks section)

Activity log file and exception log file

The activity log file records "saving", "submission", "termination", and "deletion" events related to a print request. The exception log file records all errors and anomalies detected by the server.

These log files are activated and set up by the server administration console. Note that the exception log file automatically inherits the setup of the activity log file. Refer to Configuration for more information.

Windows Events Viewer

All the information, warnings and error messages issued by the print server or one of the print processes are displayed in the Windows Events Viewer.

In case of incidents, see the Events Viewer to establish a detailed diagnosis (AdxSrvImp and AdxImp sources).

Technical architecture

The diagram below shows the simplified technical architecture of the print server.

Principles

The print server is a "multiprocessing" server which maintains and controls a pool of specialized processes. The production of Crystal Report reports is the only function of these processes. The server manages the preparation and formatting of all the information necessary for the correct production of printouts and the execution of the print processes.

The main logical components of the server are described below:

• TCP/IP listening service: Whenever a client sets up a TCP/IP connection to the print server service, it creates a "Client Thread" dedicated to the management of the requests coming from this client. There are as many "Client Threads" as there are connected clients.
• Technological services: These services ensure the integrity of the server, and mainly control the access to shared resources. A specialized technical service also manages the creation, configuration, and control of the ODBC data sources (Oracle or SQLServer) necessary for the print processes to access the database servers of the attached SAFE X3 solutions.For Oracle data sources, the print server supports versions 9, 10, and 11 of the Oracle Net client, and 'Wire Protocol' type ODBC Oracle drivers. The user account under which the print server is launched requires sufficient rights and privileges to create the ODBC system data sources and the Oracle Net aliases. The user can manually create the ODBC data sources by using startup option "/noodbc" (see the print server startup options), if required.
• Basic services: The print server processes basic functional services. The main ones are:
  • Saving and formatting the parameters associated with a print request
  • Printer selection
  • Printer configuration
  • Monitoring requests in progress
• File transfer: Managing a print request coming from a SAFE X3 application often requires to load files stored in this application (for example, the ".rpt" report file). The print server operates with SAFE X3 (SADFSQ) file servers. It establishes a TCP/IP connection with the corresponding application servers associated with it to communicate with them.
• Print processes: When the print server finishes preparing a print request, and depending on system availability, it launches a print process that manages the final production of the report. The main task of this print process is to initialize and call the Crystal Report print engine which produces the requested report.
  A print process then accesses the print server shared memory to determine if the server has pending print requests. If it is the case, it will process the first eligible request. If there are no eligible or pending requests, the print process ends automatically.
  The maximum number of concurrent print processes for a print server can be set up using the SAFE X3 administration console (refer to the startup parameters).
• Shared memory: The print server loads several segments of shared memory to exchange information with the print processes that it is able to create (Inter-processes shared memory). Access to these segments is carried out in an exclusive manner, based on the interprocess synchronization objects of mutual exclusion type.

Printer management and error lists

Follow the rules below so that the print server can carry out the printing operation correctly:

• If the print server is started in "Windows service" mode, you need to indicate a different startup account from the "Local system" account so that the print server can access one of the printers in your organization. No printer is attached to the "Local system" Windows account.
• At least one printer must be set up on the user account used to start the print server (in "Console" mode or in "Windows service" mode).
• The print server can only address printers that are "visible" and "accessible" to the user account with which the server was started (in "Console" mode or in Windows service" mode).
• When printing in PDF format, the parameters relating to the document size are inherited from the default paper size of the printer associated with the user account with which the server was started (in "Console" mode or in Windows service" mode).

Error codes and messages

The message associated with an error code refers to the following:

• The error code
• The type of message (64: information; 48: warning; 16: error)
• The function the error came from
• The context (in the form of a character string)

The error codes generated by the print server are referenced below:

Print server error codes

Error codes in the cache management module

Error codes for the Windows service management module

Error codes of the SAFE X3 solutions management module

Error codes in the ODBC management module